# Stocktake

> Audits all crucible skills for overlap, staleness, broken references, and quality. Quick scan or full evaluation modes.

- **Type:** Skill
- **Install:** `agentstack add skill-raddue-crucible-stocktake`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [raddue](https://agentstack.voostack.com/s/raddue)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [raddue](https://github.com/raddue)
- **Source:** https://github.com/raddue/crucible/tree/main/skills/stocktake

## Install

```sh
agentstack add skill-raddue-crucible-stocktake
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Skill Stocktake

Audits all crucible skills for overlap, staleness, broken references, and quality.

**Announce at start:** "I'm using the stocktake skill to audit skill health."

## When to Activate

- User invokes `/stocktake` or asks to audit skills
- Forge feed-forward nudges when results are 30+ days stale
- After adding, removing, or significantly modifying multiple skills

## Modes

| Mode | Trigger | Duration |
|------|---------|----------|
| Quick scan | `results.json` exists (default) | ~5 min |
| Full stocktake | `results.json` absent, or `/stocktake full` | ~20 min |
| Efficiency report | `/stocktake efficiency` | ~5 min |

**Results cache:** `skills/stocktake/results.json`

## Quick Scan Flow

1. Read `skills/stocktake/results.json`
2. Identify skills that have changed since `evaluated_at` timestamp (compare file mtimes)
3. If no changes: report "No changes since last run." and stop
4. Re-evaluate only changed skills using the same evaluation criteria
5. Carry forward unchanged skills from previous results
6. Output only the diff
7. Save updated results to `skills/stocktake/results.json`

## Full Stocktake Flow

### Phase 1 — Inventory

Enumerate all skill directories under `skills/`. For each:
- Read SKILL.md frontmatter (name, description, origin)
- Collect file mtime
- Note file count and total line count

Present inventory table:

| Skill | Files | Lines | Last Modified | Description |
|-------|-------|-------|---------------|-------------|

**Structural invariants (repo-level).** Run the tracked invariant checker from the repo root and treat a non-zero exit as a stocktake failure to surface:
- `python3 scripts/check_i2_marker.py` — the I2 engine-dispatch marker allowlist: the set of files carrying a column-0 `` `dispatch: delve-engine` `` body line must equal exactly `{delve, temper}` (a stray third dispatcher or a missing one fails). Added #336.
- `python3 scripts/check_qg_stagnation_minor.py` — the Minor-aware stagnation judge contract: asserts `quality-gate/stagnation-judge-prompt.md` carries the Step-3 Mixed-branch Minor-accumulation rule + the `Consecutive recurring-Minor rounds` counter + the `DR-Cause` enum; that `quality-gate/SKILL.md`'s Minor prose is reconciled (the bare "do not count toward stagnation" claim is gone; path-pinned, literal match); and that the convergence-log `dr_cause` value set (`minor-accumulation | structural-saturation | consensus | null`) is documented. Added #260.
- `python3 scripts/check_crossref.py` — the cross-reference invariant: every live `crucible:` in a git-tracked `*.md` resolves to a real `skills//` dir. Plugin-namespaced agent types (the `crucible-*` namespace, e.g. `crucible-red-team`) are resolved against `agents/.md` (so a typo'd agent ref is still caught); documented template placeholders (`skill-name`/`old-name`/`new-name`) are blanket-exempt. `docs/plans/`, `docs/prds/`, and `docs/handoffs/` are gitignored and thus naturally excluded since `git ls-files` lists tracked files only (so new files under those paths are not scanned); tracked surfaces — `skills/**`, top-level `docs/*.md`, `docs/research/`, etc. — ARE scanned. `--selftest` runs the resolution-logic regression cases. Added #365.
- `python3 scripts/catalog.py check` — the generated skill-catalog contract: asserts `docs/skills.md`'s `` rows are in bijection with `skills/*/SKILL.md` frontmatter names (no omission, no bogus entry, no naming mismatch), every on-disk skill is in `CATEGORIES` (and vice-versa, no dangling category), and every registered count token (README, workshop, plugin.json) equals the runtime skill count `n`. Added #364.
- `python3 scripts/check_calibration_dispatch.py` — the calibration-weighted-dispatch wiring invariant: asserts each of the 5 consumers (siege, quality-gate, inquisitor, delve, audit) carries the `` marker + its own `advise ` invocation, and that none inlines the convention's prose body (the net-new no-copy assertion `check_canonical_drift`/`check_crossref` don't cover). `--selftest` runs the marker/invocation/no-copy logic cases. Added #372.
- `python3 scripts/check_model_pins.py` — the model-tier guardrail: no fable-family pin (`fable`/`claude-fable-5`, case-insensitive, across frontmatter `model:` + inline `Task tool`/`Agent tool` forms) on any ``-marked file, AND every file in the security-surface set (`skills/siege/**`, `skills/dependency-audit/**`, `agents/crucible-red-team.md`, plus narrow offensive/CVE name-stems gated match-then-check-for-pin; `audit`/`test-coverage`/`stocktake` carved out) carries the marker (default-deny). Static tracked-`*.md` pins only — `inherit`/session-model roles and untracked consensus config are disclosed residuals (see `skills/shared/model-tier-policy.md`). `--selftest` runs the detection-logic cases. Added #392.

