Skills & The Agency
A skill is a packaged ability an agent can use. Headmaster ships with a set of built-in skills; you can install more from the Agency — the open catalog the desktop fetches from the Headmaster Hub registry.Skill tiers
The Agency
The Agency is a curated catalog of community-contributed skills, fetched from the Hub registry. To open it:1
Click Browse the Agency
Click Browse the Agency in the Skills tab. The desktop fetches the catalog from the registry.
2
Browse by department
3
Hire a skill
Click Hire on any skill card. The skill downloads, installs, and appears under “Open Casting.”
Adding a skill manually
If you authored a skill yourself:1
Write the skill definition
Create a
SKILL.md file with the skill’s instructions, triggers, and parameters.2
Package it
Package it as a
.zip with the skill file and any supporting assets.3
Drop into skills folder
Drop the package into
<data folder>/skills/.4
Restart Headmaster
The skill appears under “My Skills.”
~/.claude/skills, ~/skills) or paste an absolute path. Headmaster scans for SKILL.md files.
Skill structure
A skill package contains:SKILL.md file uses YAML frontmatter:
Example: PR review skill
Enabling and disabling skills
Skills are managed per-specialist:1
Open the specialist
Go to Settings → Specialists and pick a specialist.
2
Go to Skills
Open the Skills section.
3
Toggle on/off
Check/uncheck skills to enable or disable them. Save.
A skill toggled on is available in all conversations with that specialist. Built-in skills can be disabled but not removed. Custom skills can be both disabled and removed.
Removing a skill
Click Remove on a skill card in the Skills tab. The skill is uninstalled and its data is removed. Sessions that used the skill keep their transcripts — the skill’s effects are permanent, but the skill itself is no longer available for future conversations.Skills in chat
When a skill is active in a conversation:- You see it on the On the Team indicator at the top of the chat.
- The agent announces when it’s about to call a skill.
- The skill’s output appears as a tool call result block you can expand.
Skill suggestions
The agent may suggest enabling a skill mid-conversation:
“I notice you’re asking me to review a PR. I have a pr-review skill that could do this more thoroughly. Want me to enable it?”
Click Enable to add the skill to the conversation.
Skill best practices
- One job per skill — a skill should do one thing well, not five things poorly.
- Be explicit — write instructions as step-by-step imperative sentences.
- Use triggers — define clear trigger conditions so the agent knows when to use the skill.
- Test before sharing — run the skill end-to-end on the latest Headmaster build before submitting to the Agency.
- No vendor lookalikes — use your own branding and personality.
- Version your skills — bump the version in the frontmatter when you change the skill’s behavior.
Publishing to the Agency
To share a custom skill with the community:1
Package the folder
Zip the skill folder with the
SKILL.md and supporting files.2
Submit a pull request
Open a PR to the Headmaster Hub repo.
3
Review and publish
The skill is reviewed and, if accepted, published to the Agency catalog.
Specialists
Configure which skills are enabled per specialist.
Connections (MCP)
Extend skills with MCP server tool bundles.