SKILL.md format

A skill is a directory containing one required file (SKILL.md) plus optional supporting files. The format matches Anthropic’s Agent Skills spec.

Directory layout


skills/my-skill/
├── SKILL.md           ← required: frontmatter + markdown body
├── tools.py           ← OPTIONAL: @tool functions (Mode B)
├── scripts/           ← OPTIONAL: executable scripts (Mode A or C)
│   └── helper.py
└── reference.md       ← OPTIONAL: extra markdown the body links to

Frontmatter


---
name: standup-format
description: Format a daily standup from rough notes.
---
# Body in regular markdown follows.

Field	Required	Description
`name`	yes	Identifier shown to the model. Must be unique within a `skills=[...]` list.
`description`	yes	One-sentence summary the model uses to decide whether to load the skill.
`tools`	no	Mode C. Declares scripts as typed tools. See Three skill modes.
`license`	no	License string, kept on the skill’s metadata.
`compatibility`	no	Environment requirements, at most 500 characters.
`allowed-tools`	no	Space-separated tool names, as in the spec (`allowed-tools: bash read`). The older `allowed_tools` list form is still read. Recorded on `SkillMetadata.allowed_tools`.
`metadata`	no	A mapping of extra key/values.

Loomflow checks the frontmatter against the Agent Skills specification when a skill loads, and raises SkillError on a violation:

name: 1–64 characters of lowercase letters, digits and hyphens; it can’t start or end with a hyphen or contain --, and can’t contain the reserved words anthropic or claude. It should match the skill’s directory name; a mismatch warns.
description: non-empty, at most 1,024 characters, and no XML tags (<example>, </skill>, …). Claude’s skill rules forbid them, and they would open or close tags in the prompt the skill catalog is rendered into.
compatibility: at most 500 characters.

What the model sees at startup


Available skills:
- standup-format: Format a daily standup from rough notes.
- code-review:    Run a security-focused code review pass.
- meeting-notes:  Turn raw transcript into structured notes.

About 50 tokens per skill. The model calls load_skill(name) when the user’s request matches one. At that point the full SKILL.md body lands in the conversation.

Body conventions

The body is regular markdown. There’s no required structure, but useful patterns:

Lead with the goal. “When the user wants X, do Y.”
List the steps. Numbered. Concrete.
Reference bundled files: See ./reference.md for the full rubric — the agent can read_tool them on demand.
End with examples of input → output.

Bundled files

The agent reads bundled files via the standard read_tool / bash_tool it already has. Skills don’t need a new filesystem abstraction. If your SKILL.md says “see ./checklist.md for the full list,” the agent will issue a read_tool(path="checklist.md") call relative to the skill’s directory.

Skills are not auto-loaded into context. The name + description land in the system prompt; the body lands in context only when the model calls load_skill. This is the “progressive disclosure” property that lets you ship 50+ skills without blowing up context.