skill-development

What this skill does

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

```json
{
  "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:**

```json
{
  "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:**

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

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

```markdown
## 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, configuratio