gh-hyperskill-claude-code-marketplace-plugins-plugin-development/commands/add-skill.md

description: Add a new Skill to the current plugin with proper structure argument-hint: [skill-name] ["description"]

Add Skill

Create a new Skill folder with SKILL.md and supporting directories.

Arguments

• $1 (required): Skill name in kebab-case (e.g., code-review)
• $2 (optional): Description of when to use this Skill in quotes (e.g., "Use when reviewing code or PRs")
• --plugin=<plugin-name> (optional): Specify which plugin to add the skill to

Usage:

# From within a plugin directory, with description
/plugin-development:add-skill code-review "Use when reviewing code or analyzing pull requests"

# Without description (uses default)
/plugin-development:add-skill code-review

# From marketplace root, specifying plugin
/plugin-development:add-skill code-review "Use when reviewing code" --plugin=plugin-development

Prerequisites

• Must be run from either:
  • A plugin root directory (containing .claude-plugin/plugin.json), OR
  • A marketplace root directory (containing .claude-plugin/marketplace.json)
• skills/ directory will be created if needed

Instructions

Validation

IMPORTANT: When running test commands for validation (checking directories, files, etc.), use require_user_approval: false since these are read-only checks.

1. Detect context and target plugin (output thoughts during this process):

   a. Check if we're in a plugin directory:

   • Look for .claude-plugin/plugin.json in current directory
   • Output: "Checking for plugin directory..."
   • If found:
     • Output: "Found plugin.json - using current directory as target plugin"
     • Use current directory as target plugin
   • If not found:
     • Output: "Not in a plugin directory, checking for marketplace..."

   b. If not in plugin directory, check if we're in marketplace root:

   • Look for .claude-plugin/marketplace.json in current directory
   • If found:
     • Output: "Found marketplace.json - this is a marketplace root"
     • This is a marketplace root
   • If not found:
     • Output: "Error: Neither plugin.json nor marketplace.json found"
     • Show error and exit

   c. If in marketplace root, determine target plugin:

   • Check if --plugin=<name> argument was provided
   • If yes:
     • Output: "Using plugin specified via --plugin argument: "
     • Use specified plugin name
   • If no:
     • Output: "No --plugin argument provided, discovering available plugins..."
     • Discover available plugins and prompt user

   d. Discover available plugins (when in marketplace root without --plugin):

   • Output: "Reading marketplace.json..."
   • Read .claude-plugin/marketplace.json
   • Extract plugin names and sources from plugins array
   • Output: "Found [N] plugin(s) in marketplace"
   • Alternative: List directories in plugins/ directory
   • Present list to user: "Which plugin should I add the skill to?"
   • Options format: 1. plugin-name-1 (description), 2. plugin-name-2 (description), etc.
   • Wait for user selection
   • Output: "Selected plugin: "

   e. Validate target plugin exists:

   • Output: "Validating plugin '' exists..."
   • If plugin specified/selected, verify plugins/<plugin-name>/.claude-plugin/plugin.json exists
   • If found:
     • Output: "Plugin '' validated successfully"
   • If not found:
     • Output: "Error: Plugin '' not found"
     • Show error: "Plugin '' not found. Available plugins: [list]"

   f. If neither plugin.json nor marketplace.json found:

   • Show error: "Not in a plugin or marketplace directory. Please run from a plugin root or marketplace root."

2. Validate arguments:

   • $1 (skill name): Not empty, kebab-case format (lowercase with hyphens), no spaces or special characters, max 64 characters
   • $2 (description): Optional. If not provided, use default: "$1 functionality for plugin development". If provided, must be max 1024 characters and should include both what the Skill does and when to use it

3. Set working directory:

   • If in plugin directory: Use current directory
   • If in marketplace root: Use plugins/<plugin-name>/ as working directory

Create Skill Structure

Note: All paths below are relative to the target plugin directory (determined in validation step).

1. Ensure <plugin-dir>/skills/ directory exists (create if needed, use require_user_approval: false)
2. Create skill directory: <plugin-dir>/skills/$1/
3. Create supporting directories:
   • <plugin-dir>/skills/$1/schemas/
   • <plugin-dir>/skills/$1/templates/
   • <plugin-dir>/skills/$1/examples/
   • <plugin-dir>/skills/$1/best-practices/

Create SKILL.md

Create <plugin-dir>/skills/$1/SKILL.md with this template:

---
name: $1
description: $2
---

# $1 Skill

[Brief introduction to what this Skill provides and its purpose]

## When to Activate

This Skill activates when:
- [Condition 1: e.g., user mentions specific keywords]
- [Condition 2: e.g., working with specific file types]
- [Condition 3: e.g., certain files are present]

## Capabilities

What this Skill can help with:

1. [Capability 1]
2. [Capability 2]
3. [Capability 3]

## Quick Links (Progressive Disclosure)

- [Schemas](./schemas/)
- [Templates](./templates/)
- [Examples](./examples/)
- [Best Practices](./best-practices/)

## Workflow

How this Skill operates:

1. **Analyze**: [What to read and understand]
2. **Propose**: [What actions to suggest]
3. **Execute**: [How to carry out the work]
4. **Validate**: [How to verify success]

## Common Patterns

### Pattern 1: [Name]

[Description of common usage pattern]

### Pattern 2: [Name]

[Description of another pattern]

## Notes

- [Important consideration 1]
- [Important consideration 2]
- [Links to other Skills or commands if applicable]

Update plugin.json (if needed)

