In-tree agent skills
This directory holds agent skills that ship as part of the tree. They are available to every developer who works in the tree, and an AI agent may load any of them automatically when a task looks relevant.
What belongs here
In-tree skills are for broadly useful, tree-wide workflows — the kind of thing that helps Firefox developers regardless of which team or component they work on. Good candidates are general utilities such as filing a bug, splitting commits, running a linter, or reorganizing patches for review.
Because these skills live in the tree, they carry an always-on cost: a skill’s
description is loaded into the agent’s context on every session so the agent can
decide when to invoke it. A description that is too broad can trigger the skill
where it shouldn’t. Keep this directory reserved for skills that are genuinely
worth that cost for the whole project.
What does not belong here
Skills that are useful but not for everyone — team-specific or component-specific workflows — should be published to a marketplace instead of being added in-tree, so developers can browse and enable only what they need:
Useful for Firefox developers, but not everyone: firefox-aidev-plugins. This marketplace is enabled by default in the Firefox tree, so developers just run
/pluginin Claude Code to browse and enable plugins — no extra setup needed.Not Firefox-specific, useful for any Mozilla developer: aidev-plugins, the public marketplace for general-purpose Mozilla plugins.
When in doubt, prefer a marketplace plugin: it reaches the people who need it without adding context cost for everyone else.
Reducing a skill’s listing cost instead
A skill’s body costs nothing until it is invoked; only the description is
always-on. So a family whose subject is component-specific but whose audience is
large can still earn a place here by keeping that cost down.
Two levers bring it down. The first is the description itself: most of the waste
is framing that restates the trigger words it already lists, and cutting it
leaves the triggers intact. The second is skillOverrides in
.claude/settings.json, which sets a skill’s listing mode without editing its
SKILL.md:
{
"skillOverrides": {
"some-skill": "name-only"
}
}
name-only lists the name without the description, so the skill no longer
auto-triggers but stays invocable by name and in the / menu. It suits a skill
that is only ever reached from another skill — a family’s shared mechanics, or
the reference half of a pair — because the referring skill’s body names it and no
trigger text is needed. Confirm a sibling actually refers to it before relying on
this. desktop-theme-probing is the worked example.
Adding a skill
Each skill lives in its own subdirectory and is defined by a SKILL.md file with
YAML frontmatter (at minimum a name and a description). Any supporting scripts
or assets the skill needs can live alongside it in the same subdirectory. See the
existing skills in this directory for examples.
.claude/skills/ and .agents/skills/ mirror each other and must be
byte-identical; the agent-skills-sync linter enforces it. It compares every
tracked file byte for byte, scripts and assets included. Run
./mach lint -l agent-skills-sync .claude/skills from the checkout root before
submitting, or add --fix to propagate whichever side changed. Any path inside
either directory runs the comparison over both whole mirrors. Mozlint skips the
linter for a path outside them, and with no paths it lints only outgoing and
working-copy changes.
The linter reads tracked files only, so an untracked file on one side is invisible
to it. diff -rq -x __pycache__ .claude/skills .agents/skills is the backstop; it
excludes __pycache__ because importing a bundled script, as a test does, writes
one beside it on whichever side it was imported from.