# plugin-add-skill

> Add a new skill to an existing Claude Code plugin

- Author: Edison
- Repository: soilmass/claudeutils
- Version: 20260127023329
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/soilmass/claudeutils
- Web: https://mule.run/skillshub/@@soilmass/claudeutils~plugin-add-skill:20260127023329

---

---
name: plugin-add-skill
description: Add a new skill to an existing Claude Code plugin
argument-hint: "<plugin-dir> <skill-name> \"<description>\" [--model sonnet]"
user-invocable: true
model: sonnet
---

# plugin-add-skill

Add a new skill to an existing Claude Code plugin with proper structure and frontmatter.

## When to Use

Use this skill when:
- Adding a new capability to an existing plugin
- You need a properly formatted skill file
- You want to ensure skill compliance with agentskills.io spec

## Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `plugin-dir` | Yes | Path to the plugin directory |
| `skill-name` | Yes | Skill name (1-64 chars, lowercase, hyphens) |
| `description` | Yes | Brief skill description (max 200 chars) |
| `--model` | No | Model preference: sonnet, opus, haiku (default: sonnet) |
| `--size` | No | Skill size: small, medium, large (default: small) |

## Example Usage

```
/plugin-add-skill ./my-plugin code-review "Analyzes code for issues and best practices"
```

```
/plugin-add-skill ./my-plugin test-runner "Executes test suites" --model haiku --size medium
```

## Workflow

When invoked, follow these steps:

### Step 1: Validate Arguments

1. Verify plugin directory exists
2. Verify `.claude-plugin/plugin.json` exists
3. Validate skill name:
   - 1-64 characters
   - Lowercase letters, numbers, hyphens only
   - Start with letter, end with letter/number
   - No consecutive hyphens
4. Validate description is non-empty and <= 200 chars

### Step 2: Check Design Phase (if workflow active)

If design docs exist (`.plugin-design/API.md`):
1. Verify skill is listed in API.md
2. Extract expected input/output schema
3. Validate description matches design

If no design docs: Proceed with default template

### Step 3: Create Skill Directory

```
<plugin-dir>/skills/<skill-name>/
└── SKILL.md
```

### Step 4: Generate SKILL.md

Use template from `templates/plugin-build/SKILL.md.tmpl`:

```markdown
---
name: <skill-name>
description: <description>
version: 0.1.0
author: <from plugin manifest or empty>
model: <model>
size: <size>
---

# <skill-name>

<description>

## When to Use

Use this skill when:
- [Define trigger conditions]

## Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `arg1` | Yes | [Description] |

## Example Usage

\`\`\`
/<plugin-name>:<skill-name> [args]
\`\`\`

## Workflow

1. [Step 1]
2. [Step 2]
3. [Step 3]

## Output

Returns:
- [Output description]

## Error Handling

- If [condition]: [response]
```

### Step 5: Update Plugin Manifest

Add skill reference to `plugin.json`:

```json
{
  "skills": [
    ...,
    "skills/<skill-name>/SKILL.md"
  ]
}
```

### Step 6: Update Workflow State

If in plugin-build workflow:
1. Add skill to `phases.implement.components.skills.items`
2. Increment `phases.implement.components.skills.total`

### Step 7: Report Results

```
Skill added: <skill-name>
Location: <plugin-dir>/skills/<skill-name>/SKILL.md

Manifest updated: <plugin-dir>/.claude-plugin/plugin.json

Next steps:
1. Edit SKILL.md to complete the skill definition
2. Add arguments and workflow steps
3. Run /plugin-validate to check compliance
```

## Validation Rules

- Skill name must pass `validate_skill_name()` from validators.sh
- Skill directory must not already exist (use `--force` to overwrite)
- Plugin must have valid manifest
- If design docs exist, skill must be in API.md

## Error Handling

- If plugin directory doesn't exist: Report NOTFOUND error
- If skill name is invalid: Report VALIDATION error with naming rules
- If skill already exists: Report error, suggest `--force` or different name
- If not in design (when design exists): Report warning about unplanned skill

## Integration Points

- Uses `templates/plugin-build/SKILL.md.tmpl` for generation
- Updates workflow state via `add_component()` from plugin-state.sh
- Triggers PostToolUse(Write) hook for verification