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
  5user-invocable: true
  6license: LicenseRef-MutuaL-1.2
  7metadata:
  8  author: Amolith <amolith@secluded.site>
  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
 54Agents 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.
 55
 56**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.`
 57
 58**Bad**: `Helps with PDFs.`
 59
 60### Optional frontmatter
 61
 62```yaml
 63license: Apache-2.0
 64compatibility: Requires git and docker
 65metadata:
 66  author: your-name
 67  version: "1.0"
 68allowed-tools: Bash(git:*) Read
 69```
 70
 71## Body content guidelines
 72
 73- Keep under 500 lines (move details to reference files)
 74- No format restrictions—write what helps agents perform the task
 75- Information should live in either SKILL.md or references, not both
 76- Use consistent terminology throughout
 77- For large reference files (>10k words), include grep search patterns in SKILL.md
 78- 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.
 79
 80### Recommended sections
 81
 82- Step-by-step instructions
 83- Input/output examples
 84- Common edge cases
 85- Links to reference files for advanced details
 86
 87### What NOT to include
 88
 89Skills should only contain what an agent needs to do the job. Do not create:
 90
 91- README.md, CHANGELOG.md, INSTALLATION_GUIDE.md, QUICK_REFERENCE.md
 92- Setup/testing procedures, user-facing documentation
 93- Auxiliary context about the skill's creation process
 94
 95These add clutter without helping agents perform tasks.
 96
 97## Progressive disclosure structure
 98
 99```markdown
100# Quick start
101
102[Essential instructions here]
103
104## Advanced features
105
106**Form filling**: See [FORMS.md](references/FORMS.md)
107**API reference**: See [REFERENCE.md](references/REFERENCE.md)
108```
109
110Keep file references **one level deep** from SKILL.md. Avoid nested reference chains.
111
112## Detailed guidance
113
114- **Creation process**: See [process.md](references/process.md)
115- **Technical specification**: See [specification.md](references/specification.md)
116- **Common patterns**: See [patterns.md](references/patterns.md)
117- **Pre-publish checklist**: See [checklist.md](references/checklist.md)