Skip to content

ccoalm/ccl-skills / skills/skill-extraction-workflow

skill-extraction-workflow

Flagged

复盘 / 沉淀 / 总结经验 / 补进技能 / 技能缺陷 / 流程优化 / would other teammates hit this / will we forget next time / teamwide recurrence / extract skill / post-mortem / 深度 review·审计技能仓库 / 对标外部技能包找 gap(benchmark superpowers·gstack 等) / 核查全局安装点(~/.config/opencode 等)旧快照是否遮蔽本仓技能 / 本仓(ccl-skills 等共享技能仓)OpenCode 项目配置·命令治理 → turn reusable lessons into durable CCL skills.

FileKindSize
SKILL.mdskill md111.0 KB
agents/openai.yamlconfig257 B
references/analysis-parse-fix-test-challenge-replay.mdmarkdown1.5 KB
references/attention-budget-ratchet.mdmarkdown13.7 KB
references/attribution-verification.mdmarkdown4.4 KB
references/bootstrap-slim-c3-obligation-table.mdmarkdown8.0 KB
references/correction-routing-map.mdmarkdown3.7 KB
references/coverage-exhaustion-traps.mdmarkdown19.6 KB
references/description-authoring.mdmarkdown21.1 KB
references/dual-track-review-gate.mdmarkdown110.6 KB
references/eval-routing.mdmarkdown22.2 KB
references/evidence-card-template.mdmarkdown3.2 KB
references/example-domain-preselect.mdmarkdown4.6 KB
references/external-practice-controls.mdmarkdown45.5 KB
references/extraction-lifecycle-handoff.mdmarkdown6.9 KB
references/extraction-quickstart.mdmarkdown20.2 KB
references/firing-point-placement.mdmarkdown21.3 KB
references/harness-patterns-and-eval.mdmarkdown42.6 KB
references/incident-postmortem-extraction.mdmarkdown28.8 KB
references/l0-l1-l2-routing.mdmarkdown10.3 KB
references/online-skill-review.mdmarkdown6.7 KB
references/parallel-stack-references-pattern.mdmarkdown35.9 KB
references/r0-leakage-audit.mdmarkdown19.9 KB
references/recurring-anti-patterns-checklist.mdmarkdown34.4 KB
references/resume-paused-delivery.mdmarkdown3.0 KB
references/review-feedback-mining.mdmarkdown5.7 KB
references/review-finding-standards.mdmarkdown7.3 KB
references/review-rubric.mdmarkdown3.1 KB
references/rule-consolidation.mdmarkdown38.2 KB
references/skill-listing-budget.mdmarkdown1.7 KB
references/source-register.mdmarkdown1.0 MB
references/source-to-skill-extraction.mdmarkdown109.3 KB
references/two-source-extraction-pattern.mdmarkdown19.4 KB
references/uiux-judgment-extraction.mdmarkdown19.1 KB
references/uiux-routing-map.mdmarkdown5.8 KB
references/validation-and-landing.mdmarkdown46.9 KB
scripts/AGENTS.mdmarkdown635 B
scripts/check-ccl-skills.shexecutablescript100.7 KB
scripts/check-contract-anchors.shexecutablescript5.6 KB
scripts/check-evidence-card-leak.shexecutablescript26.1 KB
scripts/check-mr-target-freshness.shexecutablescript9.4 KB
scripts/check-size-budget.shexecutablescript36.0 KB
scripts/check-sync-pointers.shexecutablescript22.6 KB
scripts/check_review_evidence_present.pyexecutablescript4.6 KB
scripts/contract-anchors.tsvother3.8 KB
scripts/entrypoint_form_census.pyexecutablescript7.1 KB
scripts/eval-golden-trace.rbexecutablescript10.0 KB
scripts/eval-health.rbexecutablescript14.6 KB
scripts/eval-routing-bank.rbexecutablescript30.4 KB
scripts/eval-routing.rbexecutablescript9.2 KB
scripts/extraction_review_gate.shexecutablescript1.8 KB
scripts/gate_receipt.pyexecutablescript24.7 KB
scripts/generic-r0-leak-scan.shexecutablescript12.4 KB
scripts/governing-chain-diff.pyexecutablescript12.8 KB
scripts/impact-chain-gate.rbexecutablescript124.4 KB
scripts/obligation-ledger.pyscript107.0 KB
scripts/reference-access-census.shexecutablescript8.3 KB
scripts/register-firing-path-resolution.rbexecutablescript48.4 KB
scripts/shared_git_surface_gate.pyexecutablescript38.0 KB
scripts/skill-behavior-eval.pyexecutablescript39.3 KB
scripts/skill-paired-eval.pyexecutablescript76.9 KB
scripts/source-register-lifecycle.rbscript1.5 KB
scripts/source-register-pending-status.rbscript2.0 KB
scripts/test_ai_coding_implementation_gates.shexecutablescript85.2 KB
scripts/test_antipattern_grep_panel.shexecutablescript3.2 KB
scripts/test_body_compliance_grading.shexecutablescript21.0 KB
scripts/test_check_ccl_impact_chain_refscripts.shexecutablescript145.1 KB
scripts/test_check_ccl_r0_status.shexecutablescript4.2 KB
scripts/test_check_ccl_register_pending_exclusion.shexecutablescript7.4 KB
scripts/test_check_ccl_regressions.shexecutablescript14.3 KB
scripts/test_check_ccl_route_drift.shexecutablescript22.6 KB
scripts/test_check_ccl_size_budget.shexecutablescript59.5 KB
scripts/test_check_ccl_skill_catalog.shexecutablescript23.3 KB
scripts/test_check_ccl_source_register_lifecycle.shexecutablescript6.1 KB
scripts/test_check_contract_anchors.shexecutablescript7.4 KB
scripts/test_check_mr_target_freshness.shexecutablescript12.8 KB
scripts/test_check_review_evidence_present.shexecutablescript4.3 KB
scripts/test_check_sync_pointers.shexecutablescript32.5 KB
scripts/test_ci_checkout_ref_binding.shexecutablescript8.2 KB
scripts/test_controlled_escalation_pins.shexecutablescript7.7 KB
scripts/test_entrypoint_domain_scan_terms.shexecutablescript8.8 KB
scripts/test_entrypoint_form_census.shexecutablescript6.3 KB
scripts/test_eval_routing_bank_grader_diagnostics.shexecutablescript20.6 KB
scripts/test_eval_routing_bank_resolution.shexecutablescript15.3 KB
scripts/test_eval_routing_bank_surface_binding.shexecutablescript6.9 KB
scripts/test_eval_routing_prose_target.shexecutablescript3.7 KB
scripts/test_eval_runtime.pyexecutablescript43.3 KB
scripts/test_extraction_review_gate.shexecutablescript15.2 KB
scripts/test_frozen_case_sanctity.shexecutablescript6.9 KB
scripts/test_frozen_case_sanctity_selfproof.shexecutablescript4.6 KB
scripts/test_gate_receipt.shexecutablescript17.7 KB
scripts/test_generic_r0_leak_scan.shexecutablescript6.4 KB
scripts/test_git_identity_predicate_gate.shscript13.8 KB
scripts/test_governing_chain_diff.shexecutablescript15.1 KB
scripts/test_impact_chain_gate_dateless_host.shexecutablescript6.8 KB
scripts/test_impact_chain_gate_verdict_differential.shexecutablescript20.8 KB
scripts/test_impact_chain_round_attribution.shexecutablescript32.5 KB
scripts/test_impact_chain_self_adjudication.shexecutablescript31.4 KB
scripts/test_impact_chain_source_refuted.shexecutablescript14.7 KB
scripts/test_liveness_predicate_gate.shexecutablescript14.5 KB
scripts/test_locale_independent_gates.shexecutablescript13.0 KB
scripts/test_obligation_ledger.shexecutablescript94.9 KB
scripts/test_obligation_ledger_repo_audit.shexecutablescript2.7 KB
scripts/test_pinned_phrase_mutation_walk.shexecutablescript6.5 KB
scripts/test_reference_access_census.shexecutablescript17.3 KB
scripts/test_register_firing_path_resolution.shexecutablescript41.0 KB
scripts/test_register_firing_path_wiring.shexecutablescript29.9 KB
scripts/test_regression_runner_lanes.shexecutablescript4.5 KB
scripts/test_regression_runner_registration.shexecutablescript1.5 KB
scripts/test_routing_bank_integrity.shexecutablescript15.5 KB
scripts/test_routing_pointer_integrity.shexecutablescript18.9 KB
scripts/test_shared_git_surface_gate.shexecutablescript76.8 KB
scripts/test_skill_paired_eval.pyscript60.0 KB
scripts/test_teardown_guard_pins.shexecutablescript17.0 KB
scripts/test_uiux_delivery_contract.shexecutablescript118.6 KB
scripts/test_uiux_loading_budget.shexecutablescript15.4 KB
scripts/test_validate_skill_credential_cwd.shexecutablescript2.6 KB
scripts/test_validate_skill_cross_refs.shexecutablescript4.8 KB
scripts/test_validate_skill_root_depth.shexecutablescript2.5 KB
scripts/validate-skill.shexecutablescript10.5 KB

