AGENT SKILL

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

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) or absorbed_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

  1. Prove duplication first. Load both skills and compare structure AND content — descriptions alone lie. Overlap > 50% → merge; otherwise keep both and note the boundary.

  2. 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.

  3. 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 its description, 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. An aliases: [<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's Skills loadable check 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 whatever python3 is 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 bare Skills loadable ✅: it is a weaker result, not a clean one. Repair the interpreter (fix-fleet-venv.py) and re-run, or invoke the doctor under FLEET_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.

  4. 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 reports Stale skills: orphaned and one deploy can remove it. Import it into the repo or delete it deliberately; never leave it half-owned, and same for a references/ 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) whose SKILL.md has 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.

  5. Verify after every merge/delete. skill_view both skills, re-read the merged SKILL.md for fence balance, run the doctor, regenerate the manifest if skills/ changed.

  6. The REPO is the source of truth — a curatorial edit made on the DEPLOYED copy is STRANDED, not shipped. skill_manage writes the DEPLOYED copy (~/.hermes/skills/<...>), while the fleet receives only steadfaste-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 with diff — 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; regenerates docs/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 just SKILL.md, so a drifted references/ 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 +4 misaligns the comparison — strip the header LINES and diff what remains. Copy the canonical content in, re-run the parity check to PASS, 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 through difflib.SequenceMatcher and collect the non-equal opcodes — 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 say stranded: 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 drift line 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, marked dropped-from-repo or never-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 tracked docs/evidence/skill-drift-parity.txt regenerated 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=A for py|ts|tsx|js|jsx|mjs|cjs|go|rs|… and has no bypass flag, and a skills/<name>/scripts/<file>.py is 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.py is that guard: one discovery traversal over skills/** that compiles .py and 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_info was 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.

  7. A same-name collision from a local-* skill is the OVERRIDE WORKING — do not "fix" it. A host-local local-<x> skill deliberately keeps the fleet skill's name: <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's name: to match its directory makes BOTH load and the override silently stops working. fleet-update.sh's stale pass preserves every local-* directory for the same reason. A local-* 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 no name: 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 a local-* 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 .md in the tree is a PHANTOM candidate. A DESCRIPTION.md, README.md or similar sitting inside a category directory is enumerated as a skill whose name falls back to the DIRECTORY, so skills/<cat>/DESCRIPTION.md presents 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 .md as this shape rather than as a deliberate override.

  8. 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_skills costs 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 in references/ and templates/, and related_skills read as PARSED YAML — the list may be nested under metadata.hermes or span several lines, so a single inline related_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_by target, 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 — "every related_skills entry 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 -> new creates a duplicate list entry whenever the list already named new, 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.

Manifest Discipline

  • After any skill add/rename/delete: regenerate docs/SKILLS-MANIFEST.md via gen-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_manage delete is a sole op — it refuses to compose with other ops in a single operations array (rollback safety). Fire each delete as its own skill_manage call; issue several single-op calls in parallel when pruning a batch, but never put a delete alongside another action.
  • Writing redirect bodies over many existing SKILL.md files hits the write_file read-before-write guard: it refuses to overwrite a file whose current content you have not fully read this task, and a read_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 (no limit) first, or patch just the frontmatter lines instead of overwriting the whole file.

04 同仓库更多 Skills