skill-curation
Consolidate, dedupe, and prune the skill library — merge overlapping skills into one (absorbed_into), delete truly dead skills, and keep the manifest honest. Use when the doctor flags skill drift, two skills overlap, or a lifecycle run surfaces consolidation candidates.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 4
- Forks
- 1
01 前言 Front Matter
- name
- skill-curation
- version
- 1.1.0
- triggers
- [ "curate skills", "consolidate skills", "merge skills", "prune skills", "skill dedupe" ]
- description
- Consolidate, dedupe, and prune the skill library — merge overlapping skills into one (absorbed_into), delete truly dead skills, and keep the manifest honest. Use when the doctor flags skill drift, two skills overlap, or a lifecycle run surfaces consolidation candidates.
02 资源文件 3
- 参考文档references/always-section-consolidation.md4.6 KB
- 参考文档references/discovery-sources.md2.7 KB
- 参考文档references/skill-evaluation-pipeline.md8.7 KB
03 SKILL.md 正文
Skill Curation
Consolidate, dedupe, and prune the skill library. Curation is the counterweight to creation: every new skill is debt until it earns its place, and a merged skill serves better than two overlapping ones.
When to Curate
- After a lifecycle run (orch-skill-lifecycle Monday deep eval)
- When 2+ skills overlap —
skills_list(category=...)shows same-domain entries with similar descriptions - On any deletion — always declare
absorbed_into=<umbrella>(merged into an existing skill) orabsorbed_into=""(true prune) so downstream tooling (cron-job skill references, the curator) knows intent - When the doctor flags skill drift, duplicates, or deployed orphans
Rules
-
Prove duplication first. Load both skills and compare structure AND content — descriptions alone lie. Overlap > 50% → merge; otherwise keep both and note the boundary.
-
Improve existing before creating. The merge target is the existing skill — extend it, never spawn a sibling. If the two are equal weight, keep the one with better structure, fold the other's unique sections in.
-
Redirects carry real bodies AND the redirect in their
description. A deprecated skill keeps a body that explicitly routes to the replacement — never a placeholder — and the SAME routing text in itsdescription, because a loader REFUSES a SKILL.md whose description is absent or blank: the stub is then never loaded, so its "merged into X, load X instead" body reaches nobody and the tombstone is pure context cost with zero effect. Analiases: [<old-name>]entry on the TARGET is the belt-and-braces form; the stub alone is what actually resolves the old name. Deleting a redirect without a forwarding target orphans every reference to the old name. The doctor'sSkills loadablecheck FAILs on exactly this class — a missing or blank description, a name outside[a-z0-9-], frontmatter that does not parse, a duplicate mapping key PyYAML accepts but a loader rejects — so run it after any consolidation pass instead of eyeballing the tombstones. Check WHICH MODE that check ran in — a degradation it does not announce is a PASS over files it never read. The rules above need a YAML parser, and the doctor runs under whateverpython3is on PATH, which on a fleet host is often a runtime venv without PyYAML; it then falls back to a TEXT scan and reports a WARN naming the rules it skipped (name charset, YAML parse, duplicate keys). Read that warning before trusting a bareSkills loadable ✅: it is a weaker result, not a clean one. Repair the interpreter (fix-fleet-venv.py) and re-run, or invoke the doctor underFLEET_PYTHON/~/.steadfaste-fleet/venv/bin/python3, so the full rule set is actually applied. But the durable fix lives in the CHECKER, not in the invocation. Advice that says "invoke this under the right interpreter" depends on every caller remembering, and the caller that forgets is the one that gets a false green. A check should resolve its OWN interpreter — an explicit override env var first, then the fleet venv, each probed by actually RUNNING it in a clean environment — and re-exec itself once, guarded by an env flag so it cannot loop. A check that resolves for itself cannot be run wrong. The general rule for any check that depends on a library: a checker that CANNOT read its input has no verdict — it must say so loudly, and it must never emit a success line for the inputs it never examined, because a green tick over unread files is worse than a visible failure. -
Check consumers before pruning. A deployed-only skill may be referenced by crons, manifests, or other skills. Grep jobs.json, install-crons.sh, and skills before
delete. Deploy warnings are not deletes. A deployed-only skill is also an orphan — no repo source, so the doctor reportsStale skills: orphanedand one deploy can remove it. Import it into the repo or delete it deliberately; never leave it half-owned, and same for areferences/file that exists only deployed.A third-party PLUGIN dump is a third case: neither import nor delete. A directory carrying its own plugin manifest (
package.json,<tool>.plugin.json,_meta.json) whoseSKILL.mdhas no frontmatter has no repo source to import and no owner left to repair it. Check the RUNTIME first (command -v <tool>; its config directory) — the skills such a dump ships are instructions to call tools that exist only while that plugin is loaded, so with the runtime gone they are prompts to call nothing. Then PRESERVE it by MOVING it into a dot-directory inside the same skills tree (<skills>/.archive/<name>-<tool>/) rather than deleting: loaders skip dot-dirs, so it leaves every agent's view and stays recoverable. Assert destination-absent before the move (never clobber), then assert the file COUNT at the destination matches the source's.A ROOT-LEVEL skill directory is never pruned by a deploy — the updater's stale pass treats a path with no
/in it as a Hermes default and skips it. So a removal like that is not undone by an update, and it does not propagate either: another host carrying the same dump still gets the doctor WARN, which is the correct behaviour — report it there, do not delete it fleet-wide from one host's evidence. -
Verify after every merge/delete.
skill_viewboth skills, re-read the merged SKILL.md for fence balance, run the doctor, regenerate the manifest if skills/ changed. -
The REPO is the source of truth — a curatorial edit made on the DEPLOYED copy is STRANDED, not shipped.
skill_managewrites the DEPLOYED copy (~/.hermes/skills/<...>), while the fleet receives onlysteadfaste-fleet/skills/<category>/<name>/. A deploy then either overwrites that copy or — where the drift guardrail is in force — SKIPS it; either way the lesson reaches no other host, and the doctor reports it as skill drift ("Deployed copy is newer than repo source"). The doctor names it: "Deployed copy is newer than repo source. Commit the repo source before fleet-update overwrites it." After ANY skill edit, propagate the deployed skill back to the repo path (the whole dir,references/included) and commit it in the same run. Check for drifted pairs at the start of a pass too: drift means a previous run's lesson is still unlanded, and re-deriving it instead of propagating it duplicates the work. Verify withdiff— the only acceptable difference is the deploy header.Measure drift by CONTENT, never by mtime.
python3 ops/scripts/manage/check-skill-drift-parity.py(exit 1 = stranded; regeneratesdocs/evidence/skill-drift-parity.txt). A file is stranded when its DEPLOYED content appears neither in the repo working tree nor in any committed revision of that path. mtime is useless here — a clone or checkout resets every repo mtime to "now", so an mtime comparison reports "repo is newer" while the content exists nowhere in the repo and the drift goes unnoticed. It compares EVERY file under the deployed tree, not justSKILL.md, so a driftedreferences/file is visible too.Decide the direction PER FILE by reading the diff — the deployed side is often the CURATED one. A deployed lesson may have been rewritten to generalise, so it can ADD lines AND REMOVE lines the repo still has: never copy it in blind, and never assume the repo side is the superset. The deploy header sits AFTER the shebang and is closed by a blank line, so a fixed
tail -n +4misaligns the comparison — strip the header LINES and diff what remains. Copy the canonical content in, re-run the parity check toPASS, then deploy to clear the doctor's warnings.Recover with the repo's own tooling — and judge its output by CONTENT, not by its own line counts. Run
python3 ops/scripts/manage/reconcile-stranded-skills.py(report by default) and land the pure-superset class with--apply. Its REVIEW class is not a refusal to act: the tool compares whole LINES, so a paragraph that was REWRAPPED or condensed reports every one of its lines as a "drop". Collapse whitespace on both sides and word-diff instead — most REVIEW entries then show ZERO repo-only word runs and are pure supersets in substance. Make the copy DECIDABLE before making it: run both sides throughdifflib.SequenceMatcherand collect the non-equalopcodes — at most ONE line-dropping block (an in-place rewrite) plus insertions means the deployed side is that content, so copy it; two or more dropping blocks means the newer copy genuinely REMOVED content you must read first. Assert the count rather than eyeballing a diffstat, and keep the assertion in the script so a later reconcile cannot quietly take a side it should have read. Only a phrase genuinely absent from the deployed copy needs a decision, and the answer is often "superseded in place": a newer copy that CORRECTS a wrong claim (an obsolete design description, a rule reworded to include the mechanism the fleet now uses) must be landed AS-IS, because merging the old wording back restores the error it removed. Land by copying the file and ASSERTING sha256 equality on both sides, so byte-identical is verified rather than claimed. Re-run the report afterwards: it must saystranded: 0.Two classes, and the doctor only reports one of them. "Stranded in place" (the path IS in the repo, its content only deployed) is what the doctor's
Skill driftline counts, and the line flips to PASS when that reaches 0. The parity checker ALSO reports "absent from the repo" — files under a repo-owned skill dir the repo has never carried at all, markeddropped-from-repoornever-committed. Driving the first to 0 leaves the checker's VERDICT at FAIL, so read both numbers before reporting the class as fixed, and keep the trackeddocs/evidence/skill-drift-parity.txtregenerated and committed (it records the verdict; leaving it stale is the same defect one level up).Recovering a skill's SCRIPT is the step that stalls: the pre-commit TDD gate refuses an ADDED code file with no test in the same commit. The gate scans
--diff-filter=Aforpy|ts|tsx|js|jsx|mjs|cjs|go|rs|…and has no bypass flag, and askills/<name>/scripts/<file>.pyis exactly that — so the asset sits uncommitted indefinitely, which is a large part of why this class accumulates. Do NOT stage an unrelated test to satisfy it; add the guard the gate is actually asking for.tests/test_skill_code_assets_parse.pyis that guard: one discovery traversal overskills/**that compiles.pyand parse-checks.mjs/.js/.sh, so a newly recovered asset is covered the moment it lands. Extend it rather than writing a second one, and keep its non-vacuity assertion (it FAILs when it finds no assets at all).Read a recovered DOCUMENT before landing it — the recovery leaves defects of its own. A recovered reference is not good because it came from a host where it worked: a redaction pass can destroy the very distinction the document teaches (a fix example whose "before" and "after" lines are byte-identical because both were rewritten to the placeholder), and a recovered script can carry the bug it warns about (reading a column by hardcoded INDEX while
PRAGMA table_infowas already fetched). These are cheap to fix while landing and expensive later: the close judges each recovered file as its own blob, so a self-contradicting document is found one blob and one review round at a time, and every fix commit grows a range that was already too wide. Read for the artifact of the RECOVERY, not only for the lesson.Price a bulk recovery by CLAIM, not by file count. The close reviewer judges what each recovered blob CLAIMS. A document that presents an incident note as a live statement about code is judged as BEHAVIOUR, so a committed re-runnable test is demanded — which cannot exist for a past measurement, and the file's real claim is a POINTER to a record instead. Land recovered history declaring itself as history (what it is a record OF, and as-of when) rather than as specification, and land recovered prose in WAVES: a range whose files each need a verdict costs passes in proportion to its FILE count, so a one-hundred-file recovery commit is the most expensive shape available. Expect the class and diagnose it as a claim-type mismatch, not as a fault in the recovered text.
-
A same-name collision from a
local-*skill is the OVERRIDE WORKING — do not "fix" it. A host-locallocal-<x>skill deliberately keeps the fleet skill'sname: <x>, so it wins the name collision and the fleet copy is skipped: that IS the per-host override mechanism, and the harness reports it as a collision warning rather than an error. Renaming the local skill'sname:to match its directory makes BOTH load and the override silently stops working.fleet-update.sh's stale pass preserves everylocal-*directory for the same reason. Alocal-*skill that carries a real frontmatter defect (a duplicate key, a name outside the charset) is still broken, though — the collision is expected, the parse failure is not.How a collision arises at all — the name falls back to the DIRECTORY. A loader uses
frontmatter.name, and when that is absent it uses the skill directory's own basename, so a directory carrying noname:is advertised under its DIRECTORY name and can collide with a different skill that declares that name in frontmatter. On collision the loser is skipped and the winner is whichever the traversal reached first — decided by readdir order, not by intent — which is precisely the mechanism alocal-*override exploits on purpose. Note the interaction with rule 3: a SKILL.md with no DESCRIPTION never reaches the name map at all, so a no-frontmatter dump is dropped outright and its only effects are the diagnostic and the index cost. Read the loader's own DIAGNOSTICS LIST before calling something a collision — the two failures look identical in a directory listing and are different findings.A stray non-skill
.mdin the tree is a PHANTOM candidate. ADESCRIPTION.md,README.mdor similar sitting inside a category directory is enumerated as a skill whose name falls back to the DIRECTORY, soskills/<cat>/DESCRIPTION.mdpresents as a second skill named after its category and collides with the real one — and since the winner is readdir order, the phantom can win. Keep non-skill markdown out of the skill tree, and read a collision whose loser is a frontmatter-less.mdas this shape rather than as a deliberate override. -
A retired skill name is not done at the stub — sweep every REFERENCE to it, then guard it. A stub only helps a caller who already holds the old name; a reference in another skill's prose or
related_skillscosts a wasted load BEFORE the redirect fires. A consolidation pass therefore ends with a sweep and a check, not with the tombstone.- Sweep the two places a
SKILL.md-only scan cannot see: backticked names inreferences/andtemplates/, andrelated_skillsread as PARSED YAML — the list may be nested undermetadata.hermesor span several lines, so a single inlinerelated_skills: [...]grep pattern finds barely half the hits. Parse the frontmatter and collect from BOTH locations. - Rewrite each hit to the stub's
absorbed_into/replaced_bytarget, and require that field on every stub. With it the sweep is mechanical and assertable; without it every hit is a judgement call about where the content actually went. Assert the replacement COUNT per file, then re-scan for zero remaining. - Scope the guard to a CLOSED set. Match only names that actually carry
deprecated: true, so the check cannot fire on prose that merely looks name-like. The tempting version — "everyrelated_skillsentry must resolve inside this tree" — is noisy: a skill can be provided from a tree you are not scanning, and some entries name a TOOL rather than a skill. Precision is the feature; a guard that cries wolf teaches its reader to scroll past it. - Check repeats PER LIST, not across merged lists. A file may legitimately declare the
same entries at the top level AND under
metadata.hermes; merging them reports a phantom duplicate. The defect worth checking is a repeat WITHIN one list. - Scan for what the sweep LEFT BEHIND, not only for what it matched. Redirecting
old->newcreates a duplicate list entry whenever the list already namednew, and collapses two related bullets onto one skill when both pointed at names redirecting to the same target; a gloss describing the OLD skill then sits under the new name and must be rewritten to match — the redirect moves the annotation too. An asserted match count catches none of these, because they are consequences of a CORRECT replacement, so the sweep needs its own second pass looking for them.
- Sweep the two places a
Manifest Discipline
- After any skill add/rename/delete: regenerate
docs/SKILLS-MANIFEST.mdviagen-skills-manifest.py(never hand-edit). - Keep category counts truthful — a stub or placeholder body in the repo is a curation debt: flag for restore, don't let it ship.
Anti-Patterns
- Merging by description without reading both files
- Deleting a skill and leaving its references dangling
- "Fixing" a balanced file's fences (see orch-skill-lifecycle fence rule)
- Creating a new skill because the existing one needed a patch
Bulk Curation Mechanics
skill_managedeleteis a sole op — it refuses to compose with other ops in a singleoperationsarray (rollback safety). Fire eachdeleteas its ownskill_managecall; issue several single-op calls in parallel when pruning a batch, but never put adeletealongside another action.- Writing redirect bodies over many existing
SKILL.mdfiles hits thewrite_fileread-before-write guard: it refuses to overwrite a file whose current content you have not fully read this task, and aread_file(limit=N)counts as a "partial view" that still blocks. For bulk redirects, delegate the mechanical overwrite to a subagent (it reads-then-writes cleanly), or read each file fully (nolimit) first, orpatchjust the frontmatter lines instead of overwriting the whole file.
04 同仓库更多 Skills
macbook-linux-maintenance
Legacy MacBook Linux fixes: GPU wedge, reboot hang, thermal.
governance-regression-triage
Triage a host's governance issues: what changed.
enforcement-immutability
Use when enforcement files lose their immutable flag.
steadfaste-fleet-repo-deploy
Use when committing to the steadfaste-fleet repo.
steadfaste-fleet-maintenance
Maintain an installed Steadfaste Fleet instance — update both the upstream Hermes Agent and the fleet repo layer, merge diverged histories, sync skills safely, and troubleshoot common issues. Covers the dual-update workflow (hermes update + fleet-update.sh), encrypted brain data backup, mycortex import, and recovery techniques.
fleet-preflight
DEPRECATED alias — merged into survey-before-action (2026-08-20). Load survey-before-action instead; its "Repo-Specific Pre-Flight" section covers git search, Hermes boundary, and deployment verification.