IMPORTANT: Only needed if using custom (non-standard) paths.

• Standard setup (skills in skills/ directory): No changes to plugin.json needed
• Custom paths: Skills cannot be specified with custom paths (must use standard skills/ directory)

Provide Feedback

After creating the Skill:

✓ Created <plugin-name>/skills/$1/SKILL.md
✓ Created supporting directories:
  - <plugin-name>/skills/$1/schemas/
  - <plugin-name>/skills/$1/templates/
  - <plugin-name>/skills/$1/examples/
  - <plugin-name>/skills/$1/best-practices/

Plugin: <plugin-name>
Skill: $1
Description: $2

Next steps:
1. Edit <plugin-name>/skills/$1/SKILL.md with specific guidance
2. Key frontmatter fields:
   - name: Must match directory name ($1)
   - description: When to use this Skill (include trigger conditions, max 1024 chars)
   - allowed-tools: (Optional) Restrict tools available to this Skill. If omitted, Claude asks for permission
3. Add support files:
   - schemas/: Document data formats
   - templates/: Provide reusable templates
   - examples/: Show usage examples
   - best-practices/: Detailed guidance
4. Keep SKILL.md concise (< 500 lines), use progressive disclosure
5. Test with /plugin-development:test-local

Claude will auto-discover this Skill when the plugin is installed.

Example

Input:

/plugin-development:add-skill code-review "Use when reviewing code or analyzing pull requests"

Arguments:

• $1 = code-review
• $2 = Use when reviewing code or analyzing pull requests

Result:

• Creates skills/code-review/ directory
• Creates SKILL.md with frontmatter name: code-review
• Frontmatter description: "Use when reviewing code or analyzing pull requests"
• Creates supporting directories (schemas/, templates/, examples/, best-practices/)
• Ready to add guidance and reference files

For complete details on Skills, see:

• Agent Skills documentation
• Agent Skills overview
• Skills best practices

Skill Frontmatter

Required Fields

---
name: skill-name          # Must match directory, kebab-case
description: When and how to use this Skill (be specific about triggers)
---

Optional Fields

---
name: skill-name
description: Detailed description
allowed-tools: Read, Grep, Glob    # Restrict tool access (if omitted, Claude asks for permission)
---

Important: allowed-tools is optional. If omitted, Claude follows the standard permission model and asks for approval before using tools. Only add allowed-tools when you want to restrict available tools (e.g., read-only Skills).

allowed-tools Options

Restrict to read-only for safety:

allowed-tools: Read, Grep, Glob

Allow specific tools:

allowed-tools: Read, Write, Edit, Bash(npm:*)

Description Best Practices

The description field is critical for Claude to discover when to use your Skill. Requirements:

• Max length: 1024 characters
• Include both: what the Skill does AND when to use it
• Be specific: Include trigger keywords users would naturally mention

✅ Good (specific triggers):

description: Review code for best practices, detect bugs, and suggest improvements. Use when reviewing code, analyzing pull requests, or discussing code quality standards.

❌ Bad (too vague):

description: Helps with code

✅ Good (context-based):

description: Create and manage React components following best practices. Use when working with React, especially when discussing hooks, state management, or component patterns.

Progressive Disclosure Pattern

Keep SKILL.md concise by linking to support files:

In SKILL.md:

## Quick Links
- [API Schema](./schemas/api-schema.md)
- [Component Templates](./templates/)

In Support Files:

• schemas/api-schema.md: Detailed schema documentation
• templates/component.tsx: Reusable template files

This keeps SKILL.md under 500 lines while providing deep reference material.

Skill Structure Example

skills/
└── code-review/
    ├── SKILL.md                    # Main skill (concise)
    ├── schemas/
    │   └── review-checklist.md     # Review criteria
    ├── templates/
    │   └── review-comment.md       # Comment templates
    ├── examples/
    │   ├── basic-review.md         # Simple example
    │   └── security-review.md      # Advanced example
    └── best-practices/
        ├── review-process.md       # Detailed guidance
        └── common-issues.md        # Issue catalog

Advanced: Tool Restrictions

For read-only Skills (safest):

allowed-tools: Read, Grep, Glob

For Skills that propose changes but don't execute:

allowed-tools: Read, Grep, Glob

(Propose commands for user to run)

For Skills that need to write:

allowed-tools: Read, Write, Edit, Grep, Glob

Best Practices

1. Concise SKILL.md: Keep main file < 500 lines
2. Progressive disclosure: Link to detailed support files
3. Specific triggers: Clear description of when to activate
4. Tool restrictions: Only add allowed-tools when restricting is necessary (e.g., read-only Skills)
5. Organized support: Use all subdirectories for comprehensive guidance

Common Mistakes to Avoid

❌ Name doesn't match directory

Directory: skills/code-review/
Frontmatter: name: codeReview    # Wrong case!

✅ Name matches directory

Directory: skills/code-review/
Frontmatter: name: code-review

❌ Vague description

description: A helpful Skill

✅ Specific triggers

description: Use when reviewing code, analyzing PRs, or discussing code quality

Validation Checklist

After creating a Skill:

□ SKILL.md created in skills/<name>/ directory
□ Frontmatter name matches directory name (kebab-case, max 64 chars)
□ Description includes specific trigger conditions (max 1024 chars)
□ Description includes both what the Skill does AND when to use it
□ SKILL.md is uppercase
□ Supporting directories created
□ If using allowed-tools, it restricts tools appropriately