| name | add-skill |
| description | Create or improve agent skills. Load when creating SKILL.md files, writing skill descriptions, or structuring skill content for OpenCode or Claude. |
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.
Skill work is prompt engineering plus evaluation. Treat every skill as a behavioral artifact: define when it should trigger, what better behavior it should cause, how to verify that behavior, and how to avoid overfitting one example.
Creation Workflow
- Capture intent: target behavior, trigger phrases, non-trigger near misses, expected output, dependencies, and safety constraints.
- Research current docs or similar skills when the domain is fast-moving or tool-specific.
- Draft the smallest SKILL.md that changes behavior; put bulky reference material in
references/ and deterministic repeated work in scripts/.
- Create representative eval prompts before claiming the skill is done.
- Run or simulate baseline vs. with-skill behavior where practical; revise based on observed failures, not taste.
- Add trigger evals for should-trigger and should-not-trigger cases when description quality matters.
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. Target under 200 lines.
├── references/ # Optional detailed content, one level deep.
├── scripts/ # Optional deterministic helpers.
└── evals/ # Optional behavior/trigger tests.
Use references/ when SKILL.md exceeds 200 lines. Add scripts when multiple evals would make the agent recreate the same helper.
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):
| Quality | Example |
|---|
| Good | Manages GitLab MRs and pipelines via glab CLI. Load before running glab commands. |
| Good | Analyzes web performance with Chrome DevTools MCP. Use when auditing page load or Lighthouse scores. |
| Bad | I help you with GitLab operations. |
| Bad | Useful for various tasks. |
Include key terms users might mention: tool names, file extensions, specific operations. Make descriptions slightly assertive when under-triggering would be costly: “Load before…” or “Use when…” is better than “Helpful for…”.
Also write near-miss boundaries when skills overlap: “Use X for security PR audits; use Y for normal code review.”
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
\`\`\`
Evals
For each new or materially changed skill, add 2-5 realistic behavior evals when practical:
{
"skill_name": "example-skill",
"evals": [
{
"id": "realistic-case",
"prompt": "Real user-style task prompt",
"expected_output": "Observable behavior that should improve with the skill",
"files": [],
"assertions": []
}
]
}
For trigger tuning, create 16-20 realistic prompts split between should_trigger: true and tricky near misses with should_trigger: false. Prefer prompts that look like real user requests, not abstract labels.
When iterating, generalize from eval failures. Do not add brittle instructions that only fix one fixture.
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
- No evals for fragile behavior: Without representative prompts, description and workflow changes are guesswork
- Overfitting examples: Do not encode a test prompt’s incidental details as universal rules
Checklist
Before finalizing a skill:
