skill-development

Skill Development for Claude Code

Overview

Skills are modular packages that extend Claude's capabilities by providing specialized knowledge, workflows, and resources. Think of them as "onboarding guides" that transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge.

Key capabilities:

• Create new skills with proper structure and frontmatter
• Edit existing skills to improve discovery and content
• Organize skills using progressive disclosure
• Validate skills against best practices
• Package skills for distribution

When to Use This Skill

Use this skill when:

• Creating a new skill from scratch
• Editing an existing skill's description, instructions, or structure
• Refactoring skills for token optimization or progressive disclosure
• Validating skill structure and frontmatter
• Organizing skill content across SKILL.md, references/, examples/, scripts/

Skill Anatomy

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

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description)
│   └── Markdown body (core instructions)
└── Bundled Resources (optional)
    ├── references/    - Detailed docs loaded as needed
    ├── examples/      - Working code examples
    └── scripts/       - Utility scripts

Progressive Disclosure

Skills use three-level loading to manage context:

Level	When Loaded	Size Limit	Content
Metadata	Always (startup)	~100 words	name and description from frontmatter
Instructions	When triggered	<5k words (~1,500-2,000 words ideal)	SKILL.md body
Resources	As needed	Unlimited	references/, examples/, scripts/

Design principle: Keep SKILL.md lean. Move detailed content to references/.

Quick Start: Create or Edit?

Determine from context whether user wants to create or edit. If unclear, ask:

{
  "questions": [
    {
      "question": "O que você quer fazer?",
      "header": "Ação",
      "multiSelect": false,
      "options": [
        { "label": "Criar nova skill", "description": "Começar do zero" },
        { "label": "Editar skill existente", "description": "Atualizar uma skill que já existe" }
      ]
    }
  ]
}

Then follow the appropriate workflow:

• Creating: See references/creating-skills.md for detailed creation process
• Editing: See references/editing-skills.md for detailed editing process

Core Workflow (Creating)

1. Validate Understanding and Gather Requirements

Principle: Don't ask what the user already said. Extract from context first, then ask only what's missing.

Always ask these two questions together:

{
  "questions": [
    {
      "question": "Entendi que você quer uma skill para [RESUMO]. Correto?",
      "header": "Confirmação",
      "multiSelect": false,
      "options": [
        { "label": "Sim, é isso!", "description": "Prosseguir com a criação" },
        { "label": "Quase, mas...", "description": "Vou explicar melhor" }
      ]
    },
    {
      "question": "Qual a complexidade da skill?",
      "header": "Estrutura",
      "multiSelect": false,
      "options": [
        { "label": "Simples", "description": "Só SKILL.md com instruções diretas" },
        { "label": "Média", "description": "SKILL.md + examples ou references" },
        { "label": "Completa", "description": "SKILL.md + references + examples + scripts" }
      ]
    }
  ]
}

Conditional questions (only when needed):

• Interatividade: Se complexidade >= Média e contexto sugere necessidade
• Location: Só se não for óbvio (padrão: ~/.claude/skills/)

2. Design Skill Structure

Determine what goes where:

SKILL.md (always loaded when triggered):

• Core concepts and overview
• Essential procedures and workflows
• Quick reference tables
• Pointers to references/examples/scripts
• Most common use cases

references/ (loaded as needed):

• Detailed patterns and advanced techniques
• Comprehensive API documentation
• Migration guides
• Edge cases and troubleshooting
• Extensive examples and walkthroughs

examples/ (working code):

• Complete, runnable scripts
• Configuration files
• Template files
• Real-world usage examples

scripts/ (utilities):

• Validation tools
• Testing helpers
• Parsing utilities
• Automation scripts

3. Write Effective Frontmatter

Required fields:

---
name: skill-name
description: This skill should be used when the user asks to "specific trigger 1", "specific trigger 2", or mentions specific terms. Brief explanation of what it does.
---

Optional fields:

---
name: skill-name
description: Trigger-based description
user-invocable: true          # Show in slash command list (default: true for /skills/)
context: fork                 # Run in isolated context (default: inherit)
agent: swe                    # Specify agent type to execute skill (default: main)
language: portuguese          # Force response language (default: match user's language)
allowed-tools:                # YAML-style list (cleaner than comma-separated)
  - Bash
  - Read
  - Write
  - Edit
