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

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

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

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

# 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