117 lines
3.3 KiB
Markdown
117 lines
3.3 KiB
Markdown
---
|
|
name: write-skill
|
|
description: Create new agent skills with proper structure and AI superpower constraints. Use when user wants to create, write, or build a new skill, rule, or instruction.
|
|
---
|
|
|
|
# Write Skill Instructions (Meta-Skill)
|
|
|
|
## Process
|
|
|
|
1. **Gather requirements** - ask user about:
|
|
- What task/domain does the skill cover?
|
|
- What is the fundamental problem or hallucination the AI currently makes?
|
|
- What are the strict absolute rules ("Thou Shalt Not"s)?
|
|
- Do you have concrete ✅ (good) and ❌ (bad) examples?
|
|
|
|
2. **Draft the skill** - create:
|
|
- `SKILL.md` with concise instructions
|
|
- Additional reference files (`REFERENCE.md`) if content exceeds 100 lines
|
|
- Usage examples (`EXAMPLES.md`) if needed
|
|
|
|
3. **Review with user** - present draft and ask:
|
|
- Does this cover your use cases?
|
|
- Anything missing or unclear?
|
|
- Should any section be more/less detailed?
|
|
|
|
## Skill Structure
|
|
|
|
```
|
|
.ai/skills/skill-name/
|
|
├── SKILL.md # Main instructions (required)
|
|
├── REFERENCE.md # Detailed docs (if needed)
|
|
└── EXAMPLES.md # Usage examples (if needed)
|
|
```
|
|
|
|
## SKILL.md Template
|
|
|
|
```md
|
|
---
|
|
name: skill-name
|
|
description: Brief description of capability. Use when [specific triggers].
|
|
---
|
|
|
|
# Skill Name
|
|
|
|
## 🎯 Purpose (Quick start)
|
|
|
|
[Minimal working example or brief introduction]
|
|
|
|
## 🚨 Prohibitions
|
|
|
|
[What is strictly forbidden?]
|
|
|
|
## Workflows
|
|
|
|
[Step-by-step processes with checklists for complex tasks]
|
|
|
|
## ✅ / ❌ Examples
|
|
|
|
[Concrete examples of right and wrong behavior]
|
|
```
|
|
|
|
## Description Requirements
|
|
|
|
The description is **the only thing your agent sees** when deciding which skill to load. It's surfaced in the system prompt alongside all other installed skills. Your agent reads these descriptions and picks the relevant skill based on the user's request.
|
|
|
|
**Goal**: Give your agent just enough info to know:
|
|
|
|
1. What capability this skill provides
|
|
2. When/why to trigger it (specific keywords, contexts, file types)
|
|
|
|
**Format**:
|
|
|
|
- Max 1024 chars
|
|
- Write in third person
|
|
- First sentence: what it does
|
|
- Second sentence: "Use when [specific triggers]"
|
|
|
|
**Good example**:
|
|
|
|
```
|
|
Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.
|
|
```
|
|
|
|
**Bad example**:
|
|
|
|
```
|
|
Helps with documents.
|
|
```
|
|
|
|
The bad example gives your agent no way to distinguish this from other document skills.
|
|
|
|
## When to Split Files
|
|
|
|
Split into separate files when:
|
|
|
|
- SKILL.md exceeds 100 lines
|
|
- Content has distinct domains (finance vs sales schemas)
|
|
- Advanced features are rarely needed
|
|
|
|
## Integration (Mandatory Final Step)
|
|
|
|
Once the user approves the draft, you MUST perform BOTH of these actions:
|
|
1. Use `create_directory` and `create_file` to save the new instruction into the agreed `.ai/skills/[skill-name]/SKILL.md` location.
|
|
2. Use `replace_string_in_file` to update `.ai/ai-root-instructions.md`. Add a new trigger line to the routing section so the new skill is discoverable.
|
|
|
|
## Review Checklist
|
|
|
|
After drafting, verify:
|
|
|
|
- [ ] Description includes triggers ("Use when...")
|
|
- [ ] Contains YAML frontmatter exactly as specified
|
|
- [ ] SKILL.md under 100 lines
|
|
- [ ] References one level deep
|
|
- [ ] No time-sensitive info
|
|
- [ ] Consistent terminology
|
|
- [ ] Concrete ✅ / ❌ examples included
|