name: managing-skills
description: Create, update, and improve Claude Code skill files following official best practices. Use when user mentions "skill", "SKILL.md", "create skill", "update skill", "improve skill", "generate skill", "skill template", or wants help with skills. Triggers include "スキル作成", "PDF処理用のスキルを作って", "update the managing-agents skill".
allowed-tools: Read, Write, Edit, Glob, Grep, Bash

Managing Claude Code Skills

Create, update, and improve Claude Code skills following best practices.

When to Use

Automatically invoke when the user:
- Asks to "create a skill" or "make a skill"
- Wants to "update a skill" or "improve a skill"
- Requests "skill template" or "SKILL.md help"
- Needs to "review a skill" or "check skill quality"

What Are Skills?

Skills are modular capabilities that extend Claude's functionality. Key characteristics:
- Model-invoked: Claude autonomously decides when to use them
- Progressive disclosure: Core instructions + on-demand resources
- Required SKILL.md file with YAML frontmatter
- Optional supporting files (reference.md, examples.md, etc.)

Quick Reference

File Structure

Minimal Template

---
name: skill-name
description: [What it does]. Use when [triggers].
---

# Skill Title

Brief overview.

## When to Use
- [Trigger scenario 1]
- [Trigger scenario 2]

## Workflow

### Step 1: [Action]
Instructions with checklists if needed.

### Step 2: [Action]
Include validation: run → check → fix → repeat.

## Notes
- Constraints and prerequisites

Storage Locations

Workflow: Creating Skills

Step 1: Gather Requirements

1. Purpose: What should this skill do?
2. Triggers: What phrases activate it?
3. Scope: ONE focused capability?
4. Complexity: Needs supporting files?

Step 2: Naming

Convention: Gerund form (verb + -ing)

Rules: lowercase, hyphens, max 64 chars

Step 3: Description (CRITICAL)

Template: [What it does]. Use when [conditions/triggers].

Requirements:
- Max 1024 characters
- Third person voice
- Include WHAT (capability) and WHEN (triggers)
- Specific terminology

Good:

description: Extract text and tables from PDF files. Use when working with PDF files or when user mentions PDFs.

Bad:

description: Helps with documents  # Too vague

See reference.md for rich format with examples.

Step 4: Write SKILL.md Body

Target: Under 500 lines. Challenge every sentence.

Structure:
1. Overview (1-2 paragraphs)
2. When to Use (trigger scenarios)
3. Workflow (numbered steps)
4. Notes (constraints)
5. Related Resources (links)

Key rule: Keep references one level deep.

Step 5: Supporting Files

See architecture.md for progressive disclosure details.

Step 6: Tool Restrictions (Optional)

---
name: code-analyzer
description: ...
allowed-tools: Read, Grep, Glob
---

Step 7: Create Files

Option A: Use init script (recommended)

./scripts/init_skill.py my-skill --path .claude/skills

Creates complete skill structure with templates.

Option B: Manual creation

mkdir -p .claude/skills/skill-name
cat > .claude/skills/skill-name/SKILL.md << 'EOF'
---
name: skill-name
description: [description]
---

# Title
...
EOF

Step 8: Validate

Run validation script:

./scripts/quick_validate.py .claude/skills/skill-name

Manual checklist:

• [ ] Name: gerund form, lowercase, max 64 chars
• [ ] Description: specific triggers, third person, max 1024 chars
• [ ] SKILL.md: under 500 lines
• [ ] Frontmatter: valid YAML (spaces, not tabs)
• [ ] References: one level deep
• [ ] Paths: forward slashes only

See reference.md for complete checklist.

Step 9: Review

Run claude-config-reviewer agent to validate:
- Structure and required sections
- Anti-patterns (temporary markers, broken links)
- File size limits

Step 10: Test

1. Test activation with trigger phrases
2. Follow workflow step-by-step
3. Test across models (Haiku, Sonnet, Opus)
4. Iterate based on observations

See best-practices.md for testing strategies.

Workflow: Updating Skills

Step 1: Review Current State

cat .claude/skills/skill-name/SKILL.md
ls .claude/skills/skill-name/

Step 2: Identify Issues

Common problems:
- Vague description, missing triggers
- Outdated examples
- SKILL.md over 500 lines
- Poor structure

Step 3: Apply Changes

Same principles as creating:
- Keep under 500 lines
- Update triggers in description
- Move extensive content to supporting files

Step 4: Review

Run claude-config-reviewer agent to validate changes.

Step 5: Test

• Test activation with various phrases
• Test across models
• Get team feedback

See updating-skills.md for detailed workflow.

Key Principles

1. Conciseness

Under 500 lines. Assume Claude has foundational knowledge.

2. Degrees of Freedom

Match specificity to task fragility:
- High: Text instructions (flexible)
- Medium: Pseudocode (guided)
- Low: Exact scripts (deterministic)

3. One Level Deep

SKILL.md → supporting file (no further chaining)

4. Consistent Terminology

One term per concept throughout.

Common Anti-Patterns

Troubleshooting

Output Format

## Generating Skill: [name]

- Name: skill-name
- Description: [description]
- Location: [path]
- Size: ~[X] lines

## Structure

- `SKILL.md` (required)
- `reference.md` (optional)
- `examples.md` (optional)

## Next Steps

1. Review and confirm
2. Create files
3. Restart Claude Code
4. Test with trigger phrases

Scripts

# Initialize new skill
./scripts/init_skill.py my-skill --path .claude/skills

# Validate existing skill
./scripts/quick_validate.py .claude/skills/my-skill

# Package for distribution
./scripts/package_skill.py .claude/skills/my-skill ./dist

Related Resources

• reference.md - Complete specs, frontmatter fields
• best-practices.md - Advanced patterns, testing
• examples.md - Concrete use cases
• architecture.md - Progressive disclosure
• updating-skills.md - Update workflows
• reference-workflows.md - Workflow patterns
• reference-output-patterns.md - Output templates

Notes

• Skills are model-invoked (automatic)
• Description is CRITICAL for discovery
• Keep SKILL.md under 500 lines
• Always use forward slashes
• Restart Claude Code after changes
• Test across multiple models