Defame1297
41c4da31cf
- Add agentskillsio/ reference docs (8 topic files, agentskills- prefix stripped) - Add agentsmd/ reference docs (4 topic files) - Add skill-write examples: skill-creator (Anthropic), writing-great-skills (mattpocock), writing-skills (obra/superpowers) with canonical sources.md files Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
125 lines
4.2 KiB
Markdown
125 lines
4.2 KiB
Markdown
---
|
||
topic: agentskills-specification
|
||
source_keys:
|
||
- agentskills-spec
|
||
---
|
||
|
||
## Frontmatter fields
|
||
|
||
| Field | Required | Constraints |
|
||
|----------------|----------|-------------|
|
||
| `name` | Yes | 1–64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen. No consecutive hyphens (`--`). Must match the parent directory name. |
|
||
| `description` | Yes | 1–1024 characters. Describes what the skill does and when to use it. |
|
||
| `license` | No | License name or reference to a bundled license file. |
|
||
| `compatibility`| No | 1–500 characters. Environment requirements: intended product, required system packages, network access needs. Most skills don't need this. |
|
||
| `metadata` | No | Arbitrary key-value map. Use for author, version, category, and any project extensions not defined by the spec. |
|
||
| `allowed-tools`| No | Space-separated string of pre-approved tools. Experimental — support varies by client. |
|
||
|
||
## Minimal example
|
||
|
||
```yaml
|
||
---
|
||
name: skill-name
|
||
description: A description of what this skill does and when to use it.
|
||
---
|
||
```
|
||
|
||
## Extended example
|
||
|
||
```yaml
|
||
---
|
||
name: pdf-processing
|
||
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
|
||
license: Apache-2.0
|
||
metadata:
|
||
author: example-org
|
||
version: "1.0"
|
||
category: document
|
||
allowed-tools: Bash(python3:*) Read Write
|
||
---
|
||
```
|
||
|
||
## name field rules
|
||
|
||
Valid: `pdf-processing`, `data-analysis`, `code-review`
|
||
|
||
Invalid:
|
||
- `PDF-Processing` — uppercase not allowed
|
||
- `-pdf` — cannot start with hyphen
|
||
- `pdf--processing` — consecutive hyphens not allowed
|
||
|
||
The `name` value must exactly match the parent directory name. A skill at `.agents/skills/my-tool/SKILL.md` must have `name: my-tool`.
|
||
|
||
## description field guidance
|
||
|
||
The description carries the entire burden of triggering. Agents read only `name` and `description` at startup. Write it as a trigger — describe both what the skill does and when to use it.
|
||
|
||
Good:
|
||
```yaml
|
||
description: >
|
||
Analyze CSV and tabular data files — compute summary statistics,
|
||
add derived columns, generate charts, and clean messy data. Use this
|
||
skill when the user has a CSV, TSV, or Excel file and wants to explore,
|
||
transform, or visualize the data, even if they don't explicitly mention
|
||
"CSV" or "analysis."
|
||
```
|
||
|
||
Poor:
|
||
```yaml
|
||
description: Helps with PDFs.
|
||
```
|
||
|
||
Hard limit: 1024 characters. Descriptions tend to grow during optimization — check length before committing.
|
||
|
||
## Body content
|
||
|
||
No format restrictions. Write whatever helps agents perform the task effectively.
|
||
|
||
Recommended sections:
|
||
- Step-by-step instructions
|
||
- Examples of inputs and outputs
|
||
- Common edge cases
|
||
|
||
The agent loads the entire body once the skill is activated. Keep `SKILL.md` under 500 lines. Move detailed reference material to separate files in `references/` or similar directories.
|
||
|
||
## Optional directories
|
||
|
||
### `scripts/`
|
||
|
||
Executable code agents can run. Scripts should be self-contained, include helpful error messages, and handle edge cases gracefully. See the scripts reference for design guidance.
|
||
|
||
### `references/`
|
||
|
||
Additional documentation agents can read when needed. Keep files focused — agents load them on demand, so smaller files mean less context use. Common files: `REFERENCE.md`, `FORMS.md`, domain-specific files (`finance.md`, `legal.md`).
|
||
|
||
### `assets/`
|
||
|
||
Static resources: templates, images, data files (lookup tables, schemas).
|
||
|
||
## File references
|
||
|
||
Use relative paths from the skill root when referencing other files:
|
||
|
||
```markdown
|
||
See [the reference guide](references/REFERENCE.md) for details.
|
||
Run: scripts/extract.py
|
||
```
|
||
|
||
Keep references one level deep from `SKILL.md`. Avoid deeply nested reference chains.
|
||
|
||
## Progressive disclosure levels
|
||
|
||
1. **Metadata** (~100 tokens): `name` and `description` — loaded at startup for all skills
|
||
2. **Instructions** (<5000 tokens recommended): full `SKILL.md` body — loaded on activation
|
||
3. **Resources** (as needed): files in `scripts/`, `references/`, `assets/` — loaded only when required
|
||
|
||
## Validation
|
||
|
||
The `skills-ref` reference library validates `SKILL.md` frontmatter and naming conventions:
|
||
|
||
```bash
|
||
skills-ref validate ./my-skill
|
||
```
|
||
|
||
Source: `https://github.com/agentskills/agentskills/tree/main/skills-ref`
|