agentleFS
Sign inStart free
anthony-chaudharyanthony-chaudhary/fak/.agents/skills/skill-lifecycle/SKILL.md

skill-lifecycle

Skill47 starsChanged 12 days agoApache-2.0View on GitHub

Witnessed lifecycle for the project skill pack — usage-telemetry sidecar, value/idle-driven auto-archive (never delete, restorable), pin-exemption, journaled reversible transitions. Use to record skill usage, review archive verdicts, archive or restore a skill, or pin one exempt. Max action is archive; nothing is ever deleted. Use when this named workflow matches the task.

6 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

4 rules. 0 are common, 0 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 6 edited versions we read keep these.

  • 0

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    All state lives beside the skills, inside the claude lane:

    line 16
  2. Very specific:

    Run status and sweep (dry-run) and show the operator the verdicts.

    line 53
  3. Very specific:

    Only sweep --apply or archive after the operator confirms.

    line 54
  4. Very specific:

    After any transition, show the tail of .lifecycle-journal.jsonl so the operator sees the journaled, reversible record.

    line 56

“Common” is measured: kept by at least 6 in 10 of the 6 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/skill-lifecycle — witnessed skill lifecycle (never delete)

Keeps .claude/skills/ from rotting without ever destroying work: per-skill usage telemetry, auto-archive of stale low-witnessed-value skills, and a journaled, reversible archive/restore path. Hermes-curator parity (#2941), with fak's twist: transitions are driven by witnessed value, not idle time alone.

All state lives beside the skills, inside the claude lane:

PathRole
.claude/skills/.usage.jsontelemetry sidecar (use/view/patch counts, last activity, state, pin, origin)
.claude/skills/.lifecycle-journal.jsonlappend-only archive/restore transition log
.claude/skills/.archive/<name>/where an archived skill lives — moved, never deleted
.claude/skills/.archive/.snapshots/pre-archive tar.gz backups

Hard rules

  • Never delete. Archive is a move; a collision is a structured refusal.
  • Pinned is exempt — sidecar pinned: true or pin: true in SKILL.md front-matter blocks both auto- and manual archive.
  • Bundled/core skills are never auto-archived. Origin comes from the sidecar, else git (tracked SKILL.md = bundled); unwitnessable = bundled.
  • Value guards idle. Auto-archive needs idle > --idle-days and witnessed value (use_count + patch_count) < --min-value. An emergency-only skill with proven uses stays live.

Commands

python .claude/skills/skill-lifecycle/skill_lifecycle.py record <skill> [--kind use|view|patch]
python .claude/skills/skill-lifecycle/skill_lifecycle.py status
python .claude/skills/skill-lifecycle/skill_lifecycle.py sweep [--idle-days 30] [--min-value 1] [--apply]
python .claude/skills/skill-lifecycle/skill_lifecycle.py archive <skill> --reason "..."
python .claude/skills/skill-lifecycle/skill_lifecycle.py restore <skill>
python .claude/skills/skill-lifecycle/skill_lifecycle.py pin <skill> | unpin <skill>

sweep is dry-run by default and prints one verdict per live skill with the reason; --apply executes only the archive verdicts (snapshot → move → sidecar state → journal entry, in that order).

When invoked as a skill

  1. Run status and sweep (dry-run) and show the operator the verdicts.
  2. Only sweep --apply or archive after the operator confirms; restore is always safe to run on request.
  3. After any transition, show the tail of .lifecycle-journal.jsonl so the operator sees the journaled, reversible record.

Witness

python .claude/skills/skill-lifecycle/skill_lifecycle_test.py — 12 tests, including the acceptance witness: an idle unpinned agent skill is archived (bytes preserved, snapshot taken, journaled) while a pinned one is untouched, and restore reverses the move exactly.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.

Check your setup, free