SKILL.md

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. Every skill requires a SKILL.md file with YAML frontmatter and markdown instructions.

skill-name/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
└── assets/           # Optional: templates, resources
  1. Conciseness: The context window is shared. Challenge every token: "Does the agent really need this?"
  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)

Required frontmatter

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

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

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
  • Assume the agent is intelligent; only add context it doesn't already have
  • Use consistent terminology throughout
  • Step-by-step instructions
  • Input/output examples
  • Common edge cases
  • Links to reference files for advanced details

Progressive disclosure structure

# 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