What does this skill do?
- Primary purpose (1 sentence)
- Main workflow steps (3-7 steps)
- Tools needed (Beads? Serena? Git? API?)
- Trigger phrases (natural language)
- Success criteria (what makes it "done"?)

.claude/skills/<skill-name>/
├── SKILL.md                 # Main file (<500 lines)
└── resources/               # Progressive disclosure
    ├── examples/
    ├── patterns/
    └── reference/

---
name: skill-name
description: One-line purpose with MUST BE USED trigger. Use when [natural language patterns].
allowed-tools:
  - Tool category patterns (e.g., Bash(git:*), mcp__serena__*)
---

# Skill Name

One-line purpose with time metric.

## Purpose
What this skill does and why it exists

## When to Use This Skill
Natural language patterns and trigger phrases

## Workflow
Step-by-step execution (numbered list)

## Integration Points
How this integrates with Beads/Serena/Git/other skills

## Best Practices
Do's and don'ts

## What This Skill Does ✅
Specific capabilities

## What This Skill DOESN'T Do ❌
Out of scope

## Examples
Real usage scenarios

## Workflow

### 1. Check Prerequisites
- Verify context (branch, Beads issue, env)
- Fail fast if missing critical data

### 2. Gather Information
- Use Serena for code discovery
- Use Beads for issue context
- Use git/gh for repository state

### 3. Execute Core Action
- Make changes (code/git/API)
- Handle errors gracefully
- Provide progress updates

### 4. Validate Results
- Quick checks (<5s)
- Trust environments for full validation

### 5. Update State
- Commit changes (git)
- Update Beads (status, notes)
- Confirm to user

## Integration Points

### With Beads
- Check issue exists via show()
- Update status via update()
- Close on completion via close()
- Link discoveries via dep()

### With Serena
- Search: search_for_pattern()
- Navigate: find_symbol()
- Edit: replace_symbol_body()
- Insert: insert_after_symbol()

### With Git
- Status: git status, git branch
- Changes: git add, git commit
- Remote: git push, gh pr create

## Workflow

### 1. Analyze Request
- Understand scope and constraints
- Identify required tools and knowledge
- Check for blockers

### 2. Research Context
- Read relevant code (Serena)
- Check related issues (Beads)
- Review documentation

### 3. Execute with Expertise
- Apply domain-specific patterns
- Use specialized tools
- Maintain quality standards

### 4. Verify and Document
- Test changes
- Update documentation
- Create follow-up issues if needed

{
  "skill-name": {
    "triggers": [
      "create X",
      "make X",
      "implement X",
      "need X"
    ],
    "intents": [
      "User wants to perform workflow X",
      "User asks for capability X"
    ],
    "examples": [
      "User: 'commit my work'",
      "User: 'create PR'",
      "User: 'fix the PR'"
    ]
  }
}

### Natural Language → Skills (Auto-Invoked)

- **"trigger phrase"** → skill-name skill
  - What it does (3-5 bullets)
  - **Total: <time>**

- **skill-name**: [Description] Use when [trigger patterns].

git add .claude/skills/<skill-name>/
git add .claude/skills/skill-rules.json
git add CLAUDE.md

git commit -m "feat: Add <skill-name> skill for <purpose>

Implements <workflow-type> skill following V3 patterns:
- Progressive disclosure (<500 lines main)
- Beads/Serena integration
- Auto-activation via skill-rules.json
- <X> second typical execution

Feature-Key: <CURRENT_FEATURE>
Agent: claude-code
Role: skill-creator"

resources/
├── examples/
│   ├── simple-case.md
│   ├── complex-case.md
│   └── error-handling.md
├── patterns/
│   ├── beads-integration.md
│   ├── serena-usage.md
│   └── git-operations.md
└── reference/
    ├── tool-list.md
    ├── api-reference.md
    └── troubleshooting.md

issue = mcp__plugin_beads_beads__create({
  title: "SKILL_NAME",
  issue_type: "feature",
  priority: 2,
  design: "Skill creation following V3 patterns"
})

mcp__plugin_beads_beads__close(
  issue_id,
  reason="Skill created and tested"
)

mcp__serena__list_dir(
  relative_path=".claude/skills",
  recursive=true
)

mcp__serena__get_symbols_overview(
  relative_path=".claude/skills/sync-feature-branch/SKILL.md"
)

---
name: skill-name
description: One-line purpose. MUST BE USED when [trigger]. Use when [patterns].
allowed-tools:
  - Tool patterns
---

# Skill Name

Purpose (<time> total).

## Purpose
What and why

## When to Use This Skill
Trigger patterns

## Workflow

### 1. Check Context
Prerequisites and validation

### 2. Execute Action
Main workflow steps

### 3. Update State
Commit and confirm

## Integration Points
Beads/Serena/Git integration

## Best Practices
Do's and don'ts

## Examples
Real scenarios

---
name: specialist-name
description: Domain expertise. MUST BE USED for [domain tasks].
allowed-tools:
  - Domain-specific tools
---

# Specialist Name

Domain expertise for [area].

## Purpose
Expertise domain and scope

## When to Use This Skill
Task patterns requiring expertise

## Workflow
Expert execution pattern

## Domain Knowledge
Key patterns and practices

## Integration Points
Standard integrations

---
name: meta-skill-name
description: Operates on skill system itself. Use when [meta-operation].
allowed-tools:
  - File operations
  - System operations
---

# Meta Skill Name

Skill system operation.

## Purpose
What it changes about skills

## Workflow
Meta-operation steps

## Safety Guardrails
Protecting skill system integrity

User: "create a skill that runs linting"

AI asks: "What type of skill? (workflow/specialist/meta)"
User: "workflow"

AI asks requirements:
- Purpose: Run quick linting checks before commit
- Steps: 1) Check files changed, 2) Run linters, 3) Report results
- Tools: Bash (linters), Git (status)
- Triggers: "lint my code", "check formatting"
- Success: Linters pass or report errors

AI creates:
.claude/skills/lint-check/
├── SKILL.md (250 lines)
└── resources/
    └── linter-configs.md

AI updates:
- skill-rules.json (add triggers)
- CLAUDE.md (add to skills list)

AI tests:
User says: "lint my code"
→ Skill auto-activates ✓
→ Linters run ✓
→ Results reported ✓

AI commits:
"feat: Add lint-check skill for pre-commit linting"

User: "create a database migration skill"

AI asks: "What type?"
User: "specialist"

AI gathers requirements:
- Expertise: Database schema migrations
- Tools: Supabase CLI, SQL, migration scripts
- Domain: Schema design, data integrity, rollback safety

AI creates:
.claude/skills/database-migration/
├── SKILL.md (380 lines)
└── resources/
    ├── migration-patterns.md
    ├── rollback-strategies.md
    └── examples/
        ├── add-column.md
        └── add-table.md

AI integrates:
- Beads: Track migrations as tasks
- Serena: Read existing schema
- Railway: Verify in protected shell

AI commits and tests.

User: "create a skill that creates skills"

AI: "That's a meta skill - operates on the skill system itself"

AI creates skill-creator following this exact pattern:
- Main SKILL.md <500 lines
- Progressive disclosure in resources/
- Templates for each skill type
- Auto-activation on "create skill"
- Self-referential documentation

Result: The skill you're reading right now!

# Test hook manually
cat .claude/hooks/userpromptsubmit_skill_activation.sh | bash
# Should output skill reminders

### With [System]
- What it does
- How it connects
- Example code