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: GPL-3.0-or-later
  6metadata:
  7  author: Amolith <amolith@secluded.site>
  8---
  9
 10Skills 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.
 11
 12```
 13skill-name/
 14├── SKILL.md          # Required: metadata + instructions
 15├── scripts/          # Optional: executable code
 16├── references/       # Optional: documentation
 17└── assets/           # Optional: templates, resources
 18```
 19
 20## Core principles
 21
 221. **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.
 232. **Progressive disclosure**: Load metadata at startup, instructions when activated, resources only when needed
 243. **Appropriate freedom**: Match specificity to task fragility (see [patterns.md](references/patterns.md))
 25
 26## Required frontmatter
 27
 28```yaml
 29---
 30name: processing-pdfs
 31description: Extracts text and tables from PDF files. Use when working with PDFs or document extraction.
 32---
 33```
 34
 35### `name`
 36
 37- 1-64 characters
 38- Lowercase letters, numbers, hyphens only
 39- No start/end with hyphen, no consecutive hyphens
 40- Must match parent directory name
 41- **Prefer gerund form**: `processing-pdfs`, `analyzing-data`, `writing-documentation`
 42
 43### `description`
 44
 45- 1-1024 characters, non-empty
 46- Must be third person: "Extracts...", "Generates...", "Manages..."
 47- Include what it does AND when to use it
 48- Include trigger keywords for discovery
 49- No markdown formatting
 50
 51The 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.
 52
 53**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.`
 54
 55**Bad**: `Helps with PDFs.`
 56
 57### Optional frontmatter
 58
 59```yaml
 60license: Apache-2.0
 61compatibility: Requires git and docker
 62metadata:
 63  author: your-name
 64  version: "1.0"
 65allowed-tools: Bash(git:*) Read
 66```
 67
 68## Body content guidelines
 69
 70- Keep under 500 lines (move details to reference files)
 71- No format restrictions—write what helps agents perform the task
 72- Information should live in either SKILL.md or references, not both
 73- Use consistent terminology throughout
 74- For large reference files (>10k words), include grep search patterns in SKILL.md
 75
 76### Recommended sections
 77
 78- Step-by-step instructions
 79- Input/output examples
 80- Common edge cases
 81- Links to reference files for advanced details
 82
 83### What NOT to include
 84
 85Skills should only contain what an agent needs to do the job. Do not create:
 86
 87- README.md, CHANGELOG.md, INSTALLATION_GUIDE.md, QUICK_REFERENCE.md
 88- Setup/testing procedures, user-facing documentation
 89- Auxiliary context about the skill's creation process
 90
 91These add clutter without helping agents perform tasks.
 92
 93## Progressive disclosure structure
 94
 95```markdown
 96# Quick start
 97[Essential instructions here]
 98
 99## Advanced features
100**Form filling**: See [FORMS.md](references/FORMS.md)
101**API reference**: See [REFERENCE.md](references/REFERENCE.md)
102```
103
104Keep file references **one level deep** from SKILL.md. Avoid nested reference chains.
105
106## Detailed guidance
107
108- **Creation process**: See [process.md](references/process.md)
109- **Technical specification**: See [specification.md](references/specification.md)
110- **Common patterns**: See [patterns.md](references/patterns.md)
111- **Pre-publish checklist**: See [checklist.md](references/checklist.md)