---
name: authoring-skills
description: 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.
compatibility: Requires filesystem access to create skill directories and files
license: AGPL-3.0-or-later
metadata:
  author: Amolith <amolith@secluded.site>
  version: "1.0"
---

Skills 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.

```
skill-name/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
└── assets/           # Optional: templates, resources
```

## Core principles

1. **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.
2. **Progressive disclosure**: Load metadata at startup, instructions when activated, resources only when needed
3. **Appropriate freedom**: Match specificity to task fragility (see [patterns.md](references/patterns.md))

## Required frontmatter

```yaml
---
name: processing-pdfs
description: Extracts text and tables from PDF files. Use when working with PDFs or document extraction.
---
```

### `name`

- 1-64 characters
- Lowercase letters, numbers, hyphens only
- No start/end with hyphen, no consecutive hyphens
- Must match parent directory name
- **Prefer gerund form**: `processing-pdfs`, `analyzing-data`, `writing-documentation`

### `description`

- 1-1024 characters, non-empty
- Must be third person: "Extracts...", "Generates...", "Manages..."
- Include what it does AND when to use it
- Include trigger keywords for discovery
- No markdown formatting

The 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.

**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.`

**Bad**: `Helps with PDFs.`

### Optional frontmatter

```yaml
license: Apache-2.0
compatibility: Requires git and docker
metadata:
  author: your-name
  version: "1.0"
allowed-tools: Bash(git:*) Read
```

## Body content guidelines

- Keep under 500 lines (move details to reference files)
- No format restrictions—write what helps agents perform the task
- Information should live in either SKILL.md or references, not both
- Use consistent terminology throughout
- For large reference files (>10k words), include grep search patterns in SKILL.md

### Recommended sections

- Step-by-step instructions
- Input/output examples
- Common edge cases
- Links to reference files for advanced details

### What NOT to include

Skills should only contain what an agent needs to do the job. Do not create:

- README.md, CHANGELOG.md, INSTALLATION_GUIDE.md, QUICK_REFERENCE.md
- Setup/testing procedures, user-facing documentation
- Auxiliary context about the skill's creation process

These add clutter without helping agents perform tasks.

## Progressive disclosure structure

```markdown
# Quick start
[Essential instructions here]

## Advanced features
**Form filling**: See [FORMS.md](references/FORMS.md)
**API reference**: See [REFERENCE.md](references/REFERENCE.md)
```

Keep file references **one level deep** from SKILL.md. Avoid nested reference chains.

## Detailed guidance

- **Creation process**: See [process.md](references/process.md)
- **Technical specification**: See [specification.md](references/specification.md)
- **Common patterns**: See [patterns.md](references/patterns.md)
- **Pre-publish checklist**: See [checklist.md](references/checklist.md)