Creating Agent Skills

Skills extend agent capabilities with domain-specific knowledge. Use skills for procedural knowledge the agent lacks—not for concepts it already understands.

If guidance is project-specific or one-off, use INSTRUCTIONS.md or inline context instead.

Structure

Required Frontmatter

Every SKILL.md must start with YAML frontmatter on line 1:

---
name: my-skill-name
description: What this skill does and when to use it. Third-person.
---

Field requirements:

• name: lowercase, hyphens only, max 64 chars, no reserved words (“anthropic”, “claude”)
• description: max 1024 chars, specific triggers + capabilities

File Organization

skill-name/
├── SKILL.md              # Required. Under 200 lines.
└── references/           # Optional. For detailed content.
    ├── api.md
    └── examples.md

Use references/ when SKILL.md exceeds 200 lines. Keep references one level deep—avoid nested file references.

Writing Descriptions

The description determines when the skill activates. Include both what it does and when to use it.

Always use third-person (the description is injected into the system prompt):

Include key terms users might mention: tool names, file extensions, specific operations.

Content Guidelines

Match Specificity to Task Fragility

High freedom (multiple valid approaches):

Review code for potential bugs, readability, and adherence to project conventions.

Medium freedom (preferred pattern with variation):

Use pdfplumber for text extraction. For scanned PDFs requiring OCR, use pdf2image instead.

Low freedom (fragile operations):

Run exactly: `python scripts/migrate.py --verify --backup`
Do not modify flags.

Writing Style

• Imperative form: “Use X” not “You should use X”
• Assume competence: Skip explanations of concepts the agent knows
• One term, consistent: Pick “endpoint” or “route”, not both
• No time-sensitive content: Avoid “as of 2025” or “after next release”

Quick Reference Tables

For CLIs and APIs, provide lookup tables:

| Task | Command |
|------|---------|
| Check status | `glab ci status` |
| View logs | `glab ci trace <job>` |
| Retry job | `glab ci retry <job>` |

Common Patterns

Prerequisite Verification

Check requirements before proceeding:

## FIRST: Verify Installation

Run this before any commands. If it fails, STOP—this skill doesn't apply.

\`\`\`bash
glab --version
\`\`\`

Workflow Checklists

For multi-step tasks, provide a copyable checklist:

## Workflow

Copy this checklist to track progress:

\`\`\`
- [ ] Step 1: Analyze input
- [ ] Step 2: Validate mapping
- [ ] Step 3: Apply changes
- [ ] Step 4: Verify output
\`\`\`

Concrete Examples

Show input/output pairs instead of abstract descriptions:

**Input**: Added user authentication with JWT tokens
**Output**:
\`\`\`
feat(auth): implement JWT-based authentication
\`\`\`

Anti-patterns

• Verbose explanations: Don’t explain what PDFs are or how libraries work
• Multiple options without defaults: Recommend one approach, mention alternatives briefly
• Vague descriptions: “Helps with documents” won’t activate correctly
• Deeply nested references: SKILL.md → file.md → another.md breaks navigation
• Magic constants: Document why values were chosen, or let the agent decide

Checklist

Before finalizing a skill:

• Frontmatter starts on line 1 with ---
• name is lowercase with hyphens only
• description includes triggers AND capabilities (third-person)
• SKILL.md is under 200 lines (use references/ if larger)
• References are one level deep from SKILL.md
• Imperative form throughout (“Use X” not “You should”)
• Quick reference table for any CLI/API commands
• Prerequisite verification if skill depends on tools/config
• No time-sensitive information
• Tested with representative tasks