AGENT SKILL

skill-lifecycle

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.

License 许可
Apache-2.0
最近更新
2026-11-15
Stars
★ 48
Forks
16

01 前言 Front Matter

name
skill-lifecycle
metadata
{ "canonical": "../../../.claude/skills/skill-lifecycle/SKILL.md", "generated-by": "fak project-assets sync" }
description
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.

03 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:

Path Role
.claude/skills/.usage.json telemetry sidecar (use/view/patch counts, last activity, state, pin, origin)
.claude/skills/.lifecycle-journal.jsonl append-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.

04 同仓库更多 Skills