OpenAgentsControl/plugins/claude-code/scripts/context/openagents-repo/guides/creating-skills.md

Creating Skills

Purpose: Step-by-step guide to create Agent Skills

---

Quickstart

1. Create directory:

   mkdir -p ~/.claude/skills/my-skill
   

2. Create SKILL.md with frontmatter:

   ---
   name: my-skill
   description: What it does and when to use it
   ---
      
   Instructions for Claude...
   

3. Verify: Ask Claude "What Skills are available?"

4. Test: Ask Claude something matching the description

---

Writing Good Descriptions

The description determines when Claude uses the skill. Include:

• What it does: List specific capabilities

• When to use: Include trigger terms users would say

  # Bad
  description: Helps with documents
  
  # Good
  description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
  

---

Progressive Disclosure

Keep SKILL.md under 500 lines. Use supporting files for details:

my-skill/
├── SKILL.md         # Overview (required)
├── reference.md     # Detailed docs (loaded when needed)
├── examples.md      # Usage examples
└── scripts/
    └── helper.py    # Utility script (executed, not loaded)

Reference in SKILL.md:

For complete API details, see reference.md (example file)

---

Key Points

• Skills are loaded automatically (no restart needed)
• Use claude --debug to see loading errors
• Skills cannot spawn subagents
• Use allowed-tools to restrict capabilities

---

Related

• ../concepts/agent-skills.md - Skills overview
• ../lookup/skill-metadata.md - All metadata fields
• ../examples/skills/ - Example skills

Reference: https://docs.anthropic.com/en/docs/claude-code/skills