references/attention-budget-ratchet.md

View on GitHub
# Attention-budget ratchet — design invariants for size/budget gates

An attention-budget gate limits how much prose an agent must hold to use a surface: the entrypoint body-word/byte gate, the every-session-injection byte gate, the `description` 800-char cap, and the reference-file line gate (all enforced by `scripts/check-size-budget.sh` or the canonical validator). This file owns the design invariants those gates share and the write-side norms for reference files. Companions: `rule-consolidation.md` owns the prose doctrine (merge-into-canonical, why rule sets must not grow monotonically); `skill-listing-budget.md` owns the host's listing-budget mechanism; `description-authoring.md` owns the description surface.

## The five ratchet invariants

Any NEW budget/size gate, and any modification to an existing one, is checked against all five before landing (this is the budget-gate instantiation of the design-time operability check in `dual-track-review-gate.md` — run that check's four legs too). A gate missing one of these fails in a predictable way, named per item:

1. **Stable proxy estimator** — the metric is deterministic and environment-independent: Unicode letter/number word runs with Han counted per ideograph, raw byte size, or physical line count. Never a model/tokenizer-dependent estimate: two environments disagreeing on the measure turns the gate into noise, and a changed estimator silently invalidates every recorded allowance. Deterministic also means encoding-normalized before measuring — a line count taken over raw bytes reads a CR-delimited file as one line, so line endings are folded to LF first.
2. **Anti-false-green sentinel** — a run that could not evaluate says so: base-unresolvable prints an `*_unevaluated` token (never the ok token), probe failures fail closed as partials, and on any block the last token is the failure marker. The ok token must be unearnable by losing the base; a consumer grepping for ok must never read an un-run gate as a pass.
3. **Zero tolerance for new debt** — a NEW surface over budget blocks outright. There is no exempt marker, no waiver flag, and no way for a candidate to nominate its own baseline; structural exclusions live in the gate, owned by the gate.
4. **Legacy may only shrink** — an existing over-budget surface is frozen at its base measure: level or shrinking lands, any growth blocks. Rename credit is path-paired and non-growing (move plus growth blocks as growth). This is what makes a uniform cap deployable over a corpus that already exceeds it, without a rewrite round and without rewarding a rush to pre-shrink.
5. **A missing baseline is never a pass** — the comparison base comes from revision history (`CCL_SKILL_BASE_REF`, upstream, or merge-base), so there is no stored manifest to go stale; when no base resolves, the verdict is unevaluated (invariant 2), and reddening that state is the caller's pipeline decision (CI always exports the base ref).

Two cross-cutting corollaries:

- Average headroom must never fund a single over-budget surface: the ratchet judges each file alone, and corpus-level counters stay visibility-only.
- Debt counters and advisory bands are never a clean-landing waiver nor authorization to keep growing a surface; only the delta verdict blocks.

## Reference-file write-side norms

The read side already defends against oversized files (chunked reads under ~200 lines, references one level deep). These norms are the write side, enforced as a delta ratchet over `skills/*/references/**/*.md`:

- A NEW reference file over 500 physical lines must not land — split it by subtopic before landing (the gate blocks new-or-crossing files; 500 exactly passes).
- An existing over-limit reference is frozen per invariant 4: shrink or stay level; growth blocks. Additions to a frozen reference are funded by consolidating existing text in the same file.
- Append-only ledgers are structurally excluded: `references/source-register.md` grows by contract (append-only, supersede-by-pointer, rows never edited), so a line cap would block the ledger discipline itself; the gate skips it and prints a visibility token when it is over the figure. Residual risk, accepted under the same trusted-contributor model as the entrypoint gate: a prose file named `source-register.md` would dodge the cap — review owns that shape.
- A new reference over 100 lines must be structured with `##` sections so chunked reads and greps can navigate it; a heading-less long file draws an advisory token (never a block). A table-of-contents list is optional — section structure is the invariant, not a TOC block.
- **Funding an addition by trimming prose means editing text that may be pinned — resolve the pins before rewriting, not after.** The ratchet's per-file freeze makes every addition to a legacy surface a rewrite of something else in the same file, and load-bearing sentences are pinned by literal from places that keep multiplying: `../../skill-extraction-workflow/scripts/contract-anchors.tsv`, the always-on pairs registered in `scripts/check-sync-pointers.sh`, assertions in owner and hook suites (some through helpers such as `assert_contains`, so a search for one assertion idiom misses them), and `file:<path>#<anchor>` firing paths of `source-register.md` rows, which `scripts/register-firing-path-resolution.rb` resolves against the tree. Because the classes grow, search by path rather than by class: you must search every non-Markdown file in the repository for the path you are about to trim or move text out of (`git grep -n -F '<path>' -- ':!*.md' ':!specs/'` lists the registries, gates and suites that name it; round evidence under `specs/` records history and pins nothing) and list the ledger anchors with `grep -o 'file:<path>#[^;|]*' skills/skill-extraction-workflow/references/source-register.md`; after the edit, run `bash skills/skill-extraction-workflow/scripts/check-ccl-skills.sh .`, which resolves the contract anchors, the sync registry and every ledger anchor, plus the suites the path search named. A funded trim that silently retired two pinned wait-contract obligations was reported by the slow lane only, long after the edit, and a relocation whose pin read covered only two of these sources moved a ledger-anchored rule out of its entrypoint. A pinned sentence may be reworded or moved only together with whatever pins it, in the same landing.
- Authoring anti-patterns (verified against the official skill-authoring checklist, see verdicts below): time-sensitive facts outside an explicit old-patterns section; inconsistent terminology for one concept; abstract examples where a concrete input/output pair fits; Windows-style paths; unexplained constants; scripts that defer error handling to the model instead of solving it.

## Retirement and relocation signal (usage census)

The ratchet only stops growth; it never says *what* to retire or relocate, and "not pulling its weight" is an author's opinion until something is measured. Three independent lines converge on the same instrument: context-evolution methods keep per-bullet usage counters (helpful/harmful marks) and prune or merge on them rather than on a single monolithic rewrite that collapses detail; trajectory-distillation work places broadly applicable procedure in the root document and *lower-frequency* detail in auxiliary files, and finds joint consolidation over many traces stronger than order-dependent one-lesson-at-a-time edits; and the official skill-authoring guidance tells authors to watch how the agent navigates a skill — a bundled file the agent never accesses is unnecessary or poorly signaled, one it reads on every run belongs in the entrypoint. The repo instantiation:

- `scripts/reference-access-census.sh [--skill <name>] [--days <n>]` reads the host's own agent transcripts (Claude Code and Codex session logs; both consume this tree) and prints, per `SKILL.md`/reference file, how many sessions in the window mentioned it and when it was last touched (the last-touched column must be the newest touching transcript's date, never the oldest or an unparsed value). Counts only — no transcript text, prompts, absolute log paths, or session ids — so the output is safe for a private charter; it is still per-host data and never lands in the shared tree.
- **Placement by firing frequency and firing time, not only by kind.** The entrypoint's content-placement rule sorts by kind (trigger / routing / core workflow / non-negotiables stay; detail moves). Add the frequency axis: a rule that fires on a narrow source class or correction type (one client surface, one correction shape, one artifact kind) is *low-frequency detail* even when it is non-negotiable, and must live verbatim in the reference the entrypoint already points at, with a one-bullet summary that keeps the load-bearing obligations inline (`rule-consolidation.md` condensing rule). Ledger `file:` anchors and script pins name a path, so a pinned phrase stays where it is — enumerate them before choosing what moves. The time axis works the same way: a section that applies only at a later point of the same task (push and merge, post-merge teardown) is dead weight at activation and sits mid-context by the time it applies, so move it verbatim to a reference and name that reference where the later point is reached — a firing-point table in the entrypoint and the hook that fires there. Moving a section also breaks every pointer that names it by its old location, such as `SKILL.md「X」` or a link to the entrypoint followed by the section title; no gate resolves those, so before landing you must search the Markdown for the name of each moved section, outside `specs/`, and retarget every hit. Exact command conventions and destructive-operation guards that must be applied verbatim stay inline. A hook or always-on text injected at a firing point is what drives the action at that moment, so it must name the canonical section it summarizes, and what it restates must not read as complete when it is not — a digest that calls one exception the only one, or a command list that skips a mandatory pre-step, out-votes the canonical rule loaded earlier; pin the injected guards and the pointer target in the hook's own suite.
- **Advisory, never a gate** (Goodhart, same as the health roll-up): a count that becomes a target gets gamed by mentioning files. A zero-session reference is a relocation/merge *candidate* that still owes the zero-loss obligation map; a high-share reference is a promotion candidate, not an automatic move. Pair the census with the closeout cost row in `extraction-quickstart.md` §4 so that a round records what it cost and what it retired, and the next round can tell whether the corpus is shrinking toward the cap or only holding level.

