Metadata-Version: 2.4
Name: agentskill-cli
Version: 1.0.1
Summary: Universal AI Skill Manager for GitHub Copilot, Claude, Cursor
Author: Parth
License: MIT
Keywords: ai,copilot,claude,cursor,skills,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9.0
Dynamic: license-file

# AgentSkill 🛠️

[![PyPI version](https://badge.fury.io/py/agentskill-cli.svg)](https://pypi.org/project/agentskill-cli/)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Universal AI Skill Manager** — Create, manage, and share coding rules for AI assistants like GitHub Copilot, Claude Code, and Cursor.

---

## 🎯 What is AgentSkill?

AgentSkill is a CLI tool that helps you create and manage **skills** (coding rules and best practices) that AI coding assistants follow when helping you write code.

### The Problem
- You want AI to follow your coding standards consistently
- You have to repeat the same instructions in every project
- Different AI tools (Copilot, Claude, Cursor) need different file formats
- Sharing coding standards with your team is difficult

### The Solution
AgentSkill lets you:
- ✅ Create skills once, use everywhere
- ✅ Install skills in any project with one command
- ✅ Auto-detect and support multiple AI tools
- ✅ Share skills with your team via export/import
- ✅ Update skills across all projects instantly

---

## 🚀 Installation

```bash
pip install agentskill-cli
```

After installation, both `agentskill` and `ask` (short) commands are available.

---

## 📖 Use Cases

### 1. Enforce Coding Standards
Create a skill to enforce your team's coding standards:
```bash
agentskill create python-standards -l python
```
Edit the skill to add your rules:
```markdown
## Python Standards
- Use type hints for all function parameters and return values
- Use `pathlib` instead of `os.path`
- Prefer f-strings over .format()
- All functions must have docstrings
- Maximum line length: 88 characters (Black formatter)
```

### 2. Framework-Specific Rules
Create skills for specific frameworks with built-in templates:
```bash
# React component rules
agentskill create react-rules -l javascript -f react

# Django API rules  
agentskill create django-api -l python -f django

# Flutter widget rules
agentskill create flutter-app -l dart -f flutter
```

### 3. Project-Specific Instructions
Create skills for specific project requirements:
```bash
agentskill create myproject-rules
```
Add project-specific rules:
```markdown
## MyProject Rules
- Use PostgreSQL for all database operations
- All API endpoints must be versioned (/api/v1/...)
- Use Redis for caching
- JWT tokens for authentication
- Follow company naming conventions
```

### 4. Team Collaboration
Share skills across your team:
```bash
# Export skill
agentskill export react-rules
# Creates: react-rules.skill.zip

# Team member imports
agentskill import react-rules.skill.zip
```

### 5. Multi-Project Consistency
Install the same skill in multiple projects:
```bash
cd ~/project-1
agentskill install python-standards

cd ~/project-2  
agentskill install python-standards

cd ~/project-3
agentskill install python-standards
```

Update skill once, sync everywhere:
```bash
agentskill edit python-standards  # Make changes
agentskill update python-standards  # Sync to all projects
```

---

## 📋 Quick Start

### Step 1: Create a Skill
```bash
agentskill create my-rules -l python -f django
```

### Step 2: Edit the Skill (optional)
```bash
agentskill edit my-rules
```

### Step 3: Install in Your Project
```bash
cd /path/to/your/project
agentskill install my-rules
```

### Step 4: Done!
AI assistants will now follow your rules when working in this project.

---

## 🔧 Commands

| Command | Short | Description |
|---------|-------|-------------|
| `agentskill create <name>` | `ask create` | Create new skill |
| `agentskill install <name>` | `ask install` | Install skill in current project |
| `agentskill list` | `ask list` | Show all skills |
| `agentskill show <name>` | `ask show` | View skill details |
| `agentskill edit <name>` | `ask edit` | Open skill in editor |
| `agentskill update <name>` | `ask update` | Sync skill to all projects |
| `agentskill delete <name>` | `ask delete` | Remove skill |
| `agentskill export <name>` | `ask export` | Export skill as zip |
| `agentskill import <zip>` | `ask import` | Import skill from zip |
| `agentskill init` | `ask init` | Create AI folders in project |
| `agentskill where` | `ask where` | Show skills storage location |

---

## 🎨 Creating Skills

### Basic Skill
```bash
agentskill create my-rules
```

### With Language & Framework Templates
```bash
# Python + Django
agentskill create django-api -l python -f django

# JavaScript + React
agentskill create react-component -l javascript -f react

# TypeScript + Next.js
agentskill create nextjs-app -l javascript -f nextjs

# Dart + Flutter
agentskill create flutter-widget -l dart -f flutter

# Go + Gin
agentskill create go-api -l go -f gin

# Rust + Actix
agentskill create rust-api -l rust -f actix
```

### Supported Templates

| Language | Frameworks |
|----------|------------|
| Python | django, fastapi, flask |
| JavaScript/TypeScript | react, nextjs, node |
| Dart | flutter |
| Go | gin, fiber |
| Rust | actix, axum |

---

## 📁 Skill Structure

```
my-skill/
├── SKILL.md          # Main instructions (loaded by AI)
├── skill.yaml        # Metadata (language, framework, version)
├── instructions.md   # Legacy format for compatibility
├── scripts/          # Helper scripts
├── references/       # Additional documentation
│   └── examples.md   # Code examples
└── assets/           # Templates, boilerplate code
```

### SKILL.md Format
```markdown
---
name: my-skill
description: 'Rules for Python Django development'
---

# My Skill

## When to Use
- Working on Django projects
- Building REST APIs

## Rules
- Use class-based views for complex logic
- Always use Django ORM
- Keep business logic in services

## Examples
Check `./references/examples.md` for code examples.
```

---

## 🔌 Supported AI Tools

| Tool | Folder | Auto-Detected |
|------|--------|---------------|
| GitHub Copilot | `.github/skills/` | ✅ |
| Claude Code | `.claude/skills/` | ✅ |
| Cursor | `.cursor/skills/` | ✅ |

### Install for Specific Tool
```bash
# GitHub Copilot only
agentskill install my-skill -t copilot

# Claude only
agentskill install my-skill -t claude

# Cursor only
agentskill install my-skill -t cursor

# All tools
agentskill install my-skill -t all
```

---

## 🏗️ How It Works

```
┌─────────────────────────────────────────────────────────────────┐
│                        AgentSkill Flow                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. CREATE                    2. STORE                          │
│  ┌─────────────────┐         ┌─────────────────┐               │
│  │ agentskill      │         │ ~/.agentskill/  │               │
│  │ create my-skill │ ──────▶ │   skills/       │               │
│  └─────────────────┘         │     my-skill/   │               │
│                              │       SKILL.md  │               │
│                              └─────────────────┘               │
│                                      │                          │
│  3. INSTALL                          │                          │
│  ┌─────────────────┐                 │                          │
│  │ agentskill      │                 ▼                          │
│  │ install my-skill│         ┌─────────────────┐               │
│  └─────────────────┘         │ your-project/   │               │
│                              │   .github/      │               │
│         COPY ───────────────▶│     skills/     │               │
│                              │       my-skill/ │               │
│                              └─────────────────┘               │
│                                      │                          │
│  4. AI READS                         ▼                          │
│  ┌─────────────────┐         ┌─────────────────┐               │
│  │ GitHub Copilot  │◀────────│ Follows your    │               │
│  │ Claude Code     │         │ coding rules!   │               │
│  │ Cursor          │         └─────────────────┘               │
│  └─────────────────┘                                            │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## 💡 Tips & Best Practices

### Writing Effective Skills
1. **Be Specific**: Use clear, actionable rules
2. **Add Examples**: Include code examples in `references/examples.md`
3. **Keep It Focused**: One skill per domain/framework
4. **Use Trigger Words**: AI finds skills by matching keywords in descriptions

### Skill Organization
```bash
# Recommended skill structure
agentskill create company-standards     # General company rules
agentskill create python-backend        # Python backend rules
agentskill create react-frontend        # React frontend rules
agentskill create api-design            # API design rules
```

### Team Workflow
```bash
# 1. Create shared skills repository
mkdir team-skills && cd team-skills
git init

# 2. Export skills
agentskill export python-standards
agentskill export react-rules

# 3. Commit and push
git add .
git commit -m "Add team skills"
git push

# 4. Team members import
git clone <repo>
agentskill import python-standards.skill.zip
agentskill import react-rules.skill.zip
```

---

## 🔄 Updating Skills

### Edit and Update
```bash
# Edit the skill
agentskill edit my-skill

# Update in all projects where it's installed
agentskill update my-skill
```

### Version Tracking
Skills have version numbers in `skill.yaml`:
```yaml
name: my-skill
version: 1.0
```

---

## 🗑️ Managing Skills

### Delete a Skill
```bash
agentskill delete my-skill

# Force delete (no confirmation)
agentskill delete my-skill -f
```

### View Storage Location
```bash
agentskill where
# Output: ~/.agentskill/skills/
```

---

## 📦 Sharing Skills

### Export
```bash
agentskill export my-skill
# Creates: my-skill.skill.zip
```

### Import
```bash
agentskill import my-skill.skill.zip
```

---

## 📄 License

This project is licensed under the MIT License.

---

## 🙏 Acknowledgments

- Inspired by the need for consistent AI-assisted coding
- Built with [Typer](https://typer.tiangolo.com/) for the CLI
- Supports GitHub Copilot, Claude Code, and Cursor

---

## 📧 Author

- **Parth Kher**

---

Made with ❤️ for developers who want AI to follow their rules.
