Creating Skills

​

Core Principles

​

Concise is Key

​

Progressive Disclosure

1. Metadata (name + description) - Always in context (~100 words)
2. SKILL.md body - When skill triggers (less than 5k words)
3. Bundled resources - As needed (unlimited)

​

Skill Structure

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code
    ├── references/       - Documentation loaded as needed
    └── assets/           - Files used in output

​

SKILL.md Frontmatter

---
name: my-skill
description: "What the skill does and when to use it. Include all triggering conditions here."
---

• Include both what the skill does AND when to use it
• Include all “when to use” information in the description (not in the body)
• The body is only loaded after triggering

​

Bundled Resources

​

Scripts (scripts/)

• When to use: Repeatedly rewritten code or deterministic operations
• Example: scripts/rotate_pdf.py for PDF rotation
• Benefits: Token efficient, may execute without loading into context

​

References (references/)

• When to use: Documentation the agent should reference while working
• Examples: API docs, database schemas, company policies
• Benefits: Keeps SKILL.md lean, loaded only when needed
• Best practice: Include grep patterns in SKILL.md for large files (>10k words)

​

Assets (assets/)

• When to use: Files that will be used in final output
• Examples: Templates, images, boilerplate code, fonts
• Benefits: Separates output resources from documentation

​

Creation Process

​

Step 1: Understand with Examples

• What functionality should it support?
• What would users say to trigger it?
• Can you give specific usage examples?

​

Step 2: Plan Reusable Contents

1. What scripts would avoid rewriting code?
2. What references would provide needed context?
3. What assets would be used in output?

​

Step 3: Initialize the Skill

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

# With specific resources
scripts/init_skill.py my-skill --path skills/public --resources scripts,references

# With example files
scripts/init_skill.py my-skill --path skills/public --examples

​

Step 4: Edit the Skill

1. Add reusable resources - Create scripts, references, and assets
2. Test scripts - Run them to ensure they work
3. Write SKILL.md - Include instructions for using the skill
4. Keep it concise - Aim for less than 500 lines in SKILL.md

• Use imperative/infinitive form
• Include only essential information
• Link to references for detailed content

​

Step 5: Package the Skill

scripts/package_skill.py path/to/skill-folder

​

Step 6: Iterate

1. Use the skill on real tasks
2. Notice struggles or inefficiencies
3. Update SKILL.md or resources
4. Test again

​

Progressive Disclosure Patterns

​

Pattern 1: High-level guide with references

# PDF Processing

## Quick start
Extract text with pdfplumber:
[code example]

## Advanced features
- **Form filling**: See [FORMS.md](FORMS.md)
- **API reference**: See [REFERENCE.md](REFERENCE.md)

​

Pattern 2: Domain-specific organization

bigquery-skill/
├── SKILL.md
└── reference/
    ├── finance.md
    ├── sales.md
    └── product.md

​

Pattern 3: Conditional details

# DOCX Processing

## Creating documents
Use docx-js. See [DOCX-JS.md](DOCX-JS.md).

## Editing documents
For simple edits, modify XML directly.

**For tracked changes**: See [REDLINING.md](REDLINING.md)

​

What NOT to Include

• README.md
• INSTALLATION_GUIDE.md
• QUICK_REFERENCE.md
• CHANGELOG.md

​

Skill Naming

• Use lowercase letters, digits, and hyphens only
• Keep under 64 characters
• Prefer short, verb-led phrases
• Namespace by tool when helpful (e.g., gh-address-comments)
• Name the folder exactly after the skill name