/add-skill

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:

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):

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/`:

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:

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:

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:

---
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:

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:**

{
  "name": "[skill-name]",
  "description": "[description