- **A mention count is not an open count — classify HOW the file is reached before relocating on a census figure.** The census matches the path anywhere in a transcript line, so a file that a gate names in its own output, that an agent appends to, or that a bounded `sed`/`tail`/`grep` touches for one row scores the same as one an agent loads whole. Before a census figure justifies a split, a promotion, or a retirement, the read shape must be counted in the same window — whole-file reads versus bounded reads versus gate echo versus writes — and let the whole-read count, not the mention share, carry the read-side cost argument. Observed: the append-only ledger scored the package's highest mention share, and the read-shape count showed whole-file loads in a small minority of those mentions, with bounded reads and gate echo making up the rest — the split its share seemed to demand would have bought nothing on the read side.
- The census is host-format-bound (it matches fixed-string skill paths inside transcript lines). When no transcript is found, or any transcript is unreadable or vanishes mid-scan, it prints `reference_access_census_unevaluated` and withholds the table (exit 2 on input errors) — never zeros, and never a path: a run that could not evaluate must say so with counts only. An explicitly supplied log root that does not exist must be treated as an input error (an absent default root is normal), overlapping or repeated log roots must count a transcript once, a scan batch that fails without writing stderr must still withhold the table, the scan must not misreport an all-no-match batch under an inherited errexit, and no usage error may echo the caller's argument.

