Authoring a Skill
A skill that fails to parse never runs, and the contract that prevents that is small.
What it is
A skill in Agenthood is one Markdown file: YAML frontmatter on top (the machine-readable
contract) and a prompt body below (the human-readable protocol). Providers read the file
as-is; the runtime additionally parses the frontmatter to decide what the skill is called,
when it should activate, and which tools it is allowed to use.
The frontmatter is where a skill fails first. name must match the directory
and follow the lowercase-hyphen rule, and description must say what the skill
does and when to use it. Since PR #904,
the runtime also enforces allowed-tools: a declaration can narrow the tool
surface below the skill's permission profile, never widen it. A skill that
declares nothing keeps the profile default, which is permissive but no longer
invisible.
The frontmatter fields
| Field | Required | What it does |
|---|---|---|
name | yes | Skill identity. Must match the directory and the spec pattern (^[a-z0-9]+(-[a-z0-9]+)*$) |
description | yes | What it does and when to use it, ≤1024 chars. This is the router's only signal |
license | yes for members | SPDX id or expression (MIT, Apache-2.0, MIT OR Apache-2.0), or UNLICENSED. Prose like MIT License fails verify |
compatibility | no | Free-form environment requirement, ≤500 chars, e.g. Requires Bash and git access |
allowed-tools | no | Space-, comma- or list-separated tool names. Narrows the tool surface, never widens it |
metadata.version | yes for members | Semver. agenthood bump <member> --patch increments it and re-locks |
metadata.author | to publish | Registry namespace: the owner in owner/name. Lowercase letters, digits, single hyphens |
metadata.* | no | Any nested shape: maps, lists, booleans. Passed through untouched for your own tooling |
hidden | no | true keeps the skill out of the available-skills catalog. It still activates by name |
disable-model-invocation | no | true hides the skill from the catalog and the activate_skill enum. /skill-name still works, for user-invoked-only workflows |
metadata.priority | no | Whole number 0-100. Higher sorts earlier in the catalog (verify rejects out-of-range) |
metadata.conditions | no | Predicates that must hold before activation: env:NAME, env:NAME=value, file.exists:path (under the project root), git.status:dirty|clean |
fallback | no | Ordered skill names to try when this one cannot activate: a fallback chain, capped at three hops, disabled with --no-fallback |
router | no | true marks a routing entry point, for setups with too many skills to list in full |
metadata is deliberately unconstrained: nest a provider map or a dependency pin under it and
the runtime neither validates nor rewrites it. Tool skills in skills/ use it to declare
install commands (metadata.dependencies).
The body is pure prompt. No format is enforced on it, which is exactly why the best bodies
read like onboarding docs for a careful new hire.
Why it matters in production
Skills are loaded by an agent that is trying to pick the right one from the description
line alone. Vague descriptions misroute: a skill whose description says "helps with code"
competes with every other skill in the registry, and the provider's choice is a coin flip.
Undeclared or over-broad tool sets are the inverse problem: the skill runs, but withfile.write in a review-only workflow, and nobody notices until a bot edits a file it
should never touch. The narrow-only rule means a SKILL.md edit can never escalate
privileges; drift gets caught by agenthood verify and the agenthood.lock hash gate.
How Agenthood implements it
Parsing and validation live insrc/skills/discovery/SkillParser.ts;
member tool derivation lives insrc/members/MemberRegistry.ts:
Tool vocabulary members may declare: file.read, file.write, file.search, code.write,code.refactor, code.explain, pr_sync (trusted profile only). ask_human needs no
declaration: every member can park for human input regardless of frontmatter.
Hands-on example
Create a read-only meeting-notes skill in your project:
Write skills/the-notetaker/SKILL.md:
Validate, then invoke through any member run that has it in scope:
agenthood run executes registered members, not arbitrary skill files, so the demo
hands the new skill's format to a member that is registered. To see it used as a
standalone prompt, copy skills/the-notetaker/ into your provider's skill path
(.agents/skills/, .claude/skills/, …) and invoke it there. (agenthood activate
covers registered members only.)
Expected: verify reports the skill parses cleanly; if you typo name: the-notetakers
(mismatched directory), verify fails the run before anything loads, that is the gate
doing its job.
Checklist before you ship
-
namematches the directory, lowercase-hyphenated -
descriptionsays what and when ("Use when …") -
licenseis an SPDX id,metadata.versionis semver -
allowed-toolsdeclares the minimum: leave the dangerous ones out - Body reads like onboarding for a careful new hire
-
npx agenthood verifypasses;agenthood.lockre-locked if a member changed
Share what you ship
LinkedIn post draft: I built an agent skill in one Markdown file, and it had a
trust boundary. Agenthood's SKILL.md contract: a trigger-phrase description, a narrow-onlyallowed-tools list, and a verify gate that fails the build, not the production.
A skill that cannot be parsed is a skill that never runs.
Further reading
- ADR-028: SKILL.md Frontmatter as an Enforced Contract
src/skills/discovery/SkillParser.ts: validation source- Agent Skills specification: the upstream format
allowed-toolscomes from