Agent-Skills.md

Agent Skills: Capability Ledger

>-

UncategorizedID: pproenca/dot-claude/capability-ledger

Repository

pproenca/dot-claude
pproenca
1

Install this agent skill to your local

pnpm dlx add-skill https://github.com/pproenca/dot-claude/tree/HEAD/plugins/cairn/skills/capability-ledger

Skill Files

Browse the full folder contents for capability-ledger.

Download Skill

Loading file tree…

plugins/cairn/skills/capability-ledger/SKILL.md

Skill Metadata

Name
capability-ledger
Description
>-

Capability Ledger

The entity layer. The three knowledge skills cache what Claude knows (facts, craft, insight). This tracks what Claude can do — demonstrated capability — and turns it into earned autonomy: the license to attempt a bigger thing, skip a gate, or delegate. It is the difference between a tool that gets faster and an entity that grows.

Why earned, never declared (the safety spine)

A system that expands its own authority is gameable if the evidence is self-assessed. So capability here is computed ONLY from measured outcomes against a floor — the same un-fakeable signal the spike floor gate uses to prevent false victory now doubles as the promotion oracle. Claude cannot write "I am good at this"; the ledger counts only spikes/features that actually landed near their declared floor with a recorded benchmark. Competence is un-fakeable by the agent itself.

The unit: a capability (a demonstrated ability to solve a problem CLASS)

capability-ledger.jsonl, keyed by problem_class (e.g. render-perf-optimization, idempotent-write-boundary, state-machine-design):

  • solves — each: { floor_ratio, domain, date, benchmark_ref }. The evidence.
  • maturity — computed: novice / practiced / proven (never hand-set).
  • playbook — the proven approach (reframings used, floor to beat, boundaries to respect) — what makes the capability DELEGABLE, not just a score.
  • last_demotion — provenance of any instant drop (a near-miss).

The autonomy ladder (mirrors the enforcement ladder, pointed at license)

  • novice (0–2 near-floor solves): full gates. Human confirms spec AND result. The default for every new class.
  • practiced (>=3 near-floor solves in ONE domain): the PLAN gate may auto-pass for this class — proceed without plan confirmation; verify gate + human result review still stand.
  • proven (>=3 near-floor solves across >=2 domains): licensed to DELEGATE this class to a sub-agent under the recorded playbook, and to attempt larger blast radius — because the playbook is demonstrated, not guessed.

No rung auto-passes the spec parse-point (feature-workflow STAGE 0.5): the PLAN gate is planning shape, but intent is not a demonstrated problem class. See references/licensing.md.

"Near-floor" = within the class's agreed ratio of the floor (default <=2x), proven by a recorded benchmark. No benchmark -> not a solve -> no credit.

The asymmetry (the guardrail)

License climbs SLOWLY (multiple demonstrated solves, multiple domains) and falls INSTANTLY (a single near-miss in a class demotes it one rung, recorded in last_demotion). The cost of over-licensing (attempting/delegating beyond real competence) dwarfs the cost of under-licensing (an extra gate), so the ladder is deliberately asymmetric. Demotion is real here — unlike the code maturity ladder, this one must walk back.

Workflow

  • Record a solve (truth-checked): cap_record.py --class <c> --floor-ratio <r> --domain <d> --benchmark <ref> after a spike/feature lands. Refuses a solve with no benchmark ref. Recomputes maturity from the full solve history.
  • Check license (before acting): cap_check.py --class <c> returns the current maturity and what it licenses (gate auto-pass? delegate?). The feature/ spike loops consult this to decide whether the plan gate may auto-pass.
  • Demote (on a near-miss): cap_record.py --class <c> --miss --floor-ratio <r> records a failure and drops the rung immediately.

Composition

  • The spike floor gate is the promotion ORACLE — its measured ratio is the solve evidence. No floor, no capability credit.
  • mental-models supplies the playbook's reframings; a proven capability's playbook references the models that made its solves work.
  • knowledge-ratchet governs nothing here — capability promotion is outcome-driven and automatic, not friction-driven; this is a distinct, stricter ladder.
  • The feature/spike loops READ cap_check.py to decide gate auto-pass; they never WRITE their own license. Read-only consumption keeps the loop from self-licensing.

The one law here

License reflects DEMONSTRATED outcome, never intention or self-report. A capability with no benchmarked near-floor solves is novice no matter how confident the agent feels. Earned, measured, and instantly revocable.

Files

  • references/licensing.md — the maturity computation, near-floor rule, demotion.
  • scripts/store.py — ledger storage port (JSONL).
  • scripts/cap_record.py — record a truth-checked solve or a demoting miss.
  • scripts/cap_check.py — read current maturity + what it licenses.