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. Off until you run it.
flanner skills report --csvWhat was used, over a window you can see, with whether anything was watching during it.
Every command takes --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.
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
Off until you turn it on, per agent and per repository. 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. Nothing 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
Nothing. Every Skills operation is CLI-only, and unlike the gaps elsewhere on this site that is the whole design rather than a limit waiting to be lifted.
Read what skills are installed
flanner skills scan · list · inspect
A read, and one an agent has no use for: it already has its skills. The reader is you.
Find out what is wrong with them
flanner skills doctor
Exits non-zero on a defect so a check can gate on it. That is a command for you or your CI, not for a chat turn.
Turn observation on or off
flanner skills observe enable · status · disable
Consent to being watched. Letting the agent switch on its own monitoring would make the setting meaningless.
See what was used, and delete it
flanner skills report · data purge
Your record of your own work. Deleting it is never automatic and never delegated.
Hand over work to learn from
flanner skills evidence submit
Nothing is harvested. Evidence exists because you submitted it, which is what stops learning from becoming surveillance.
Draft, review, approve or reject a skill
flanner skills propose · review · approve · reject
An approval covers the exact text a person read. No observation and no model output can authorise its own installation.
Keep a copy, install it, put it back
flanner skills adopt · install · rollback
Writes into the directory your agent reads. A person decides what an agent loads.
Send one to your team, or install one they sent
flanner skills share · transfers · import
Receiving is not installing. Both ends are a person's decision, on a paid Mesh plan.
Follow a skill's updates
flanner skills channel subscribe · list
Following notifies you. It never installs, or whoever publishes would control what your agent reads.
An agent that could approve and install its own skills would be writing its own instructions. Compare Flanner Memory, where fourteen of nineteen operations are MCP tools, because a memory is context an agent reads and a skill is a procedure it follows.
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.