skill-library-curation
Skill3 starsChanged 53 days agoMITView on GitHub
Review a reusable skill library: inventory, overlap groups, pruning and consolidation proposals, installer provenance, and upstream freshness. Use when asked to audit, prune, or recommend skills, or to answer where an installed skill came from and whether it is current. Not for creating or editing a skill, and not for porting one into a shared repo — review and execution are separate modes, and execution needs its own confirmed scope.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- ashleysbrain/skillstheir own version, first seen Nov 8, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- ashleysbrain/skills★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository59 other files it gives its agents.
- AGENTS.mdAGENTS.md
- agent-harness-settings-paritySkill
- agent-operating-contract-evolutionSkill
- ai-coding-agent-delegationSkill
- arch-improvement-planSkill
- contract-bound-deliverablesSkill
- cross-agent-repair-routingSkill
- define-goalSkill
- delegated-work-acceptanceSkill
- design-an-interfaceSkill
- design-mdSkill
- discord-rich-messageSkill
- dotnet-repo-workflowSkill
- evidence-backed-analytical-writingSkill
- evidence-boundary-disciplineSkill
- find-nearbySkill
- gddSkill
- generated-runtime-repairsSkill
- ghc-searchSkill
- git-auto-sync-pipelinesSkill
- github-code-reviewSkill
- github-repo-managementSkill
- grounded-citationsSkill
- harness-engineeringSkill
- hermes-context-file-loadingSkill
- hermes-modelsSkill
- hermes-updatesSkill
- hoa-introspect-distillSkill
- hoa-introspectSkill
- hoa-skill-reviewSkill
- hoa-skill-workSkill
- html-artifactSkill
- jupyter-live-kernelSkill
- kanban-workflowsSkill
- m365-copilot-cdpSkill
- measurement-campaign-evidenceSkill
- microsoft-officeSkill
- notes-to-prdSkill
- ocr-and-documentsSkill
- official-document-verificationSkill
- omp-headless-orchestrationSkill
- ops-claim-verificationSkill
- package-release-verificationSkill
- plan-to-issuesSkill
- project-phase-closeoutSkill
- report-claim-auditSkill
- research-stream-consolidationSkill
- review-revision-candidatesSkill
- rss-feedsSkill
- skill-porting-and-publishingSkill
- spec-convergenceSkill
- structural-validity-gatesSkill
- subagent-driven-developmentSkill
- systematic-debuggingSkill
- teams-cdpSkill
- tmux-agent-controlSkill
- whisperSkill
- writing-plansSkill
- writingSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 5 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 32
Use this for library review, pruning/overlap/consolidation proposals, or usage-based skill discovery.
- Distinctive: line 42
Keep skills class-level: prefer one reusable workflow skill with a small topical reference set over many narrow incident skills or one …
- Distinctive: line 52
When the owner says a working skill "should be general, let's improve it", the defect is rarely missing prose — it is the same protocol …
- Very specific: line 92
Do not trust SKILL.md mtimes after editing anything in the tree — your own sed/patch refreshes them.
- Very specific: line 139
Run scripts/upstream-freshness-check.py (reads the optional disabled list + the installer lock, threads the fetches, prints only DIFF/ERR …
- Distinctive: line 148
Collect usage evidence: Read the available usage metadata and record use count, last-used time, and whether the evidence is recent, …
- Distinctive: line 157
Stop at the decision gate: Do not delete files, disable skills, rewrite routing, or merge content during the review.
- Distinctive: line 166
Verify the exact post-change state: loader list, disabled list, active references to removed names, skill loading, and config validity.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Skill Library Curation
Configuration
| Variable | Resolves | Default |
SKILLS_HUB | shared skill store (hub installs + .skill-lock.json) | ~/.agents |
SKILLS_ROOT | directory the runtime loads skills from | <hub>/skills |
SKILL_RUNTIME_CONFIG | operator config file used for the skills.disabled label | ${XDG_CONFIG_HOME:-~/.config}/agent/config.yaml |
Resolution order and the config-file path are defined once in
skill-porting-and-publishing § Configuration.
Nothing above has a machine-specific default: point SKILLS_HUB at the store and the rest follows.
Use this for library review, pruning/overlap/consolidation proposals, or usage-based skill discovery.
Review and recommendation are distinct modes; execution requires its own explicitly confirmed scope.
For recurring discovery, follow references/usage-based-recommendations.md, not a whole-library sweep.
Moving a skill out of the runtime into a shared/public repo is a different job — porting and
publishing (de-coupling axes, generated catalogs, canonical-source swap), not this skill.
Core rules
- Be active: a meaningful library review should produce a reusable inventory, classification, or skill-library improvement; do not turn “no deletion yet” into “no work done.”
- Be conservative: zero usage is evidence, not proof of low value. If the owner's scenario is unclear, classify
needs confirmationand do not guess. - Keep skills class-level: prefer one reusable workflow skill with a small topical reference set over many narrow incident skills or one umbrella with a reference file per session.
- Report overlap explicitly. Do not silently merge or delete a skill because another one looks similar.
- For usage-based discovery, ground recommendations in the owner's actual preceding-week activity, not agent-generated maintenance or cumulative counters. Return at most three concise Simplified Chinese bullet recommendations: actual trigger, practical benefit, next use, installed/enabled/disabled/external status and verified source. Do not auto-install or change state; stay silent without worthwhile evidence and do not repeat a prior recommendation without a new reason.
Auditing one workflow skill for protocol integrity
When the owner says a working skill "should be general, let's improve it", the defect is rarely missing prose — it is the same protocol living in several files and drifting. Probe before writing:
- Inventory the family, not the file.
wc -lthe umbrellaSKILL.mdplus everyreferences/andprofiles/file, then read the headings of the related skills it names. A stage order or gate that appears in three bodies is already a liability; 500-line profile copies of a 180-line protocol mean every future edit must land in two places. - Count copies by distinctive token. Grep a protocol-specific string across the skill tree (a role marker name, the transport wrapper command, the gate script name): one hit per file = one more source of truth. No judgement needed, and it is faster than reading.
- Hunt claims that contradict current defaults. The highest-value defect is a stale transport/command sentence in a reference file that the umbrella already superseded (e.g. a prompt template still telling you to paste into an interactive pane after the default moved to headless). Fix that in place immediately — it is a factual error, not a design choice.
- Diff same-purpose scripts across skills
(
diff <(sed 's/[[:space:]]*$//' a) <(sed 's/[[:space:]]*$//' b)). The weaker twin is dead weight: keep the stronger one and make the other a pointer. - Check coverage against reality, not against intent. For each repo/project the owner actually
works in (
ls -d <workspace>/*/, look for the contract dir such asdocs/goals/), ask whether a profile exists. An active repo with no profile is a bigger fluency gap than any wording fix. - Check for durable state and telemetry. Is there a per-increment state file (stage, base sha, next action) and a ledger with durations/rounds? If not, interruption recovery is the real bottleneck and more prose cannot fix it.
Deliver: what exists (with counts), where the protocol is duplicated, which claims are already wrong, then 2–3 options sized by effort. Do not rewrite a methodology skill the owner depends on before they pick an option — the audit is the deliverable.
Upstream-maintenance retirement rule
Standing owner policy (pre-authorized deletion class): delete imported skills whose upstream author has been inactive longer than 3 months. The author's activity is the criterion, not local usage — a zero-use skill with an active upstream author stays; an unused skill with an abandoned upstream is a delete candidate without further conservative gating.
Sweep procedure:
- Build the provenance map before judging activity: hub installs from the runtime's hub lock file (
source), shared-store installs from the shared installer lock (skills.<name>.source/sourceUrl), the rest from repo links insideSKILL.md. Locally-authored skills with no upstream are owned by the owner — judge those by usage count and edit staleness instead, and treat them asneeds confirmationunless the owner stated a local-staleness rule.
Owner's stated local-staleness rule: a skill 180 days unloaded or never loaded is a delete candidate — but keep it when a plausible near-future use exists (judge from the owner's projects and current direction). Always produce the deletion list and get owner confirmation before deleting; never prune this class autonomously.
2. Probe each upstream repo once: curl -s https://api.github.com/repos/<owner>/<repo> → read pushed_at and archived. An archived repo or a pushed_at older than the cutoff is the delete signal.
3. Cross-reference before deleting: scheduled-job prompts, live docs (identity file, operating contract, fact store, shared rails, team docs), and other skills' bodies. A mention inside another skill as a historical case study is not a live dependency — update the example, proceed with the deletion.
4. Back up the confirmed set into one tarball before deleting. Category-level profile symlinks propagate the removal automatically, so verify with a profile-side skill count, not the category-entry count the reconciler reports.
5. Do not trust SKILL.md mtimes after editing anything in the tree — your own sed/patch refreshes them. Use the runtime's usage ledger plus directory mtimes for staleness evidence.
Installer provenance and warning triage
Answer "where did this skill come from", "is it actually installed", "why is the installer warning" from recorded state and source, never from guessing:
- Provenance is a lookup. Shared-store installs (
${SKILLS_HUB:-~/.agents}/skills/<name>) record their origin in${SKILLS_HUB:-~/.agents}/.skill-lock.jsonunderskills.<name>(source,sourceType,sourceUrl,skillPath,skillFolderHash,installedAt,updatedAt; the file also holdsdismissedandlastSelectedAgents). Hub installs use the runtime's own hub lock file. Per-source counts from this file answer "how many skills came from repo X" exactly. - Attribute a repo-relative path without cloning.
gh search code "<path>" --limit 10names the owning repo;gh api repos/<owner>/<repo>/contents/<path> --jq '.content' | base64 -dreads a single file. Preferghover browser/HTTP fetching for anything on GitHub — it is authenticated, prints clean JSON, and needs no scraping. - Locate the emitting code before explaining a warning.
grep -rl "<warning text>" <runtime-home> ~/.npmfinds the CLI bundle; read the surrounding function. The warning's own path prefix identifies the phase — a path under the tool'smkdtemp(TMPDIR/<tool>-*)directory means it scanned a throwaway git clone, not an install target. - Scan warnings that point inside
tests//fixtures are noise, but verify it. Installers walk everySKILL.mdin the cloned tree and validate frontmatter (name+description), so upstream test fixtures trip the gate. Confirm with two reads: the fixture file carries onlyname:(deliberately incomplete), and the warned names are absent from the lock file (nothing was installed, nothing was silently dropped). - Report mechanism + impact + provenance. "Cosmetic, here is why, zero entries affected, here is the file that proves it" — never a bare "it's fine". A genuine defect found this way belongs upstream (e.g. the scanner should skip test trees); do not patch the local install to silence someone else's tool.
This applies to the skills CLI install model and its lock layout in detail — see
references/skills-cli-installs.md.
Upstream freshness — verify by HEAD diff, not the lock timestamp
"Are all my skills up to date?" is a different question from "is the upstream author active?" (the retirement rule above). Answer it by content, not timestamps:
- An old
updatedAtin the installer lock is NOT staleness. The installer only rewrites files whose content changed, so an unchanged skill keeps its original install timestamp for months. A repopushed_atis also a weak signal — a monorepo push rarely touches your specific skill. - The truth is a byte-for-byte diff of each github-backed skill's local
SKILL.mdagainst upstream HEAD: resolvesourceUrl+skillPathfrom the lock, buildhttps://raw.githubusercontent.com/<owner>/<repo>/HEAD/<skillPath>, and compare with CRLF normalized. (Prefer this overgh api .../contentshere — raw HEAD is one fetch per skill.) - Cover DISABLED skills too — they still sit on disk and can be re-enabled; a stale one is a latent surprise.
- Run
scripts/upstream-freshness-check.py(reads the optional disabled list + the installer lock, threads the fetches, prints only DIFF/ERR rows plus a SAME/DIFF/ERR tally; exits non-zero on any DIFF so it can gate).--enabledlimits the sweep to non-disabled skills;--lock,--skills-root, and--configoverride the XDG-based defaults.
Review procedure
- Define the review scope. Include enabled, disabled, filesystem-only, loader-only, and archived entries. Record the source/path and current runtime status for every entry.
- Establish runtime truth. Query the actual runtime loader/registry, then reconcile it with the filesystem inventory. Report loader-only and filesystem-only mismatches instead of dropping them or trusting a stale snapshot.
- Collect usage evidence. Read the available usage metadata and record use count, last-used time, and whether the evidence is recent, historical, or absent. Never invent frequency from the skill name.
- Read enough content to judge quality. Inspect each skill's description and, for candidates, its
SKILL.md; flag empty/malformed metadata, stale instructions, dangerous permissions, unclear scope, or obsolete dependencies. - Assess every skill on four axes:
- usage frequency: recent, historical, or unobserved;
- overlap: unique, complementary, or a concrete replacement candidate;
- core value: directly supports the owner's main workflows, useful on demand, or non-core;
- quality: clear and maintained, bulky/ambiguous, stale, risky, or malformed.
- Assign exactly one recommendation:
retain,merge,suggest delete, orneeds confirmation. Useneeds confirmationwhenever a personal integration, domain interest, or future workflow cannot be inferred safely. - Produce the recommendation before changing state. For every skill, output its name, recommendation, one-sentence reason, and the four evidence dimensions. Use a CSV/JSON artifact for the full set when chat formatting is constrained; on a channel that renders tables poorly use bullets or labeled rows rather than a raw Markdown table.
- Stop at the decision gate. Do not delete files, disable skills, rewrite routing, or merge content during the review. Wait for an explicit owner confirmation that names the action scope. A vague request to “review” is not deletion approval.
Execution procedure after explicit confirmation
- Freeze the confirmed set; do not expand it from inference.
- Back up every skill directory and affected config before destructive edits. Preserve an audit trail of the selected set and the backup path.
- For a merge, choose one canonical class-level skill, move reusable rules into its
SKILL.md, extend an existing topical reference before creating a new one, and update active routing references precisely. - For deletion, remove only the confirmed skills; leave archived history untouched unless the owner explicitly includes it.
- Reload or rebuild the runtime only after the filesystem/config edit succeeds.
- Verify the exact post-change state: loader list, disabled list, active references to removed names, skill loading, and config validity. Report proof and rollback path.
Pitfalls
- Do not explain a tool warning from its message text alone. Locate the emitting code and the provenance/lock record first; the message often names a temp path or a fixture, and the plausible reading of it is wrong more often than not.
- Do not recurse a grep over the whole runtime tree. A
grep -rnacross the runtime home walks the installer's hub index cache — a single-line, multi-megabyte JSON index — and buries the hits in tens of megabytes of one JSON line. Target the skill directory or excludeindex-cache. - Do not use an old inventory as runtime truth. Skill installs, platform gates, and malformed metadata can make loader and filesystem counts differ; reconcile both before declaring totals.
node_modulesphantom skills. A vendored npm package under a skill'sscripts/node_modules/can ship its ownSKILL.md(e.g.dotenv/skills/dotenvx/SKILL.md). A recursive filesystem scan counts it as a top-level skill, but the runtime loader skipsnode_modules, so it is NOT injected and costs no prompt. Do not add it to the disabled list (creates a phantom entry) or delete it (breaks the vendored dep) — excludenode_modulesfrom the inventory and note it once. Confirm the real injected count from the live assembled prompt, not the filesystem count.- Do not equate “never used” with “useless.” Integrations and specialist skills are often intentionally dormant; keep them in
needs confirmationunless the owner context rules them out. - Do not make a deletion proposal without a replacement or scope reason. A skill can be non-core without being safe to remove; state the replacement, overlap, or explicit irrelevance.
- Do not patch a user-owned, bundled, hub-installed, external, or pinned skill during autonomous curation. Report the protection boundary and recommend adoption or foreground-owner action instead.
- A profile that declares itself authoritative over its umbrella is a drift machine. Text like "where the two differ, this profile wins" puts owner-level protocol in a per-repo file, so the next protocol edit lands in the wrong place and the two silently disagree. Report it as structural; the profile should carry repo deltas only (contract location, gate commands, branch and bot conventions, frozen surfaces, resource limits).
- Do not propose new machinery before checking what the existing failure cost. Stage caps, extra checklists and dispatcher scripts are guesses until a ledger shows which stage burns the rounds; the mechanical part worth building first is the one that runs a gate the agent keeps skipping by hand.
- Do not make a raw Markdown table the only deliverable on a channel that renders tables poorly. Attach a CSV/JSON artifact and provide readable bullet rows.
- Do not let a large inventory hide the decision. Lead with counts and the high-confidence take, then link the complete per-skill evidence.
Completion output
Report:
- total entries and runtime/archived split;
- counts for retain/merge/suggest-delete/needs-confirmation;
- high-confidence recommendations and the main overlap groups;
- at most three genuinely justified new-skill candidates;
- artifact paths for the complete review;
- an explicit statement that no changes were made when still at the review gate.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

