Docs / Skills
Skills
See what skills your agents load, which ones get used, and change them safely.
What it is
A skill is a directory holding a SKILL.md: a procedure your agent can follow. They arrive from three places at once — the project, your home directory, and every plugin you have installed — and nothing on your machine can tell you which copy actually loads.
Flanner Skills answers that. It reads every package your agent would see, works out which one wins, and tells you what is wrong with the collection. On the machine it was built against, 110 packages were installed and 57 were in effect. The other 53 were shadowed.
It is a read. Packages stay where their owner put them, flanner never edits them in place, and nothing inside one is executed by a scan.
Commands
flanner skills scanReads every skill package your agent would load, and records what it found. A read: nothing in a package is executed.
flanner skills list --allShows what is in effect, and with --all the copies that are being shadowed by another.
flanner skills doctorSays what is wrong. Exits 1 on a defect, so a check can gate on it.
flanner skills inspect matchaOne skill in full, including every copy of it and where each one lives.
flanner skills observe enableStarts recording which skills get invoked in this repository. flanner init already asks, and pressing Enter says yes; this turns it on if you said no.
flanner skills report --csvWhat was used, over a window you can see, with whether anything was watching during it.
The commands that list or report, such as scan, list, doctor and report, take --json. The full list is in the CLI reference.
What it checks
manifest_invalidDefect
The SKILL.md frontmatter is missing, unreadable, or names a different skill than its directory. An agent matches on that name.
shadowed_packageDefect or advice
The same name exists in more than one place with different contents. A defect when the copies come from different places, because editing the wrong one is the usual cause of a change doing nothing. Advice when they are revisions of one plugin, which is how an agent stores a plugin it has updated.
ambiguous_packageDefect
Copies of one skill differ, in an agent that offers every copy rather than picking one, as Codex does. Nothing on disk decides which runs, so the answer can change between turns.
duplicate_packageAdvice
Identical copies. One loads; the rest are dead weight.
stale_plugin_revisionAdvice
A cached revision your agent's own config no longer lists as installed. Nothing to do unless you are short of disk.
Every finding names the path it came from, so you can check the claim. Advice never fails doctor: it is a judgement you may disagree with, and a judgement should not break your build.
Watching what gets used
Per agent and per repository. flanner init asks whether to record skill use, and pressing Enter says yes; an init run with no one at the terminal leaves it off. What is recorded is that a named skill was invoked, when, and by which local session. Not your prompts, not the agent's replies, not the files it touched. None of it leaves your machine.
Only invocations are visible. Claude Code shows every skill's description to the model whether or not it is used, and does not report which were read, so a “loads” number would be made up. There is not one.
Every report carries the window it covers and whether anything was watching during it. Zero uses and zero coverage are different facts, and only one of them means a skill is unused.
Changing a skill safely
flanner skills adopt keeps a copy of a package where flanner can put it back. An install snapshots whatever it is about to replace, so flanner skills rollback always has something to restore.
A directory flanner did not install, or one you have edited by hand since, is refused rather than overwritten. Overwriting somebody's own edit is the failure worth being strict about.
A skill can also be proposed from work you hand over, reviewed, and approved. An approval covers the exact text you read: editing the draft afterwards sends it back for another look rather than shipping the edit under the old approval.
What your agent can do
Your agent can read skills: what loads, what is wrong, and what was used. Changing what it loads stays with you. The Skills page in the web UI covers much of this too, so the terminal is not the only way in.
See what loads and what is wrong
skills_report
The agent's read records nothing. `flanner skills scan` records by default.
See which skills were used
skills_usage
Turn watching on or off
flanner skills observe enable · flanner skills observe disable
Consent to being watched. An agent switching on its own monitoring would make the setting meaningless.
Delete recorded skill use
flanner skills data purge
Your record of your own work. Deleting it is never delegated.
Hand over work to learn from, and see what was handed over
skills_submit_evidence
An agent's report is labelled as its own account wherever it is shown.
Draft, revise and read skill proposals
skills_propose · skills_revise
An agent drafts for review. Revising a draft drops any approval it had.
Approve or reject a skill draft
flanner skills approve · flanner skills reject
An approval covers the exact text a person read. No model output may authorise its own installation.
Keep a copy, install it, or put it back
request_action
An agent only asks, with a preview. You apply it with `flanner actions apply`.
See kept versions and installs
flanner skills versions · flanner skills installs
Not offered to agents yet.
Send a skill to the team, or install one that arrived
request_action
An agent only asks, with a preview. You apply it with `flanner actions apply`.
See what arrived and what you follow
mesh_status
Follow a skill's updates
flanner skills channel subscribe · flanner skills channel unsubscribe
Following notifies you and never installs, so whoever publishes cannot steer what your agent reads.
Record evaluation cases and results
flanner skills eval add-case · flanner skills eval add-profile · flanner skills eval record
Not offered to agents yet. Flanner stores comparison results and does not run them. Running them is on the roadmap.
See the evaluation matrix
flanner skills eval matrix
Not offered to agents yet. It shows results somebody else produced. Flanner ran none of them.
An agent that could approve and install its own skills would be writing its own instructions. Compare Flanner Memory, where 16 of 21 operations are MCP tools, because a memory is context an agent reads and a skill is a procedure it follows.
The agent-blast-radius skill
flanner init installs three skills of its own, for Claude Code and Codex alike: flanner-plan, flanner-memory and agent-blast-radius. The third is how an agent uses Flanner Curb. Ask your agent how exposed your agents are, what one could read or send, or whether a secret leaked into an agent's history.
The skill has the agent run four commands in its shell, where you see and approve each one:
flanner curb mapEach agent launch's severity, its open channels, and what would close each.
flanner curb inventoryThe agents, settings layers, MCP servers, hooks, skills and scheduled jobs.
flanner curb sweepSecrets agents left behind, counted by exposure class. Needs the flanner[sweep] extra.
flanner curb observedWhat each agent has been seen using, when the action log is on.
It never sees names or locations. These commands print severities, categories and counts to every caller, and nothing more. The skill tells the agent not to look for the rest another way: not to search for the files, and not to read agent settings or transcripts to find what Curb left out.
For names and locations, the agent asks you to run flanner curb show yourself. It opens a window on your screen, and nothing from it comes back. If the agent runs it, it gets only a notice.
Changes stay yours. flanner curb fix, test, scrub and policy --approve ask your operating system for a yes. The skill tells the agent to suggest them, and never to try to get around the prompt. That part is an instruction. The redaction is not: it is what the commands do, whoever asks.
What it does not claim
It does not tell you a skill is unused. It tells you a skill was not invoked in a stated window, and whether anything was watching.
It does not measure what a skill costs you in context. Package size is bytes on disk, which is not the same thing, and the pages say so rather than converting one into the other.
It does not learn on its own. Nothing is read from your conversation history. A skill is proposed from work you handed over, and installed only after you approve that exact draft.
Comparisons are recorded, never run. Flanner calls no model provider, so a result comes from whatever actually ran it, and a combination nobody ran is reported as not run rather than as a zero.