add-skill — команда для Claude Code: добавить скилл в проект
Команда add-skill для копирования скилла в проект с проверкой названия и автогенерацией README. Сэкономит время на валидацию и документацию.
MIT ★ 2 707 обновлён 2026-03-05
.claude/commands/add-skill.mdЧто делает add-skill
Команда /add-skill берёт скилл из исходной папки, копирует его в директорию skills/ и проверяет, что имя папки совпадает с полем name: в SKILL.md и оба написаны в kebab-case. Если скилл приехал с нарушениями — команда предложит исправить: переименовать папку или обновить фронтматтер.
Если README.md не найден, команда запускает подагента, который автоматически создаёт подробную документацию на основе SKILL.md — описание, примеры использования, предусловия и как работает. После этого добавляет запись о скилле в marketplace.json с выбранной категорией и обновляет таблицу доступных скиллов в главном README.
Работает с Claude Code, Codex, GitHub Copilot и Gemini CLI — каждый получает свой файл команды в нужную директорию.
Какие задачи решает
- скопировать скилл в проект с валидацией структуры
- убедиться, что имена папки и SKILL.md совпадают
- сгенерировать README для скилла из фронтматтера
- добавить скилл в маркетплейс с категорией
- обновить список доступных скиллов в документации
Примеры запросов агенту
- Добавь скилл из
/home/leo/workspace/softaworks/projects/claude-plugins/plugins/planning/skills/spec-interview - /add-skill ~/.claude/skills/my-skill
- Добавь скилл из другого проекта:
/add-skill ~/workspace/other-project/skills/awesome-skill
Как установить add-skill
Вручную: положить файлы
.claude/commands/add-skill.mdВызов — /add-skill. Для всех проектов — ~/.claude/commands/
Вручную: положить файлы
~/.codex/prompts/add-skill.mdВызов — /prompts:add-skill. В Codex этот формат помечен устаревшим, замена — скиллы
Вручную: положить файлы
.github/prompts/add-skill.prompt.mdВручную: положить файлы
.gemini/commands/add-skill.tomlGemini хранит команды в TOML: текст запроса — в поле prompt
Вопросы об add-skill
Как установить add-skill в Claude Code?
Добавьте файл команды в папку проекта: скопируйте содержимое в .claude/commands/add-skill.md. Если папка не существует, создайте её. После этого команда /add-skill будет доступна в Claude Code.
Что делает add-skill?
Команда копирует скилл из исходной папки в проект, проверяет, что название папки и поле name: в SKILL.md совпадают и написаны в kebab-case, создаёт README если его нет, и регистрирует скилл в маркетплейсе.
Что такое kebab-case и почему это важно?
Kebab-case — это формат «слово-слово» только с маленькими буквами, цифрами и дефисами (например, my-skill). Команда проверяет это, потому что такой формат нужен для единообразия: если имена папок и в конфиге разные, скилл не активируется корректно.
Исходный текст
add-skill.md · MIT
---
description: Add a skill to the project with validation and README generation
argument-hint: <source-path>
---
# Add Skill
Copy a skill from a source path to the project, verify naming consistency, and generate README.md if missing.
## Usage
```
/add-skill <source-path>
```
**Arguments:**
- `<source-path>` - Path to the skill directory to add (required)
**Examples:**
```
/add-skill ~/.claude/skills/my-skill
/add-skill ~/workspace/other-project/skills/awesome-skill
/add-skill /home/leo/workspace/softaworks/projects/claude-plugins/plugins/planning/skills/spec-interview
```
## Workflow
### 1. Validate Source Path
Check that the source path exists and is a directory:
```bash
if [ -d "<source-path>" ]; then
echo "Source path exists"
else
echo "Error: Source path does not exist or is not a directory"
exit 1
fi
```
If source path is invalid, stop and report the error to the user.
### 2. Extract Skill Name
Get the skill name from the source path (basename of the directory):
```bash
basename <source-path>
```
Example: `/path/to/my-skill` → `my-skill`
Store this as the skill name for the rest of the workflow.
### 3. Copy Skill to Project
Copy the entire skill directory to `skills/`:
```bash
cp -r <source-path> skills/
```
Report to user: "✅ Copied skill to skills/[skill-name]"
### 4. Verify Folder Name is Kebab-Case
Check that the folder name follows kebab-case convention:
- Only lowercase letters, numbers, and hyphens
- No underscores, spaces, or uppercase letters
**Regex pattern:** `^[a-z0-9]+(-[a-z0-9]+)*$`
Use Bash to check:
```bash
skill_name="[skill-name]"
if [[ $skill_name =~ ^[a-z0-9]+(-[a-z0-9]+)*$ ]]; then
echo "Folder name is valid kebab-case"
else
echo "Warning: Folder name is not kebab-case"
fi
```
If invalid, warn the user but continue (we'll check SKILL.md next).
### 5. Verify SKILL.md Exists and Read Frontmatter
Check for SKILL.md in the copied skill directory:
```bash
ls skills/[skill-name]/SKILL.md
```
If SKILL.md doesn't exist:
- Error and stop: "❌ Error: No SKILL.md found in skills/[skill-name]"
- Suggest: "Please ensure the source directory contains a valid SKILL.md file"
If SKILL.md exists, read it with the Read tool to extract the frontmatter.
**Extract the `name:` field from frontmatter:**
The frontmatter is between the first two `---` markers:
```yaml
---
name: skill-name-here
description: ...
---
```
Parse the YAML and extract the value of the `name:` field.
### 6. Verify Naming Consistency
Compare:
1. **Folder name:** `[skill-name]` (from basename)
2. **SKILL.md name field:** `[name-from-frontmatter]`
**Check 1: Both are kebab-case**
Both should match the regex: `^[a-z0-9]+(-[a-z0-9]+)*$`
If either is not kebab-case:
- Report: "⚠️ Naming issue detected:"
- If folder is not kebab-case: " - Folder name '[folder]' is not kebab-case"
- If name field is not kebab-case: " - SKILL.md name '[name]' is not kebab-case"
**Check 2: Folder name matches name field**
If `folder-name` != `name-from-frontmatter`:
- Report: "⚠️ Name mismatch detected:"
- "Folder name: [folder-name]"
- "SKILL.md name: [name-from-frontmatter]"
- "These should match for consistency"
**Ask user for fix:**
If there's a mismatch or non-kebab-case naming, ask:
"Would you like me to fix the naming inconsistency? I can:
1. Rename the folder to match SKILL.md name field
2. Update SKILL.md name field to match folder name
3. Leave as-is"
Based on user choice:
- **Option 1:** Use `mv` to rename the folder
- **Option 2:** Use Edit tool to update SKILL.md frontmatter
- **Option 3:** Continue without changes
Report the action taken.
### 7. Check for README.md
Check if README.md exists in the skill directory:
```bash
ls skills/[skill-name]/README.md
```
**If README.md exists:**
- Report: "✅ README.md already exists"
- Skip to step 8
**If README.md does NOT exist:**
- Report: "📝 No README.md found. Creating comprehensive README..."
- Proceed to spawn sub-agent
### 8. Spawn Sub-Agent to Create README.md (if missing)
Use the Task tool to spawn a general-purpose sub-agent with this prompt:
```
For the skill at /home/leo/workspace/softaworks/projects/agent-skills/skills/[skill-name]:
1. Read the SKILL.md file completely
2. Analyze what the skill does, how it works, and when to use it
3. Create a comprehensive README.md that explains:
- **Purpose**: What the skill does and why it exists
- **When to Use**: Specific scenarios and trigger phrases
- **How It Works**: Step-by-step explanation of the workflow
- **Key Features**: Main capabilities and highlights
- **Usage Examples**: Practical examples showing how to use it
- **Prerequisites** (if any): Required tools, dependencies, or setup
- **Output** (if applicable): What the skill produces
- **Best Practices** (if applicable): Tips for getting the best results
The README should be user-friendly, comprehensive, and help users understand the skill's purpose and functionality in detail.
Write the README.md to: skills/[skill-name]/README.md
```
**Agent parameters:**
- `subagent_type: "general-purpose"`
- `description: "Create README for [skill-name]"`
Wait for the agent to complete, then report success.
### 9. Add Plugin Entry to marketplace.json
Add a new plugin entry to `.claude-plugin/marketplace.json` for the new skill.
**Read the marketplace.json file** to get current plugins array.
**Ask user for category** using AskUserQuestion:
"Which category does this skill belong to?"
Options:
- ai-tools (AI-powered tools)
- meta (Skills for building skills/commands/plugins)
- documentation (Writing, diagrams, docs)
- design-frontend (UI/UX, React, styling)
- development (Database, dependencies, refactoring)
- planning (Requirements, implementation planning)
- professional (Communication, feedback)
- testing (QA, test planning)
- git (Version control)
- utilities (General tools)
**Create the plugin entry:**
```json
{
"name": "[skill-name]",
"description": "[description from SKILL.md frontmatter]",
"source": "./",
"strict": false,
"skills": ["./skills/[skill-name]"],
"category": "[selected-category]",
"keywords": ["[category]", "[relevant]", "[tags]"]
}
```
**Insert the plugin entry** into the plugins array in marketplace.json, keeping entries grouped by category.
Use the Edit tool to add the new entry before the agents section (after the last skill entry for the selected category, or at the end of skills if it's a new category).
Report: "✅ Added plugin entry to marketplace.json"
### 10. Update Available Skills Table in README.md
Update the "Available Skills" table in README.md to include the new skill.
**Read README.md** to find the Available Skills table.
**Find the rows for the skill's category** and add the new skill in the appropriate position.
For example, if adding a skill to "🤖 AI Tools" category:
```markdown
| 🤖 AI Tools | [new-skill](skills/new-skill/README.md) | Description here |
```
Use the Edit tool to add the new row in the correct category section.
Report: "✅ Updated Available Skills table in README.md"
### 11. Final Report
After all steps are complete, report to the user:
```
✅ Skill '[skill-name]' added successfully!
📋 Summary:
- Source: <source-path>
- Destination: skills/[skill-name]
- SKILL.md: ✅ Valid
- Naming: [✅ Consistent / ⚠️ Fixed / ⚠️ Inconsistent]
- README.md: [✅ Exists / 📝 Created]
- marketplace.json: ✅ Plugin entry added
- Available Skills table: ✅ Updated
Next steps:
1. Review the skill at skills/[skill-name]
2. Commit the changes
```
## Error Handling
**Source path doesn't exist:**
- Stop immediately
- Error: "❌ Source path '<source-path>' does not exist"
**Source path is not a directory:**
- Stop immediately
- Error: "❌ Source path '<source-path>' is not a directory"
**No SKILL.md in source:**
- Stop after copy
- Error: "❌ No SKILL.md found in skills/[skill-name]"
- Suggest checking the source directory
**SKILL.md has no frontmatter:**
- Warn user
- Warning: "⚠️ SKILL.md has no frontmatter with name field"
- Ask if user wants to continue anyway
**Naming mismatch detected:**
- Warn user with details
- Offer to fix (rename folder or update frontmatter)
- Don't proceed until user decides
**README.md creation fails:**
- Report the failure
- Suggest: "You may need to create README.md manually for this skill"
- Continue anyway (skill is still added)
## Tools to Use
- **Bash** - Validate paths, copy directories, check naming
- **Read** - Read SKILL.md frontmatter, marketplace.json, README.md
- **Edit** - Fix SKILL.md name field, update marketplace.json, update README.md
- **Task** - Spawn sub-agent to create README.md
- **AskUserQuestion** - Ask about fixing naming inconsistencies, ask for category
## Success Criteria
- Skill copied to skills/ directory
- Folder name and SKILL.md name field are consistent and kebab-case
- README.md exists (either copied or created by sub-agent)
- Plugin entry added to marketplace.json
- Available Skills table in README.md updated
- User informed of all actions taken
- Clear next steps provided
© softaworks · MIT · softaworks/agent-toolkit