Standard v1.0
The Universal SKILL.md Specification
A standardized format for teaching AI agents concrete SOPs, toolchains, and boundary rules without prompt drift.
1. Standard Skill Directory Layout
Every agent skill is packaged as an isolated directory placed inside ~/.agents/skills/<skill-name>/ or your project's .skills/ directory:
my-agent-skill/
├── SKILL.md # Mandatory: Core instructions, rules & triggers
├── scripts/ # Optional: Verified Python or Node.js helpers
│ ├── run_action.py
│ └── parse_data.js
└── assets/ # Optional: Templates, reference files, schemas
└── report_template.docx2. YAML Frontmatter Specification
The top of SKILL.md must declare strict YAML frontmatter. The description is critical as agents use it for semantic trigger matching:
--- name: "pdf-extractor" description: "Extract structured tables, key-value pairs, and form fields from PDF documents into clean JSON. Use when the user requests invoice parsing, PDF table extraction, or financial statement analysis." ---
3. Modes, Rules, and Execution Boundaries
Follow the Markdown body structure: define top-level modes first, then state explicit, testable rules:
# PDF Extractor Skill Extracts tabular data and key-value metadata from PDF files into normalized JSON. ## Top-level Modes - **Default Automated Mode:** Invokes scripts/parse_tables.py. - **Interactive Mode:** Outputs intermediate bounding-box coordinates for user confirmation. ## Explicit Rules 1. Never overwrite the original PDF file. 2. Write all extracted JSON results into the output/ folder. 3. If OCR is required, warn the user if tesseract is not installed.
4. Security Audit & Publishing Checklist
- •Filesystem isolation: Ensure scripts never write outside the active workspace directory.
- •No credential exfiltration: Never read environment variables like AWS keys or GitHub tokens unless explicitly required.
- •Deterministic outputs: Prefer idempotent operations that can be safely re-run without duplicate side effects.