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
 53Agents tend to undertrigger — they won't load a skill unless the description clearly matches the user's request. Be generous with trigger contexts. Include the obvious keywords, but also phrases the user might use when they need the skill without naming it directly. A description that triggers a few times when it isn't needed costs less than one that misses the cases where it would help.
 54
 55**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.`
 56
 57**Bad**: `Helps with PDFs.`
 58
 59### Optional frontmatter
 60
 61```yaml
 62license: Apache-2.0
 63compatibility: Requires git and docker
 64metadata:
 65  author: your-name
 66  version: "1.0"
 67allowed-tools: Bash(git:*) Read
 68```
 69
 70## Body content guidelines
 71
 72- Keep under 500 lines (move details to reference files)
 73- No format restrictions—write what helps agents perform the task
 74- Information should live in either SKILL.md or references, not both
 75- Use consistent terminology throughout
 76- For large reference files (>10k words), include grep search patterns in SKILL.md
 77- When the skill needs the agent to override its default behaviour (e.g., "write the test before the implementation"), explain the reasoning rather than relying on bare directives. The agent will follow a well-explained rationale more reliably than an all-caps MUST. Save the token economy for informational content the agent already knows.
 78
 79### Recommended sections
 80
 81- Step-by-step instructions
 82- Input/output examples
 83- Common edge cases
 84- Links to reference files for advanced details
 85
 86### What NOT to include
 87
 88Skills should only contain what an agent needs to do the job. Do not create:
 89
 90- README.md, CHANGELOG.md, INSTALLATION_GUIDE.md, QUICK_REFERENCE.md
 91- Setup/testing procedures, user-facing documentation
 92- Auxiliary context about the skill's creation process
 93
 94These add clutter without helping agents perform tasks.
 95
 96## Progressive disclosure structure
 97
 98```markdown
 99# Quick start
100[Essential instructions here]
101
102## Advanced features
103**Form filling**: See [FORMS.md](references/FORMS.md)
104**API reference**: See [REFERENCE.md](references/REFERENCE.md)
105```
106
107Keep file references **one level deep** from SKILL.md. Avoid nested reference chains.
108
109## Detailed guidance
110
111- **Creation process**: See [process.md](references/process.md)
112- **Technical specification**: See [specification.md](references/specification.md)
113- **Common patterns**: See [patterns.md](references/patterns.md)
114- **Pre-publish checklist**: See [checklist.md](references/checklist.md)