hooks:                        # Inline hooks scoped to this skill
  - type: PreToolUse
    once: true               # Run hook only once per session
  - type: PostToolUse
---

When to use optional fields:

• user-invocable: false: Hide skill from / command list (skill only triggers automatically via description)
• context: fork: Isolate skill execution from main conversation (useful for experimental or modifying skills)
• agent: type: Route skill to specialized agent (e.g., swe for code-heavy tasks)
• language: Force response in specific language regardless of conversation language
• allowed-tools: Restrict tools skill can use (security/scope control)
• hooks: Add PreToolUse/PostToolUse/Stop hooks scoped to skill execution only

Naming rules:

• Lowercase letters, numbers, hyphens only
• Max 64 characters
• Use gerund form (verb+ing): analyzing-code, writing-documentation
• Be specific, not generic

Description requirements:

• Max 1024 characters
• Third person: "This skill should be used when..." (NOT "Use this skill when..." or "I help you...")
• Include BOTH what it does AND when to use it
• Use specific trigger words users would say
• Mention file types, operations, and context

Good example:

description: This skill should be used when the user asks to "create a hook", "add a PreToolUse hook", "validate tool use", or mentions hook events (PreToolUse, PostToolUse, Stop). Provides comprehensive hooks API guidance.

Bad examples:

description: Helps with hooks  # Vague, not third person
description: Use this skill for hook development  # Wrong person
description: I can help you create hooks  # First person

4. Write Clear Instructions

Writing style:

• Use imperative/infinitive form (verb-first instructions)
• NOT second person ("You should...")
• Objective, instructional language

Correct:

To create a hook, define the event type.
Configure the MCP server with authentication.
Validate settings before use.

Incorrect:

You should create a hook by defining the event type.
You need to configure the MCP server.

Add interactive patterns when needed:

If the skill helps create/configure something, include AskUserQuestion to gather requirements:

## Instructions

### Step 1: Gather Requirements

Use AskUserQuestion to understand what to create:

