# skill-development

> Review code for best practices...

- Author: dependabot[bot]
- Repository: sjnims/plugin-dev
- Version: 20260119153152
- Stars: 9
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/sjnims/plugin-dev
- Web: https://mule.run/skillshub/@@sjnims/plugin-dev~skill-development:20260119153152

---

---
name: skill-development
description: This skill should be used when the user asks to "create a skill", "add a skill to plugin", "write a new skill", "improve skill description", "organize skill content", "SKILL.md format", "skill frontmatter", "skill triggers", "trigger phrases for skills", "progressive disclosure", "skill references folder", "skill examples folder", "validate skill", or needs guidance on skill structure, file organization, writing style, or skill development best practices for Claude Code plugins.
---

# Skill Development for Claude Code Plugins

This skill provides guidance for creating effective skills for Claude Code plugins.

## About Skills

Skills are modular, self-contained packages that extend Claude's capabilities by providing
specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific
domains or tasks—they transform Claude from a general-purpose agent into a specialized agent
equipped with procedural knowledge that no model can fully possess.

### What Skills Provide

1. Specialized workflows - Multi-step procedures for specific domains
2. Tool integrations - Instructions for working with specific file formats or APIs
3. Domain expertise - Company-specific knowledge, schemas, business logic
4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks

### Anatomy of a Skill

Every skill consists of a required SKILL.md file and optional bundled resources:

```
skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)
```

#### SKILL.md (required)

**Metadata Quality:** The `name` and `description` in YAML frontmatter determine when Claude will use the skill. Be specific about what the skill does and when to use it. Use the third-person (e.g. "This skill should be used when..." instead of "Use this skill when...").

#### Optional Frontmatter Fields

##### allowed-tools

Optionally restrict which tools Claude can use when the skill is active:

```yaml
---
name: code-reviewer
description: Review code for best practices...
allowed-tools: Read, Grep, Glob
---
```

Use `allowed-tools` for:

- Read-only skills that shouldn't modify files
- Security-sensitive workflows
- Skills with limited scope

When specified, Claude can only use the listed tools without needing permission. If omitted, Claude follows the standard permission model.

##### user-invocable

Control whether the skill appears in the slash command menu:

```yaml
---
name: internal-review-standards
description: Apply internal code review standards...
user-invocable: false
---
```

**Default:** `true` (skills are visible in the `/` menu)

**Important:** This field only controls slash menu visibility. It does NOT affect:

- **Skill tool access** - Claude can still invoke the skill programmatically
- **Auto-discovery** - Claude still discovers and uses the skill based on context

Use `user-invocable: false` for skills that Claude should use automatically but users shouldn't invoke directly.

##### disable-model-invocation

Prevent Claude from programmatically invoking the skill via the Skill tool:

```yaml
---
name: dangerous-operation
description: Perform dangerous operation...
disable-model-invocation: true
---
```

**Default:** `false` (programmatic invocation allowed)

Use for skills that should only be manually invoked by users, such as:

- Destructive operations requiring human judgment
- Interactive workflows needing user input
- Approval processes

**Visibility comparison:**

| Setting | Slash Menu | Skill Tool | Auto-Discovery |
|---------|-----------|------------|----------------|
| `user-invocable: true` (default) | Visible | Allowed | Yes |
| `user-invocable: false` | Hidden | Allowed | Yes |
| `disable-model-invocation: true` | Visible | Blocked | Yes |

#### Bundled Resources (optional)

##### Scripts (`scripts/`)

Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.

- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed
- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks
- **Benefits**: Token efficient, deterministic, may be executed without loading into context

##### References (`references/`)

Documentation and reference material intended to be loaded as needed into context.

- **When to include**: For documentation that Claude should reference while working
- **Examples**: `references/schema.md` for database schemas, `references/api_docs.md` for API specifications
- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md
- **Avoid duplication**: Information should live in either SKILL.md or references files, not both

##### Assets (`assets/`)

Files not intended to be loaded into context, but rather used within the output Claude produces.

- **When to include**: When the skill needs files that will be used in the final output
- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for templates

### Progressive Disclosure Design Principle

Skills use a three-level loading system to manage context efficiently:

1. **Metadata (name + description)** - Always in context (~100 words)
2. **SKILL.md body** - When skill triggers (<5k words)
3. **Bundled resources** - As needed by Claude (Unlimited*)

*Unlimited because scripts can be executed without reading into context window.

## Skill Creation Process

To create a skill, follow these six steps. For detailed instructions on each step, see `references/skill-creation-workflow.md`.

1. **Understand the Skill**: Gather concrete examples of how the skill will be used through user questions and feedback
2. **Plan Reusable Contents**: Analyze examples to identify what scripts, references, and assets would be helpful
3. **Create Structure**: Set up the skill directory with `mkdir -p skills/skill-name/{references,examples,scripts}`
4. **Edit the Skill**: Write SKILL.md with proper frontmatter and imperative-form body; create bundled resources
5. **Validate and Test**: Check structure, trigger phrases, writing style, and progressive disclosure
6. **Iterate**: Improve based on real-world usage and feedback

### Key Writing Guidelines