## Official-clause verdicts (provenance)

Registered claims were re-verified against the primary source (Anthropic "Skill authoring best practices", docs.claude.com, read 2026-08-31) before landing; per-clause disposition:

- "Keep SKILL.md body under 500 lines" — present verbatim, but it scopes to SKILL.md, not references. Already covered more strictly here by the 5000-body-word delta ratchet. The 500-LINE reference cap above is a repo-internal norm motivated by the read-side chunking evidence, and is labeled as such — never cite it as an official requirement.
- Table-of-contents mandate for long references — NOT PRESENT in the current official text. The official remedy for `head -100` partial reads is keeping references one level deep (already a Step 6 validation rule). The `##`-section advisory above rests on repo-internal evidence only.
- "Tested with Haiku, Sonnet, and Opus" — present, conditional on the models you plan to ship to. This repo's skills inherit the session model and the eval layer exercises real sessions, so no multi-model matrix is mechanized; the clause fires only if the repo starts shipping model-pinned skills.
- Checklist anti-patterns (time-sensitive info, terminology, concrete examples, forward-slash paths, voodoo constants, scripts-solve-not-defer) — present; landed above as authoring norms. The recurring-anti-patterns grep panel is NOT their landing surface: its admission rule requires a class observed in 2+ skills of this repo.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall