# Pillar #4 — Skills

Progressive-disclosure audit: 79 skills inventoried, L0-L3 rubric, top-20 refactor priority, PoC task-postflight (541→194 LOC). MC #99131 | 2026-05-04

# Audit Summary

# Pillar #4 Skills Audit — Summary

**Source:** `~/system/specs/agentic-os-pillar4-skills-audit-2026-05-04.md` (§1–§3 + Reality Anchor)  
**MC:** [\#99131](https://boards.alai.no/tasks/99131) | [\#99176](https://boards.alai.no/tasks/99176)  
**Date:** 2026-05-05  
**Phase:** DESIGN + PoC (Phase 2)

---

## Executive Summary

This audit covers D2 (Top-20 Refactor Priority Table), D3 (Progressive Disclosure Design Pattern), and D4 PoC analysis for the task-postflight skill refactor.

**Key findings:**

- 79 active skill directories on disk; 94 rows in skill-registry.db (32 phantoms, 17 unregistered)
- Only 15 skills have any log invocations in the 19-day measurement window
- `mehanik` (186 hits) and `update-config` (1 hit) appear in logs but have no disk directory — ghost invocations
- 9 skills with references/ dir; 70 are monolithic (L0/L1)
- 12 TOB skills have nested structure — invisible to Claude Code flat-discovery loader
- Highest-priority refactor target: `task-postflight` (5,367 tokens × 21 measured invocations = priority\_score 82.05)
- **Reality anchor:** At current ALAI scale (Claude Max flat-rate subscription), context-bloat incremental cost is approximately $0-2/month. The value of this audit is context window capacity management, not dollar cost reduction.

---

## Environment Constants

```
WORKING_DIR=/Users/makinja
SKILLS_ROOT=/Users/makinja/.claude/skills
TELEMETRY_LOG=/Users/makinja/system/logs/skill-use.log
REGISTRY_DB=/Users/makinja/system/databases/skill-registry.db
TOKENIZATION_FORMULA=bytes_div_3.7
PRICE_USD_PER_MTOK_INPUT=3.00
SESSIONS_PER_MONTH_BASELINE=600
TELEMETRY_WINDOW_DAYS=19
OUTPUT_DIR=/tmp/pillar4-99131-out/

```

---

## Inventory Summary

<table id="bkmrk-metricvaluesource-ac"><thead><tr><th>Metric</th><th>Value</th><th>Source</th></tr></thead><tbody><tr><td>Active skill dirs on disk</td><td>79</td><td>`ls ~/.claude/skills/ | grep -v _archived | wc -l`</td></tr><tr><td>Archived skills</td><td>32</td><td>`ls ~/.claude/skills/_archived/ | wc -l`</td></tr><tr><td>skill-registry.db rows</td><td>94</td><td>`sqlite3 skill-registry.db 'SELECT COUNT(*) FROM skills;'`</td></tr><tr><td>DB-only phantoms</td><td>32</td><td>comm comparison</td></tr><tr><td>Disk-only unregistered</td><td>17</td><td>comm comparison</td></tr><tr><td>Skills with references/ dir</td><td>9</td><td>find query</td></tr><tr><td>Skills with invocations in window</td><td>15</td><td>log grep</td></tr><tr><td>Measurement window</td><td>19 days</td><td>2026-04-16 to 2026-05-05</td></tr><tr><td>Total invocations in window</td><td>267</td><td>awk filter</td></tr><tr><td>Ghost invocations (mehanik, no disk)</td><td>186</td><td>log grep — mehanik not on disk</td></tr></tbody></table>

---

## Appendix A — Inventory CSV (83 rows)

**Source:** `~/system/specs/agentic-os-pillar4-skills-inventory.csv`

*83 total lines: 3 comments + 1 header + 79 data rows, 19 columns, RFC-4180 compliant*

**Methodology:**

- **Tokenization formula:** `skill_md_tokens_est = skill_md_bytes / 3.7` (GPT-4o empirical average for English markdown, ±15% error)
- **Telemetry window:** 19 days (2026-04-16 to 2026-05-05) — `invocations_30d` is lower bound, not exact 30-day count
- **Sessions per month baseline:** 600
- **Price per Mtok (input):** $3.00

**Key findings from CSV:**

- **32 phantom rows:** Exist in skill-registry.db but no corresponding directory on disk (e.g., `algorithmic-art`, `brand-guidelines`, `sentry-*`, `tob-*` variants)
- **17 unregistered:** Disk skills NOT in skill-registry.db (`ask-board`, `prompt-forge`, `task-postflight`, `lightrag-*`, etc.)
- **Ghost invocations:** `mehanik` (186 hits), `update-config` (1 hit) — no disk directory exists
- **TOB nested structure:** All 12 `tob-*` skills have `README.md + skills/` subdir at root; no `SKILL.md` — invisible to flat-loader

[→ See Top-20 Refactor Priority Table](https://docs.alai.no/books/pillar-4-skills/page/top-20-priority)

---

## Appendix B — Inventory README

**Source:** `~/system/specs/agentic-os-pillar4-skills-inventory.README.md`

### Frequency Sources

Two independent sources per spec §CONSTRAINTS #4:

1. **skill-use.log (PRIMARY)** — `/Users/makinja/system/logs/skill-use.log`
    - 300 total entries
    - 267 entries within 30d window (2026-04-04 to 2026-05-04)
    - Hook fires on `SKILL=<name>` log line
2. **skill-registry.db (SECONDARY)** — `/Users/makinja/system/databases/skill-registry.db`
    - Query: `SELECT name, use_count FROM skills ORDER BY use_count DESC;`
    - 94 rows in registry

### Hook Coverage Gap

- Hook fires only when `tool_name="Skill"` (i.e., the `/command` invocation)
- **Skills invoked by sub-agents as inline tool calls (not via Skill tool) are NOT counted**
- **Skills triggered via `references/` file Read operations are NOT counted**
- `invocations_30d` column = **minimum lower bound**, not exact count

### Monthly Cost Assumptions

```
SESSIONS_PER_MONTH_BASELINE = 600
PRICE_USD_PER_MTOK_INPUT = 3.00

est_monthly_context_tokens = (frontmatter_description_bytes / 3.7) * 600
est_monthly_invocation_tokens = skill_md_tokens_est * invocations_30d
est_monthly_cost_usd = (est_monthly_context_tokens + est_monthly_invocation_tokens) * 3.00 / 1,000,000

```

**Reality anchor:** At current ALAI scale (Claude Max flat-rate subscription), context-bloat incremental cost is approximately $0-2/month. The value of this audit is context window capacity management, not dollar cost reduction.

---

*Cross-links:*

- [Top-20 Refactor Priority Table](https://docs.alai.no/books/pillar-4-skills/page/top-20-priority)
- [Progressive Disclosure Design Pattern](https://docs.alai.no/books/pillar-4-skills/page/design-pattern)
- [PoC: task-postflight Refactor](https://docs.alai.no/books/pillar-4-skills/page/poc-task-postflight)

# Top-20 Priority

# Top-20 Refactor Priority Table

**Source:** `~/system/specs/agentic-os-pillar4-skills-audit-2026-05-04.md` (§4)  
**MC:** [\#99131](https://boards.alai.no/tasks/99131) | [\#99176](https://boards.alai.no/tasks/99176)  
**Date:** 2026-05-05

---

## Methodology

**Priority score formula:**

```
priority_score = log10(skill_md_tokens_est) * (1 + invocations_30d)

```

Bonus weight ×1.5 if `frontmatter_description_bytes > 500`.

**Tie-break rule:** Higher `skill_md_tokens_est` wins.

**Exclusion list:**

- `owner=anthropic` vendor skills (docx, pdf, pptx, xlsx, figma-design) — VENDOR\_REFACTOR\_IMMUNE
- `_archived/` skills
- TOB skills with `skill_md_loc=0` (no SKILL.md at root, tokens\_est=0, score undefined)
- Skills where `invocations_30d=NO_DATA` (none in this dataset — all zero values are grounded in grep)

**Note on invocations\_30d=0 skills:** Ranked separately at bottom of table with priority\_score computed as `log10(skill_md_tokens_est) * 1` (no invocation multiplier). This represents their per-session load cost without usage frequency.

**Note on est\_monthly\_cost:** The columns below show estimated cost per month. These projections assume sessions\_per\_month=600 and invocations\_30d as a proxy for monthly rate. Per-turn savings are the honest metric; monthly projections are estimates only.

---

## Top-20 Table (sorted descending by priority\_score)

<table id="bkmrk-rank-skill_name-loc-"><thead><tr><th>rank</th><th>skill\_name</th><th>LOC</th><th>tokens</th><th>inv\_30d</th><th>est\_$/mo (current)</th><th>est\_$/mo (post-L3)</th><th>savings\_$/mo</th><th>priority\_score</th><th>owner</th></tr></thead><tbody><tr><td>1</td><td>task-postflight</td><td>541</td><td>5,367</td><td>21</td><td>$0.547</td><td>$0.078</td><td>$0.469</td><td>82.054</td><td>john</td></tr><tr><td>2</td><td>prompt-forge</td><td>224</td><td>2,372</td><td>20</td><td>$0.350</td><td>$0.070</td><td>$0.280</td><td>70.877</td><td>john</td></tr><tr><td>3</td><td>plan-with-team</td><td>140</td><td>1,177</td><td>13</td><td>$0.105</td><td>$0.042</td><td>$0.063</td><td>42.991</td><td>john</td></tr><tr><td>4</td><td>build-plan</td><td>90</td><td>923</td><td>7</td><td>$0.126</td><td>$0.063</td><td>$0.063</td><td>23.722</td><td>john</td></tr><tr><td>5</td><td>ask-board</td><td>307</td><td>2,623</td><td>3</td><td>$0.125</td><td>$0.038</td><td>$0.087</td><td>13.675</td><td>john</td></tr><tr><td>6</td><td>build</td><td>79</td><td>838</td><td>3</td><td>$0.113</td><td>$0.057</td><td>$0.056</td><td>11.693</td><td>john</td></tr><tr><td>7</td><td>sentinel</td><td>105</td><td>990</td><td>2</td><td>$0.116</td><td>$0.058</td><td>$0.058</td><td>8.987</td><td>john</td></tr><tr><td>8</td><td>sync</td><td>46</td><td>346</td><td>2</td><td>$0.087</td><td>$0.087</td><td>$0.000</td><td>7.617</td><td>john</td></tr><tr><td>9</td><td>learning-opportunity</td><td>165</td><td>1,433</td><td>1</td><td>$0.067</td><td>$0.034</td><td>$0.033</td><td>6.313</td><td>john</td></tr><tr><td>10</td><td>vault-unlock</td><td>117</td><td>1,312</td><td>1</td><td>$0.142</td><td>$0.071</td><td>$0.071</td><td>6.236</td><td>john</td></tr><tr><td>11</td><td>incident-response</td><td>122</td><td>1,051</td><td>1</td><td>$0.067</td><td>$0.034</td><td>$0.033</td><td>6.043</td><td>john</td></tr><tr><td>12</td><td>youtube-learning</td><td>93</td><td>877</td><td>1</td><td>$0.136</td><td>$0.068</td><td>$0.068</td><td>5.886</td><td>john</td></tr><tr><td>13</td><td>code-review</td><td>87</td><td>674</td><td>1</td><td>$0.002</td><td>$0.001</td><td>$0.001</td><td>5.657</td><td>john</td></tr><tr><td>14</td><td>lightrag-upload</td><td>87</td><td>659</td><td>1</td><td>$0.117</td><td>$0.059</td><td>$0.058</td><td>5.638</td><td>john</td></tr><tr><td>15</td><td>lightrag-status</td><td>101</td><td>625</td><td>1</td><td>$0.121</td><td>$0.061</td><td>$0.060</td><td>5.592</td><td>john</td></tr><tr><td>16</td><td>product-lifecycle</td><td>491</td><td>5,103</td><td>0</td><td>$0.081</td><td>$0.041</td><td>$0.040</td><td>3.708</td><td>john</td></tr><tr><td>17</td><td>skill-creator</td><td>362</td><td>4,911</td><td>0</td><td>$0.088</td><td>$0.044</td><td>$0.044</td><td>3.691</td><td>john</td></tr><tr><td>18</td><td>doc-coauthoring</td><td>375</td><td>4,274</td><td>0</td><td>$0.208</td><td>$0.104</td><td>$0.104</td><td>3.631</td><td>john</td></tr><tr><td>19</td><td>mcp-builder</td><td>236</td><td>2,457</td><td>0</td><td>$0.135</td><td>$0.068</td><td>$0.067</td><td>3.390</td><td>john</td></tr><tr><td>20</td><td>plan-build-test</td><td>293</td><td>2,437</td><td>0</td><td>$0.099</td><td>$0.050</td><td>$0.049</td><td>3.387</td><td>john</td></tr></tbody></table>

*est\_$/mo (post-L3) = estimate assuming 50% body-token reduction via progressive disclosure*

---

## Per-Skill Triage (Top 10)

### \#1 task-postflight

- **Current footprint:** 541 LOC / 5,367 tokens
- **Why bloated:** BLOAT\_LOC\_GT\_300 — Contains anomaly decision tree (Section 3), learning-opportunity dispatch template (Section 4), memory writer procedure (Section 5), and failure mode reference table (Section 8) all inline in one file. Most of this content is only needed after an anomaly is detected.
- **Recommended action:** Split — progressive-disclose. Trigger skeleton ≤200 LOC stays in SKILL.md; Sections 3-5+8 move to references/.
- **Predicted savings:** ~3,500 tokens/session on typical PASS flows (63% context reduction); full 5,367 tokens only loaded on ANOMALY path.

### \#2 prompt-forge

- **Current footprint:** 224 LOC / 2,372 tokens
- **Why bloated:** Single references/agent-briefs.md exists but body still contains full 5-panelist dispatch protocol, model tier assignments, and synthesis rules inline. Most body content is needed only during the forge step.
- **Recommended action:** Split — move per-panelist briefs and synthesis rules to references/; keep trigger condition and dispatch skeleton in core.
- **Predicted savings:** ~1,200 tokens/session when invoked without full panelist detail read (50% reduction).

### \#3 plan-with-team

- **Current footprint:** 140 LOC / 1,177 tokens
- **Why bloated:** No references/ dir. Builder/validator role descriptions, round-robin protocol, and output templates are all inline. Frequently invoked (13x in window) — every invocation carries full load.
- **Recommended action:** Progressive-disclose — move builder brief and validator brief to references/. Keep selection logic in SKILL.md.
- **Predicted savings:** ~700 tokens/session (59% reduction) across 13 monthly invocations.

### \#4 build-plan

- **Current footprint:** 90 LOC / 923 tokens
- **Why bloated:** No references/ dir. Moderate size but high invocation frequency (7x). Output templates and TaskList format examples inline.
- **Recommended action:** Progressive-disclose — move TaskList format examples and edge-case handling to references/quick-ref.md.
- **Predicted savings:** ~400 tokens/session (43% reduction).

### \#5 ask-board

- **Current footprint:** 307 LOC / 2,623 tokens
- **Why bloated:** BLOAT\_LOC\_GT\_300 — 5-agent dispatch briefs are fully inline. Each panelist persona description (50-80 lines each) loads for every board invocation.
- **Recommended action:** Split — move per-panelist briefs to references/panelist-&lt;name&gt;.md. Keep dispatch skeleton (trigger, model tier, synthesis format) in SKILL.md.
- **Predicted savings:** ~1,800 tokens/session (69% reduction).

### \#6 build

- **Current footprint:** 79 LOC / 838 tokens
- **Why bloated:** No references/ dir. Build mode toggle and autocoder integration details inline. Reasonably compact but no progressive disclosure path for edge cases.
- **Recommended action:** Progressive-disclose — move edge-case handling (yolo mode, concurrency) to references/.
- **Predicted savings:** ~300 tokens/session (36% reduction). Low priority given small absolute size.

### \#7 sentinel

- **Current footprint:** 105 LOC / 990 tokens
- **Why bloated:** No references/ dir. 5-agent audit team definitions inline. Hardcoded audit procedure steps.
- **Recommended action:** Progressive-disclose — move per-agent audit checklists to references/; keep dispatch skeleton.
- **Predicted savings:** ~500 tokens/session (50% reduction).

### \#8 sync

- **Current footprint:** 46 LOC / 346 tokens
- **Why bloated:** Small and clean — no significant refactor needed. Score driven by 2 invocations.
- **Recommended action:** Keep as-is. Already close to L3 trigger skeleton.
- **Predicted savings:** Negligible. Lowest absolute token size in top-20.

### \#9 learning-opportunity

- **Current footprint:** 165 LOC / 1,433 tokens
- **Why bloated:** No references/ dir. Root-cause classification procedure, GOTCHA layer mapping, and fix-type catalog inline. Invoked only on anomaly path (1x).
- **Recommended action:** Progressive-disclose — move GOTCHA layer catalog and fix-type table to references/.
- **Predicted savings:** ~700 tokens/session (49% reduction).

### \#10 vault-unlock

- **Current footprint:** 117 LOC / 1,312 tokens
- **Why bloated:** HARDCODED\_PATH (/Users/makinja) — breaks Pillar #9 VM portability. Caddy proxy restart sequence and bw CLI flags inline.
- **Recommended action:** Progressive-disclose + fix HARDCODED\_PATH — move Caddy sequence to references/; replace /Users/makinja with $HOME.
- **Predicted savings:** ~600 tokens/session (46% reduction) + VM portability fix.

---

## Aggregate Savings (per-turn, not monthly $)

<table id="bkmrk-skills-loaded-per-tu"><thead><tr><th>skills loaded per turn</th><th>tokens saved vs. baseline</th><th>% context window recovered (128K window)</th></tr></thead><tbody><tr><td>Only task-postflight (PASS path)</td><td>3,500 tokens</td><td>2.7%</td></tr><tr><td>task-postflight + prompt-forge</td><td>4,700 tokens</td><td>3.7%</td></tr><tr><td>Top-5 hot-path skills (ranks 1-5)</td><td>7,300 tokens</td><td>5.7%</td></tr><tr><td>All top-20 (max benefit, full session)</td><td>19,500 tokens</td><td>15.2%</td></tr><tr><td>All 79 skills at L3 (theoretical max)</td><td>~35,000 tokens</td><td>27.3%</td></tr></tbody></table>

*Assumes 40-50% body-token reduction per skill post-refactor. Calculations: savings\_tokens = current\_tokens × 0.45. Context window basis: 128K tokens (Claude standard context). These are per-turn estimates derived from body-token reduction; monthly projections without measured session counts would be phantom claims.*

---

[← Back to Audit Summary](https://docs.alai.no/books/pillar-4-skills/page/audit-summary) | [Design Pattern →](https://docs.alai.no/books/pillar-4-skills/page/design-pattern)

# Design Pattern

# Progressive Disclosure Design Pattern

**Source:** `~/system/specs/agentic-os-pillar4-skills-audit-2026-05-04.md` (§5)  
**MC:** [\#99131](https://boards.alai.no/tasks/99131) | [\#99176](https://boards.alai.no/tasks/99176)  
**Date:** 2026-05-05

*Derived from `~/.claude/skills/skill-creator/SKILL.md` ("context window is a public good"). This section codifies what is implicit in the canonical reference — it does not invent a new framework.*

---

## Definition

Progressive disclosure for skills means that skill content is loaded in tiers based on actual need:

- **Tier 1 (frontmatter — always-loaded):** Every time a Claude session starts, all SKILL.md frontmatter `description` fields are loaded to determine which skills to activate. Frontmatter is the highest-cost content per byte because it loads regardless of usage.
- **Tier 2 (SKILL.md body — loaded on trigger):** After a skill matches its trigger condition, the full SKILL.md body loads. This is the decision-making and branching layer.
- **Tier 3 (references/ — loaded on demand):** Content in `references/` is loaded explicitly via `Read <path>` only when the agent reaches a branch that needs it. Scripts in `scripts/` are invoked without being loaded into context.

**The principle:** never load content that is not needed for the current branch of execution.

---

## L0–L3 Rubric

This rubric is used for the `progressive_disclosure_score` column in the inventory CSV.

<table id="bkmrk-level-definition-bod"><thead><tr><th>Level</th><th>Definition</th><th>Body size</th><th>References</th><th>Frontmatter</th><th>Hardcoded paths</th></tr></thead><tbody><tr><td>L0</td><td>Monolithic — entire skill in one file, no references/ dir</td><td>any (often &gt; 200 LOC)</td><td>absent</td><td>any size</td><td>allowed</td></tr><tr><td>L1</td><td>SKILL.md exists + references/ dir may exist, but body &gt; 200 lines OR references are read proactively (not conditionally)</td><td>&gt; 200 LOC</td><td>optional</td><td>any size</td><td>allowed</td></tr><tr><td>L2</td><td>SKILL.md body ≤ 200 lines; references/ loaded conditionally on branch; no hardcoded paths</td><td>≤ 200 LOC</td><td>conditional</td><td>any size</td><td>not allowed</td></tr><tr><td>L3</td><td>SKILL.md ≤ 60-line trigger skeleton; references/ strictly on-demand per branch; frontmatter ≤ 500 bytes; no hardcoded /Users/makinja paths</td><td>≤ 60 LOC</td><td>on-demand only</td><td>≤ 500 bytes</td><td>not allowed</td></tr></tbody></table>

**Distribution in current corpus:**

- L0: 32 skills (40.5%) — monolithic, no references
- L1: 38 skills (48.1%) — body &gt; 200 LOC or proactive refs
- L2: 2 skills (2.5%) — sentry-skill-scanner, task-splitter
- L3: 0 skills (0%) — no skill fully meets all L3 criteria

*Note: skill-creator comes closest to L3 intent but is 362 LOC (exceeds the 60-line body target).*

---

## Reference Exemplar

The canonical reference for the L3 pattern is `~/.claude/skills/skill-creator/`.

This skill demonstrates:

- `references/output-patterns.md` — loaded only when generating skill output
- `references/workflows.md` — loaded only for the workflow design step
- Clear "when to Read" callouts in the body
- Frontmatter description that covers all trigger cases without bloat

The canonical pattern from skill-creator states:

> "Keep SKILL.md body to the essentials and under 500 lines to minimize context bloat. Split content into separate files when approaching this limit. When splitting out content into other files, it is very important to reference them from SKILL.md and describe clearly when to read them, to ensure the reader of the skill knows they exist and when to use them."

A true L3 implementation would reduce this further to ≤60-line skeleton with all procedural content in references/.

---

## Anti-Pattern Catalog

All 9 anti-patterns documented (minimum 8 required per spec):

<table id="bkmrk-%23-pattern-detector-h"><thead><tr><th>\#</th><th>Pattern</th><th>Detector heuristic</th><th>Example skill</th><th>Fix</th></tr></thead><tbody><tr><td>1</td><td>`BLOAT_LOC_GT_300`</td><td>`wc -l SKILL.md > 300`</td><td>task-postflight (541L), product-lifecycle (491L), doc-coauthoring (375L)</td><td>Move decision trees and reference tables to references/</td></tr><tr><td>2</td><td>`FRONTMATTER_GT_500B`</td><td>description field bytes &gt; 500</td><td>docx (785B), xlsx (945B), pptx (690B), task-splitter (469B)</td><td>Condense to single-line trigger sentence; move examples to body</td></tr><tr><td>3</td><td>`INLINED_SCRIPT`</td><td>bash/python block embedded in markdown body</td><td>plan-build-test (Playwright CLI commands inline)</td><td>Move to scripts/run-tests.sh; invoke without loading into context</td></tr><tr><td>4</td><td>`DUPLICATE_PROCEDURE`</td><td>Same workflow steps appear in 2+ skills</td><td>product-lifecycle delegates to plan-with-team (6,266 tokens combined on product-lifecycle invocation)</td><td>Extract shared procedure to references/ in one skill; the other references it</td></tr><tr><td>5</td><td>`NO_TRIGGER`</td><td>No `description:` field in frontmatter, or field is empty</td><td>code-review (0B), qa-doc-review (0B), financial-overview (0B), invoice (0B), onboard-client (0B), onboard-partner (0B), send-for-signing (0B), form-filler (0B)</td><td>Add description: field with "Use when..." trigger condition</td></tr><tr><td>6</td><td>`NO_REFS_DIR`</td><td>No references/ subdirectory; entire skill in one file</td><td>70 of 79 skills</td><td>Create references/ dir; move branch-specific content</td></tr><tr><td>7</td><td>`DEAD_30D`</td><td>use\_count=0 AND no log hits in 19-day measurement window</td><td>doc-coauthoring, product-lifecycle, design-system, debugging (all 0 invocations)</td><td>Audit whether skill is still needed; consider retire or merge</td></tr><tr><td>8</td><td>`HARDCODED_PATH`</td><td>`/Users/makinja` embedded in skill body</td><td>learning-opportunity, vault-unlock, form-filler, plan-build-test</td><td>Replace with `$HOME` or relative path; required for Pillar #9 VM portability</td></tr><tr><td>9</td><td>`UNREGISTERED`</td><td>Disk directory exists but missing from skill-registry.db</td><td>17 skills (ask-board, deploy-verify, fiken-agent, hop-build, incident-response, library, lightrag-\*, prompt-forge, sync, task-postflight, task-splitter, template-meta-prompt, vault-unlock, web-search)</td><td>Run `INSERT INTO skills (name) VALUES ('<name>');` or skill-creator registration step</td></tr></tbody></table>

---

## Three-Tier Load Model

The canonical Anthropic pattern (derived from skill-creator/SKILL.md):

### Tier 1 — Always-Loaded (frontmatter only)

- **Content:** trigger condition + one-paragraph overview + when-to-use
- **Location:** YAML `description:` field
- **Target:** ≤ 60 lines total frontmatter / ≤ 1.5K tokens
- **Cost:** paid on every session, regardless of whether skill fires
- **Rule:** Never put procedural steps, code examples, or reference tables here

### Tier 2 — Loaded on Trigger (SKILL.md body)

- **Content:** process steps, branching logic, tool whitelist, output contract
- **Location:** SKILL.md body (everything after frontmatter `---`)
- **Target:** 60-200 lines / token budget ≤ 5K
- **Cost:** paid when skill trigger matches
- **Rule:** Include branch decision table; link to Tier 3 files explicitly

### Tier 3 — On-Demand (references/ and scripts/)

- **Content:** detailed procedures, examples, anti-pattern tables, worked code samples, branch-specific rules
- **Location:** `references/<branch>.md`, `scripts/<action>.sh`
- **Target:** unbounded; each file should be independently useful
- **Cost:** paid only when the agent reads the file on a specific branch
- **Rule:** Agent must see the file reference in Tier 2 SKILL.md body with explicit "when to read" instruction

---

## Canonical Skill Skeleton Template

```
---
name: <kebab-case-name>
description: Use when <concrete trigger>. Does <one-line outcome>.
argument-hint: <stdin-arg>
---

# <name>

## 1. Preconditions (<= 30 lines)
- Hard checks. Abort fast. Cite the hook that enforces if any.

## 2. Branch decision (<= 30 lines)
Pick the procedure, then load it:

| Condition | Procedure |
|---|---|
| <condition-A> | Read `./references/<branch-a>.md` |
| <condition-B> | Read `./references/<branch-b>.md` |

## 3. Sub-agent dispatch contract (<= 40 lines)
- Model tier (Haiku/Sonnet/Opus + rationale)
- Tool whitelist
- Brief path: `./references/<role>-brief.md`
- Output contract (path + format)

## 4. Closure (<= 30 lines)
- mc.js submission shape
- Memory write rule (cite owning skill; do NOT reimplement)

# Body MUST stay under 200 lines.
# Anything longer goes into references/<branch>.md.

```

*This template will be promoted to `~/system/specs/skill-skeleton-canonical.md` as a separate Skillforge step.*

---

[← Top-20 Priority](https://docs.alai.no/books/pillar-4-skills/page/top-20-priority) | [PoC Analysis →](https://docs.alai.no/books/pillar-4-skills/page/poc-task-postflight)

# PoC: task-postflight

# PoC: task-postflight Refactor

**Source:** `/tmp/pillar4-99131-out/poc-task-postflight-tier1.md` + `~/system/specs/agentic-os-pillar4-skills-audit-2026-05-04.md` (§6)  
**MC:** [\#99131](https://boards.alai.no/tasks/99131) | [\#99176](https://boards.alai.no/tasks/99176)  
**Branch:** `feat/pillar4-skills-poc` (merged to master 2026-05-05 ef8536ad)  
**Date:** 2026-05-05

---

## Overview

The PoC refactor of `task-postflight/SKILL.md` validates the three-tier progressive disclosure pattern on the highest-priority target.

- **Target:** 541 LOC → ≤ 200 LOC core trigger skeleton
- **New references/ files:** `anomaly-decision-tree.md`, `proveo-rubric.md`, `memory-writer.md`
- **Existing references/ preserved:** `proveo-brief.md`, `learning-loop.md` (unchanged)

---

## Token Reduction Analysis

<table id="bkmrk-metric-before-after-"><thead><tr><th>Metric</th><th>Before</th><th>After (PASS path)</th><th>After (ANOMALY path)</th></tr></thead><tbody><tr><td>SKILL.md LOC</td><td>541</td><td>≤190</td><td>≤190</td></tr><tr><td>SKILL.md bytes</td><td>19,859</td><td>~8,200</td><td>~8,200</td></tr><tr><td>Tokens loaded</td><td>5,367</td><td>~2,216</td><td>~2,216</td></tr><tr><td>Additional refs loaded</td><td>0</td><td>0</td><td>~3,000 (anomaly-decision-tree)</td></tr><tr><td>Total tokens (PASS path)</td><td>5,367</td><td>2,216</td><td>N/A</td></tr><tr><td>**Reduction on PASS path**</td><td>—</td><td>**59%**</td><td>—</td></tr><tr><td>Bytes reduction check</td><td>—</td><td>11,659 bytes saved / 19,859 = 58.7% ≥ 40%</td><td>**PASS**</td></tr></tbody></table>

The ≥40% byte reduction target is met on the typical PASS path. On anomaly paths, the `anomaly-decision-tree.md` is loaded (~3,000 additional tokens) but this is appropriate because the anomaly path requires that content.

---

## PoC Target Rationale

**Selection: task-postflight**

Priority score comparison:

<table id="bkmrk-skill-tokens_est-inv"><thead><tr><th>Skill</th><th>tokens\_est</th><th>inv\_30d</th><th>priority\_score</th></tr></thead><tbody><tr><td>task-postflight</td><td>5,367</td><td>21</td><td>**82.054**</td></tr><tr><td>prompt-forge</td><td>2,372</td><td>20</td><td>70.877</td></tr><tr><td>doc-coauthoring</td><td>4,274</td><td>0</td><td>3.631</td></tr><tr><td>product-lifecycle</td><td>5,103</td><td>0</td><td>3.708</td></tr></tbody></table>

Petter's preference for `doc-coauthoring` (376L, clean three-stage structure) was overridden by frequency data. `task-postflight` fires on every H/BLOCKER closure — 21 times in 19 days. `doc-coauthoring` has 0 measured invocations. Frequency × size dominates structural elegance.

---

## Trigger-Map Table

Content migration plan (required before coding per D3 pre-refactor requirement):

<table id="bkmrk-current-skill.md-sec"><thead><tr><th>Current SKILL.md section</th><th>Lines</th><th>Always needed?</th><th>Move to</th></tr></thead><tbody><tr><td>Frontmatter (description)</td><td>8</td><td>YES — trigger</td><td>Keep in SKILL.md</td></tr><tr><td>§1 Preconditions</td><td>32</td><td>YES — fail fast</td><td>Keep in SKILL.md</td></tr><tr><td>§2 Proveo dispatch</td><td>40</td><td>YES — every invocation</td><td>Keep in SKILL.md</td></tr><tr><td>§3 Anomaly decision tree</td><td>38</td><td>NO — only after Proveo returns</td><td>→ references/anomaly-decision-tree.md</td></tr><tr><td>§4 Learning-opportunity dispatch template</td><td>62</td><td>NO — only on ANOMALY path</td><td>→ references/anomaly-decision-tree.md</td></tr><tr><td>§5 Memory writer procedure</td><td>38</td><td>NO — only if learning returns memory</td><td>→ references/memory-writer.md</td></tr><tr><td>§6 Postflight marker writer</td><td>72</td><td>PARTIAL — Section 6a-6b always needed, 6c-6f only on success path</td><td>6a-6b keep; 6c-6f → references/marker-writer.md</td></tr><tr><td>§7 mc.js ready writer</td><td>52</td><td>PARTIAL — format in SKILL.md; details → references/</td><td>Keep dispatch shape; move table → references/</td></tr><tr><td>§8 Failure modes table</td><td>30</td><td>NO — reference only</td><td>→ references/anomaly-decision-tree.md</td></tr><tr><td>§9 Audit trail</td><td>20</td><td>YES — always runs</td><td>Keep in SKILL.md</td></tr><tr><td>v0.1 TODO + References footer</td><td>30</td><td>NO</td><td>Drop from PoC (TODO deferred)</td></tr></tbody></table>

---

## Content Split

### Stage 1 content (stays in SKILL.md core)

- Preconditions (1a-1c)
- Proveo dispatch inputs and expected output format
- Anomaly routing decision (IF/THEN — 4 cases, each with "Read ./references/anomaly-decision-tree.md")
- Postflight marker check (6a-6b only)
- mc.js ready submission shape
- Audit trail append

### Stages 2-N content (moved to references/)

- Full anomaly class decision tree → `references/anomaly-decision-tree.md`
- Learning-opportunity invocation template → `references/anomaly-decision-tree.md` (same file, appended)
- Memory writer procedure → `references/memory-writer.md`
- Marker writer full procedure (6c-6f) → `references/marker-writer.md`
- Failure modes table → appended to `references/anomaly-decision-tree.md`

### Existing references/ files

- `references/proveo-brief.md` — keep as-is (already correct progressive disclosure)
- `references/learning-loop.md` — keep as-is

---

## Verification Commands

```
# 1. Branch exists
git -C /Users/makinja/.claude branch --list "feat/pillar4-skills-poc"

# 2. LOC check
wc -l /Users/makinja/.claude/skills/task-postflight/SKILL.md  # must be <= 200

# 3. Reference files exist
ls /Users/makinja/.claude/skills/task-postflight/references/anomaly-decision-tree.md
ls /Users/makinja/.claude/skills/task-postflight/references/proveo-rubric.md
ls /Users/makinja/.claude/skills/task-postflight/references/memory-writer.md

# 4. Before/after snapshots exist
ls /tmp/pillar4-99131-out/poc-task-postflight-before.md
ls /tmp/pillar4-99131-out/poc-task-postflight-after.md

# 5. Byte reduction >= 40%
python3 -c "
before=$(wc -c < /tmp/pillar4-99131-out/poc-task-postflight-before.md)
after=$(wc -c < /tmp/pillar4-99131-out/poc-task-postflight-after.md)
print(f'Reduction: {(before-after)/before*100:.1f}%')
print('PASS' if (before-after) >= 0.4*before else 'FAIL')
"

# 6. No section header permanently lost
# Proveo verifies headers in before.md appear in {after.md + 3 ref files}

```

---

## PR Merged

**Branch:** `feat/pillar4-skills-poc`  
**Merged:** 2026-05-05T09:17:35Z  
**Commit:** ef8536adba17  
**Status:** Merged to master  
**Result:** 541 LOC → 194 LOC (64.7% reduction)

---

[← Design Pattern](https://docs.alai.no/books/pillar-4-skills/page/design-pattern) | [Audit Summary](https://docs.alai.no/books/pillar-4-skills/page/audit-summary)