\`\`\`json
{
  "questions": [
    {
      "question": "What should this do?",
      "header": "Purpose",
      "options": [...]
    }
  ]
}
\`\`\`

### Step 2: Create Based on Answers

Based on user's selections, create the appropriate structure...

When to add: Skills for creating commands, hooks, configurations, or anything requiring user decisions

See: examples/interactive-workflow-example.md for complete patterns

5. Configure Tool Permissions and Hooks

Tool permissions with YAML lists (recommended):

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

Cleaner and less error-prone than comma-separated: allowed-tools: Bash, Read, Write

Bash wildcards for flexible permissions:

---
allowed-tools:
  - Bash(npm *)              # Allow any npm command
  - Bash(git * main)         # Allow git commands with 'main' anywhere
  - Bash(* install)          # Allow any command ending with 'install'
  - Read
  - Write
---

Use wildcards when skill needs variations of commands without listing each one.

Inline hooks for skill-scoped automation:

---
hooks:
  - type: PreToolUse         # Validate before tool execution
    once: true               # Run only once (useful for setup)
  - type: PostToolUse        # React to tool results
  - type: Stop               # Clean up when skill completes
---

Hooks run only when this skill is active. Use for:

• Validation specific to skill operations
• Logging/tracking skill actions
• Setup/teardown within skill lifecycle

See: ../hook-development/ for complete hooks documentation

6. Organize Content

Keep SKILL.md lean (1,500-2,000 words ideal, <5k max):

• Move detailed content to references/
• Move examples to examples/
• Move utilities to scripts/
• Reference these resources clearly in SKILL.md

Reference resources in SKILL.md:

## Additional Resources

### Reference Files
- **`references/patterns.md`** - Common patterns
- **`references/advanced.md`** - Advanced techniques

### Examples
- **`examples/basic-example.sh`** - Working example

7. Validate the Skill

CRITICAL: Always run automated validation after creating or editing a skill.

Execute the validation script:

bash ~/.claude/skills/skill-development/scripts/validate-skill.sh path/to/skill-name

The script automatically checks:

• ✓ SKILL.md exists with valid YAML frontmatter
• ✓ Required fields (name, description) present and valid
• ✓ Name format (lowercase, hyphens, max 64 chars)
• ✓ Description format (third person, <1024 chars, specific triggers)
• ✓ Line count (<500 lines, warns at >400)
• ✓ Referenced files exist
• ✓ No second person usage ("you should")

If validation fails:

1. Fix reported errors
2. Re-run validation script
3. Only proceed to testing after passing all checks

Additional manual verification:

• Clear instructions in imperative form
• Concrete examples provided
• Supporting files clearly referenced

8. Test the Skill

For plugin skills:

cc --plugin-dir /path/to/plugin

For personal/project skills:

Skills in ~/.claude/skills/ or .claude/skills/ are hot-reloaded automatically - no restart needed!

1. Edit the skill file
2. Try trigger phrases that match the description
3. Verify skill activates automatically with updated content
4. Confirm instructions are clear and actionable

Note: Plugin skills still require plugin reload (remove and re-add marketplace)

Debug if needed:

claude --debug  # See skill loading and activation logs

Common Patterns

Minimal Skill (Simple knowledge)

skill-name/
└── SKILL.md

Standard Skill (Recommended)

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

Complete Skill (Complex domain)

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

Plugin-Specific Considerations

Skill Location

Plugin skills live in plugin-name/skills/:

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

Auto-Discovery

Claude Code automatically:

• 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 Claude determines needed

Testing in Plugins

# Test with --plugin-dir
cc --plugin-dir /path/to/plugin

# Verify skill loads and triggers correctly

Best Practices

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 ideal)
• ✅ Use progressive disclosure (move details to references/)
• ✅ Write in imperative/infinitive form
• ✅ Reference supporting files clearly
• ✅ Provide working examples
• ✅ Use gerund naming (analyzing-code not code-analyzer)
• ✅ Use YAML lists for allowed-tools (cleaner than comma-separated)
• ✅ Use wildcards in Bash permissions when appropriate (Bash(npm *))
• ✅ Set user-invocable: false for internal-only skills
• ✅ Use context: fork for experimental or high-risk operations
• ✅ Add inline hooks for skill-specific automation

DON'T:

• ❌ Use second person anywhere
• ❌ Have vague trigger conditions
• ❌ Put everything in SKILL.md (>3,000 words without references/)
• ❌ Leave resources unreferenced
• ❌ Include broken or incomplete examples
• ❌ Skip validation
• ❌ Make all skills user-invocable (some should be auto-trigger only)
• ❌ Over-restrict with comma-separated allowed-tools when wildcards work better

Additional Resources

Reference Files

For detailed processes and techniques, consult:

• references/creating-skills.md - Complete skill creation process with AskUserQuestion patterns
• references/editing-skills.md - Detailed editing workflows and refactoring patterns
• references/best-practices.md - Validation rules, common mistakes, optimization techniques

Example Skills

Study these skills as templates:

• ../hook-development/ - Progressive disclosure, utilities, complete structure
• ../command-development/ - Clear critical concepts, good organization
• ../sync-claude-md/ - Well-structured analysis skill

Implementation Workflow Summary

To create a skill:

1. Understand use cases: Ask questions, gather examples
2. Plan resources: Determine what scripts/references/examples needed
3. Create structure: mkdir -p skills/skill-name/{references,examples,scripts}
4. Write SKILL.md:
   • Frontmatter with third-person description and trigger phrases
   • Lean body (1,500-2,000 words) in imperative form
   • Reference supporting files
5. Add resources: Create references/, examples/, scripts/ as needed
6. Validate: Check description, writing style, organization
7. Test: Verify skill loads on expected triggers
8. Iterate: Improve based on usage

To edit a skill:

1. Read current skill: Analyze structure, content, line count
2. Determine edit type: Description, instructions, new section, or refactor
3. Make changes: Use Edit tool to update specific sections
4. Validate: Check all requirements still met
5. Test: Verify skill still activates correctly

Focus on strong trigger descriptions, progressive disclosure, and imperative writing style for effective skills that load when needed and provide targeted guidance.