(Other tracked checkers under `scripts/check_*.py` may be run here too as they are brought into alignment.)

### Phase 2 — Quality Evaluation

Dispatch an Opus Explore agent with all skill contents and the evaluation checklist.

Each skill is evaluated against:

- [ ] Content overlap with other skills checked
- [ ] Scope fit — name, trigger, and content aligned
- [ ] Actionability — concrete steps vs vague advice
- [ ] Cross-references — do `crucible:` links resolve to existing skills?
- [ ] Convention drift — does a skill that dispatches subagents carry the `` / `return-convention.md` markers (vs. copying or omitting them)?
- [ ] Eval presence — does the skill have an `evals/` directory, or is one warranted given its surface? (eval-before-publish; flag absence, don't auto-fail — evals are aspirational across the suite)

Each skill gets a verdict:

| Verdict | Meaning |
|---------|---------|
| Keep | Useful and current |
| Improve | Worth keeping, specific improvements needed |
| Retire | Low quality, stale, or cost-asymmetric |
| Merge into [X] | Substantial overlap with another skill; name the merge target |

**Reason quality requirements** — the `reason` field must be self-contained and decision-enabling:
- For **Retire**: state (1) what specific defect was found, (2) what covers the same need instead
- For **Merge**: name the target and describe what content to integrate
- For **Improve**: describe the specific change needed (what section, what action)
- For **Keep**: restate the core evidence for the verdict

### Phase 3 — Summary Table

| Skill | Verdict | Reason |
|-------|---------|--------|

### Phase 4 — Consolidation

1. **Retire / Merge**: present detailed justification per skill before confirming with user
2. **Improve**: present specific improvement suggestions with rationale
3. Save results to `skills/stocktake/results.json`

## Efficiency Report Flow

Triggered by `/stocktake efficiency` or by forge feed-forward when 10+ chronicle signals with efficiency data exist.

### Step 1: Load Chronicle Data

1. Read `~/.claude/projects//memory/chronicle/signals.jsonl`
2. If the file is missing or empty: report "No efficiency data available. Run a pipeline with enriched manifest tracking to begin collecting data." and stop.
3. Filter to signals that have a `metrics.efficiency` sub-object.
4. If fewer than 3 signals have efficiency data: report available data with caveat: "Insufficient data for trend analysis. N signals available, 3+ recommended for meaningful comparison."
5. Report: "N of M total signals include efficiency data." (where M is total signals, N is signals with efficiency).

### Step 2: Per-Skill Summary

Group filtered signals by `skill`. For each skill, compute:
- **Runs**: count of signals
- **Avg Est. Tokens (in+out)**: average of `(est_input_tokens + est_output_tokens)` across runs
- **Avg Duration**: average `duration_m`
- **Avg Dispatches**: average total dispatches (sum of `dispatches_by_tier` values)
- **Rework %**: average `rework_pct` across runs. If `rework_pct` is missing (pre-rework-tracking signal), display "—"
- **Trend**: compare last 3 runs vs prior 3 runs — "improving" (fewer tokens), "stable" (within 10%), or "increasing" (more tokens). "insufficient data" if fewer than 4 runs.

If any skill has average rework >30%, append a note: "**[skill]**: rework >30% — consider reviewing dispatch templates or quality-gate prompts for this skill."

Output:

```
## Skill Efficiency Report
**Period:**  to 
**Tracked runs:** N
**Disclaimer:** Estimates based on dispatch file sizes (chars/4). Actual token consumption may vary +/-30%.

### Per-Skill Summary
| Skill | Runs | Avg Est. Tokens (in+out) | Rework % | Avg Duration | Avg Dispatches | Trend |
|-------|------|--------------------------|----------|--------------|----------------|-------|
```

### Step 3: Dispatch Breakdown

For each skill, compute dispatch tier distribution and categorize dispatches as review vs. implementation:
- **Opus/Sonnet/Haiku %**: from `dispatches_by_tier` averaged across runs
- **Review %**: dispatches with role containing "reviewer", "red-team", "quality-gate", "adversarial" as a percentage of total
- **Impl %**: remaining dispatches as a percentage of total

Note: Review vs. implementation breakdown requires reading manifest entries (role field). If manifests are not available (only chronicle signals), report "N/A" for these columns.

Output:

```
### Dispatch Breakdown
| Skill | Opus % | Sonnet % | Haiku % | Review % | Impl % |
|-------|--------|----------|---------|----------|--------|
```

### Step 4: Structural Efficiency

For each skill, compute:
- **Avg Input/Dispatch**: average `total_input_chars / total dispatches` — measures context per subagent
- **Context Distribution**: qualitative assessment — "focused" (15000)
- **Quality Overhead %**: `review dispatches / total dispatches * 100` — what fraction of work is quality assurance (requires manifest data; "N/A" if unavailable)

Output:

```
### Structural Efficiency
| Skill | Avg Input/Dispatch | Context Distribution | Quality Overhead % |
|-------|--------------------|-----------------------|--------------------|
```

### Step 5: Baseline Comparison (Structural)

For each skill with sufficient data (3+ runs):
- **Avg Total Context**: average `(total_input_chars + total_output_chars)` per run — total context the pipeline touched
- **Avg Input/Dispatch**: average `total_input_chars / total dispatches` per run — how much context each subagent receives on average
- **Context Focus Ratio**: `avg input per dispatch / avg total context` — lower values mean each subagent sees a smaller slice of the total, indicating effective context distribution
- **Quality Investment**: `review dispatches / total dispatches` — fraction of dispatches dedicated to quality assurance (requires manifest data; "N/A" if only chronicle signals available)

Output:

```
### Baseline Comparison (Structural)
| Skill | Avg Total Context | Avg Input/Dispatch | Context Focus Ratio | Quality Investment |
|-------|-------------------|--------------------|---------------------|--------------------|

**Interpretation:** Context focus ratio measures how much of the total pipeline context each
subagent receives. Lower values mean more focused dispatches. Quality investment shows the
fraction of dispatches dedicated to review, red-team, and quality gates. These are structural
comparisons, not cost savings claims — they measure how the skill distributes work, not what
a monolithic alternative would cost.
```

### Step 6: Cache Results

Save efficiency report data to `skills/stocktake/results.json` under a new `efficiency` key (separate from the skill verdict cache):

```json
{
  "efficiency": {
    "computed_at": "2026-04-07T10:00:00Z",
    "signals_with_efficiency": 15,
    "total_signals": 42,
    "per_skill": {
      "build": { "runs": 8, "avg_est_tokens": 52600, "avg_duration_m": 45, "trend": "stable" },
      "debugging": { "runs": 5, "avg_est_tokens": 25000, "avg_duration_m": 22, "trend": "improving" }
    }
  }
}
```

## Results File Schema

`skills/stocktake/results.json`:

```json
{
  "evaluated_at": "2026-03-07T10:00:00Z",
  "mode": "full",
  "skills": {
    "skill-name": {
      "path": "skills/skill-name/SKILL.md",
      "verdict": "Keep",
      "reason": "Concrete, actionable, unique value for X workflow",
      "mtime": "2026-01-15T08:30:00Z"
    }
  }
}
```

## Safety

- **Never auto-deletes or auto-modifies skills**
- Always presents findings and waits for explicit user confirmation
- Archive/delete operations always require user approval

## Integration

- **crucible:forge** — Feed-forward checks stocktake results timestamp; nudges when 30+ days stale
- Evaluation is blind: same checklist applies regardless of skill origin

## Red Flags

- Deleting or modifying skills without user confirmation
- Treating the checklist as a numeric score rather than holistic judgment
- Writing vague verdicts ("unchanged", "overlaps") instead of decision-enabling reasons

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [raddue](https://github.com/raddue)
- **Source:** [raddue/crucible](https://github.com/raddue/crucible)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-raddue-crucible-stocktake
- Seller: https://agentstack.voostack.com/s/raddue
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.