SKILL.md

  1---
  2name: authoring-skills
  3description: Creates well-structured Agent Skills following best practices. Use when writing new skills, reviewing existing skills, or when the user mentions skill authoring or Skills.
  4compatibility: Requires filesystem access to create skill directories and files
  5license: AGPL-3.0-or-later
  6metadata:
  7  author: Amolith <amolith@secluded.site>
  8  version: "1.0"
  9---
 10
 11Skills extend agent capabilities through a simple folder structure. Think of them as onboarding guides—they transform a general-purpose agent into a specialized one equipped with procedural knowledge no model can fully possess.
 12
 13```
 14skill-name/
 15├── SKILL.md          # Required: metadata + instructions
 16├── scripts/          # Optional: executable code
 17├── references/       # Optional: documentation
 18└── assets/           # Optional: templates, resources
 19```
 20
 21## Core principles
 22
 231. **Conciseness**: The context window is a public good. Default assumption: the agent is already smart. Only add context it doesn't already have. Does this paragraph justify its token cost? Prefer concise examples over verbose explanations.
 242. **Progressive disclosure**: Load metadata at startup, instructions when activated, resources only when needed
 253. **Appropriate freedom**: Match specificity to task fragility (see [patterns.md](references/patterns.md))
 26
 27## Required frontmatter
 28
 29```yaml
 30---
 31name: processing-pdfs
 32description: Extracts text and tables from PDF files. Use when working with PDFs or document extraction.
 33---
 34```
 35
 36### `name`
 37
 38- 1-64 characters
 39- Lowercase letters, numbers, hyphens only
 40- No start/end with hyphen, no consecutive hyphens
 41- Must match parent directory name
 42- **Prefer gerund form**: `processing-pdfs`, `analyzing-data`, `writing-documentation`
 43
 44### `description`
 45
 46- 1-1024 characters, non-empty
 47- Must be third person: "Extracts...", "Generates...", "Manages..."
 48- Include what it does AND when to use it
 49- Include trigger keywords for discovery
 50- No markdown formatting
 51
 52The description is the primary trigger mechanism. The body only loads *after* activation, so "When to Use" sections in the body don't help agents discover the skill.
 53
 54**Good**: `Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.`
 55
 56**Bad**: `Helps with PDFs.`
 57
 58### Optional frontmatter
 59
 60```yaml
 61license: Apache-2.0
 62compatibility: Requires git and docker
 63metadata:
 64  author: your-name
 65  version: "1.0"
 66allowed-tools: Bash(git:*) Read
 67```
 68
 69## Body content guidelines
 70
 71- Keep under 500 lines (move details to reference files)
 72- No format restrictions—write what helps agents perform the task
 73- Information should live in either SKILL.md or references, not both
 74- Use consistent terminology throughout
 75- For large reference files (>10k words), include grep search patterns in SKILL.md
 76
 77### Recommended sections
 78
 79- Step-by-step instructions
 80- Input/output examples
 81- Common edge cases
 82- Links to reference files for advanced details
 83
 84### What NOT to include
 85
 86Skills should only contain what an agent needs to do the job. Do not create:
 87
 88- README.md, CHANGELOG.md, INSTALLATION_GUIDE.md, QUICK_REFERENCE.md
 89- Setup/testing procedures, user-facing documentation
 90- Auxiliary context about the skill's creation process
 91
 92These add clutter without helping agents perform tasks.
 93
 94## Progressive disclosure structure
 95
 96```markdown
 97# Quick start
 98[Essential instructions here]
 99
100## Advanced features
101**Form filling**: See [FORMS.md](references/FORMS.md)
102**API reference**: See [REFERENCE.md](references/REFERENCE.md)
103```
104
105Keep file references **one level deep** from SKILL.md. Avoid nested reference chains.
106
107## Detailed guidance
108
109- **Creation process**: See [process.md](references/process.md)
110- **Technical specification**: See [specification.md](references/specification.md)
111- **Common patterns**: See [patterns.md](references/patterns.md)
112- **Pre-publish checklist**: See [checklist.md](references/checklist.md)