- **Description**: Use third-person ("This skill should be used when...") with specific trigger phrases
- **Body**: Use imperative/infinitive form ("To create X, do Y"), not second person ("You should...")
- **Size**: Target 1,500-2,000 words; move detailed content to references/

## Plugin-Specific Considerations

### Skill Location in Plugins

Plugin skills live in the plugin's `skills/` directory:

```
my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
├── agents/
└── skills/
    └── my-skill/
        ├── SKILL.md
        ├── references/
        ├── examples/
        └── scripts/
```

### Auto-Discovery

Claude Code automatically discovers skills:

- Scans `skills/` directory
- Finds subdirectories containing `SKILL.md`
- Loads skill metadata (name + description) always
- Loads SKILL.md body when skill triggers
- Loads references/examples when needed

### No Packaging Needed

Plugin skills are distributed as part of the plugin, not as separate ZIP files. Users get skills when they install the plugin.

### Testing in Plugins

Test skills by installing plugin locally:

```bash
# Test with --plugin-dir
claude --plugin-dir /path/to/plugin

# Ask questions that should trigger the skill
# Verify skill loads correctly
```

## Examples from Plugin-Dev

Study the skills in this plugin as examples of best practices:

**hook-development skill:**

- Excellent trigger phrases: "create a hook", "add a PreToolUse hook", etc.
- Lean SKILL.md (2,125 words)
- 3 references/ files for detailed content
- 3 examples/ of working hooks
- 3 scripts/ utilities

**agent-development skill:**

- Strong triggers: "create an agent", "agent frontmatter", etc.
- Focused SKILL.md (1,896 words)
- References include the AI generation prompt from Claude Code
- Complete agent examples

**plugin-settings skill:**

- Specific triggers: "plugin settings", ".local.md files", "YAML frontmatter"
- References show real implementations (multi-agent-swarm, ralph-wiggum)
- Working parsing scripts

Each demonstrates progressive disclosure and strong triggering.

## Validation Checklist

Before finalizing a skill:

**Structure:**

- [ ] SKILL.md file exists with valid YAML frontmatter
- [ ] Frontmatter has `name` and `description` fields
- [ ] Name uses only lowercase letters, numbers, and hyphens (max 64 chars)
- [ ] Description is under 1024 characters
- [ ] (Optional) `allowed-tools` field if restricting tool access
- [ ] (Optional) `user-invocable` field if hiding from slash menu
- [ ] (Optional) `disable-model-invocation` field if blocking programmatic use
- [ ] Markdown body is present and substantial
- [ ] Referenced files actually exist

**Description Quality:**

- [ ] Uses third person ("This skill should be used when...")
- [ ] Includes specific trigger phrases users would say
- [ ] Lists concrete scenarios ("create X", "configure Y")

**Content Quality:**

- [ ] SKILL.md body uses imperative/infinitive form
- [ ] Body is focused and lean (1,500-2,000 words ideal, <3k max)
- [ ] Detailed content moved to references/
- [ ] Examples are complete and working

**Testing:**

- [ ] Skill triggers on expected user queries
- [ ] Content is helpful for intended tasks
- [ ] No duplicated information across files

## Quick Reference

### Minimal Skill

```
skill-name/
└── SKILL.md
```

Good for: Simple knowledge, no complex resources needed

### Standard Skill (Recommended)

```
skill-name/
├── SKILL.md
├── references/
│   └── detailed-guide.md
└── examples/
    └── working-example.sh
```

Good for: Most plugin skills with detailed documentation

### Complete Skill

```
skill-name/
├── SKILL.md
├── references/
│   ├── patterns.md
│   └── advanced.md
├── examples/
│   ├── example1.sh
│   └── example2.json
└── scripts/
    └── validate.sh
```

Good for: Complex domains with validation utilities

## Best Practices Summary

**DO:**

- Use third-person in description ("This skill should be used when...")
- Include specific trigger phrases ("create X", "configure Y")
- Keep SKILL.md lean (1,500-2,000 words)
- Use progressive disclosure (move details to references/)
- Write in imperative/infinitive form
- Reference supporting files clearly
- Provide working examples
- Create utility scripts for common operations

**DON'T:**

- Use second person ("You should...")
- Have vague trigger conditions
- Put everything in SKILL.md (>3,000 words without references/)
- Leave resources unreferenced
- Include broken or incomplete examples

## Additional Resources

### Example Skills

Copy-paste ready skill templates in `examples/`:

- **`examples/minimal-skill.md`** - Bare-bones skill with just SKILL.md (git conventions example)
- **`examples/complete-skill.md`** - Full skill with references/, examples/, and scripts/ (API testing example)
- **`examples/frontmatter-templates.md`** - Quick-reference frontmatter patterns for common use cases

### Reference Files

For detailed guidance, consult:

- **`references/skill-creation-workflow.md`** - Plugin-specific skill creation workflow (recommended for plugin skills)
- **`references/skill-creator-original.md`** - Original generic skill-creator methodology (includes init/packaging scripts for standalone skills)

### Study These Skills

Plugin-dev's skills demonstrate best practices:

- `../hook-development/` - Progressive disclosure, utilities
- `../agent-development/` - AI-assisted creation, references
- `../mcp-integration/` - Comprehensive references
- `../plugin-settings/` - Real-world examples
- `../command-development/` - Clear critical concepts
- `../plugin-structure/` - Good organization