---
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: GPL-3.0-or-later
metadata:
  author: Amolith <amolith@secluded.site>
---

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.

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

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

### 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)