jeninh/authoring-skills

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.

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

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

# 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
• Technical specification: See specification.md
• Common patterns: See patterns.md
• Pre-publish checklist: See checklist.md