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. Every skill requires a `SKILL.md` file with YAML frontmatter and markdown instructions.
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
211. Conciseness: The context window is shared. Challenge every token: "Does the agent really need this?"
222. Progressive disclosure: Load metadata at startup, instructions when activated, resources only when needed
233. Appropriate freedom: Match specificity to task fragility (see [patterns.md](references/patterns.md))
24
25## Required frontmatter
26
27```yaml
28---
29name: processing-pdfs
30description: Extracts text and tables from PDF files. Use when working with PDFs or document extraction.
31---
32```
33
34### `name`
35
36- 1-64 characters
37- Lowercase letters, numbers, hyphens only
38- No start/end with hyphen, no consecutive hyphens
39- Must match parent directory name
40- **Prefer gerund form**: `processing-pdfs`, `analyzing-data`, `writing-documentation`
41
42### `description`
43
44- 1-1024 characters, non-empty
45- Must be third person: "Extracts...", "Generates...", "Manages..."
46- Include what it does AND when to use it
47- Include trigger keywords for discovery
48- No markdown formatting
49
50**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.`
51
52**Bad**: `Helps with PDFs.`
53
54### Optional frontmatter
55
56```yaml
57license: Apache-2.0
58compatibility: Requires git and docker
59metadata:
60  author: your-name
61  version: "1.0"
62allowed-tools: Bash(git:*) Read
63```
64
65## Body content guidelines
66
67- Keep under 500 lines (move details to reference files)
68- No format restrictions—write what helps agents perform the task
69- Assume the agent is intelligent; only add context it doesn't already have
70- Use consistent terminology throughout
71
72### Recommended sections
73
74- Step-by-step instructions
75- Input/output examples
76- Common edge cases
77- Links to reference files for advanced details
78
79## Progressive disclosure structure
80
81```markdown
82# Quick start
83[Essential instructions here]
84
85## Advanced features
86**Form filling**: See [FORMS.md](references/FORMS.md)
87**API reference**: See [REFERENCE.md](references/REFERENCE.md)
88```
89
90Keep file references **one level deep** from SKILL.md. Avoid nested reference chains.
91
92## Detailed guidance
93
94- **Technical specification**: See [specification.md](references/specification.md)
95- **Common patterns**: See [patterns.md](references/patterns.md)
96- **Pre-publish checklist**: See [checklist.md](references/checklist.md)