jeninh 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
- 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.
- Progressive disclosure: Load metadata at startup, instructions when activated, resources only when needed
- 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