Skip to main content

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

FieldRequiredWhat it does
nameyesSkill identity. Must match the directory and the spec pattern (^[a-z0-9]+(-[a-z0-9]+)*$)
descriptionyesWhat it does and when to use it, ≤1024 chars. This is the router's only signal
licenseyes for membersSPDX id or expression (MIT, Apache-2.0, MIT OR Apache-2.0), or UNLICENSED. Prose like MIT License fails verify
compatibilitynoFree-form environment requirement, ≤500 chars, e.g. Requires Bash and git access
allowed-toolsnoSpace-, comma- or list-separated tool names. Narrows the tool surface, never widens it
metadata.versionyes for membersSemver. agenthood bump <member> --patch increments it and re-locks
metadata.authorto publishRegistry namespace: the owner in owner/name. Lowercase letters, digits, single hyphens
metadata.*noAny nested shape: maps, lists, booleans. Passed through untouched for your own tooling
hiddennotrue keeps the skill out of the available-skills catalog. It still activates by name
disable-model-invocationnotrue hides the skill from the catalog and the activate_skill enum. /skill-name still works, for user-invoked-only workflows
metadata.prioritynoWhole number 0-100. Higher sorts earlier in the catalog (verify rejects out-of-range)
metadata.conditionsnoPredicates that must hold before activation: env:NAME, env:NAME=value, file.exists:path (under the project root), git.status:dirty|clean
fallbacknoOrdered skill names to try when this one cannot activate: a fallback chain, capped at three hops, disabled with --no-fallback
routernotrue 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 with
file.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 in
src/skills/discovery/SkillParser.ts;
member tool derivation lives in
src/members/MemberRegistry.ts:

// MemberRegistry: declared ∩ profile: narrowing only (#641)
static intersectDeclaredTools(declared: string, permission: PermissionProfile): string[] {
  const set = new Set(declared.split(/\s+/).filter(Boolean))
  return MemberRegistry.toolsByProfile[permission].filter((t) => set.has(t))
}

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:

mkdir -p skills/the-notetaker

Write skills/the-notetaker/SKILL.md:

---
name: the-notetaker
description: Turns raw meeting transcripts into decisions, owners, and follow-ups. Use when a transcript needs to become action items.
allowed-tools: file.read file.search ask_human
license: MIT
compatibility: Requires a local file path to the transcript
metadata:
  version: 1.0.0
---

# The Notetaker

Read the transcript the user points you at. Extract:
1. Decisions made (verbatim where possible)
2. Owners and deadlines
3. Open questions

Ask the user before guessing an owner. Never invent a date.

Validate, then invoke through any member run that has it in scope:

npx agenthood verify            # frontmatter shape + name↔directory match
npx agenthood run scribe "summarize meeting.txt using the-notetaker's format"

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

  • name matches the directory, lowercase-hyphenated
  • description says what and when ("Use when …")
  • license is an SPDX id, metadata.version is semver
  • allowed-tools declares the minimum: leave the dangerous ones out
  • Body reads like onboarding for a careful new hire
  • npx agenthood verify passes; agenthood.lock re-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-only
allowed-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