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

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

MetricValueSource
Active skill dirs on disk79ls ~/.claude/skills/ | grep -v _archived | wc -l
Archived skills32ls ~/.claude/skills/_archived/ | wc -l
skill-registry.db rows94sqlite3 skill-registry.db 'SELECT COUNT(*) FROM skills;'
DB-only phantoms32comm comparison
Disk-only unregistered17comm comparison
Skills with references/ dir9find query
Skills with invocations in window15log grep
Measurement window19 days2026-04-16 to 2026-05-05
Total invocations in window267awk filter
Ghost invocations (mehanik, no disk)186log grep — mehanik not on disk

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:

Key findings from CSV:

→ See Top-20 Refactor Priority Table

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

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 Priority

Top-20 Refactor Priority Table

Source: ~/system/specs/agentic-os-pillar4-skills-audit-2026-05-04.md (§4)
MC: #99131 | #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:

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)

rank skill_name LOC tokens inv_30d est_$/mo (current) est_$/mo (post-L3) savings_$/mo priority_score owner
1task-postflight5415,36721$0.547$0.078$0.46982.054john
2prompt-forge2242,37220$0.350$0.070$0.28070.877john
3plan-with-team1401,17713$0.105$0.042$0.06342.991john
4build-plan909237$0.126$0.063$0.06323.722john
5ask-board3072,6233$0.125$0.038$0.08713.675john
6build798383$0.113$0.057$0.05611.693john
7sentinel1059902$0.116$0.058$0.0588.987john
8sync463462$0.087$0.087$0.0007.617john
9learning-opportunity1651,4331$0.067$0.034$0.0336.313john
10vault-unlock1171,3121$0.142$0.071$0.0716.236john
11incident-response1221,0511$0.067$0.034$0.0336.043john
12youtube-learning938771$0.136$0.068$0.0685.886john
13code-review876741$0.002$0.001$0.0015.657john
14lightrag-upload876591$0.117$0.059$0.0585.638john
15lightrag-status1016251$0.121$0.061$0.0605.592john
16product-lifecycle4915,1030$0.081$0.041$0.0403.708john
17skill-creator3624,9110$0.088$0.044$0.0443.691john
18doc-coauthoring3754,2740$0.208$0.104$0.1043.631john
19mcp-builder2362,4570$0.135$0.068$0.0673.390john
20plan-build-test2932,4370$0.099$0.050$0.0493.387john

est_$/mo (post-L3) = estimate assuming 50% body-token reduction via progressive disclosure

Per-Skill Triage (Top 10)

#1 task-postflight

#2 prompt-forge

#3 plan-with-team

#4 build-plan

#5 ask-board

#6 build

#7 sentinel

#8 sync

#9 learning-opportunity

#10 vault-unlock

Aggregate Savings (per-turn, not monthly $)

skills loaded per turn tokens saved vs. baseline % context window recovered (128K window)
Only task-postflight (PASS path)3,500 tokens2.7%
task-postflight + prompt-forge4,700 tokens3.7%
Top-5 hot-path skills (ranks 1-5)7,300 tokens5.7%
All top-20 (max benefit, full session)19,500 tokens15.2%
All 79 skills at L3 (theoretical max)~35,000 tokens27.3%

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 | Design Pattern →

Design Pattern

Progressive Disclosure Design Pattern

Source: ~/system/specs/agentic-os-pillar4-skills-audit-2026-05-04.md (§5)
MC: #99131 | #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:

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.

Level Definition Body size References Frontmatter Hardcoded paths
L0Monolithic — entire skill in one file, no references/ dirany (often > 200 LOC)absentany sizeallowed
L1SKILL.md exists + references/ dir may exist, but body > 200 lines OR references are read proactively (not conditionally)> 200 LOCoptionalany sizeallowed
L2SKILL.md body ≤ 200 lines; references/ loaded conditionally on branch; no hardcoded paths≤ 200 LOCconditionalany sizenot allowed
L3SKILL.md ≤ 60-line trigger skeleton; references/ strictly on-demand per branch; frontmatter ≤ 500 bytes; no hardcoded /Users/makinja paths≤ 60 LOCon-demand only≤ 500 bytesnot allowed

Distribution in current corpus:

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:

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

# Pattern Detector heuristic Example skill Fix
1BLOAT_LOC_GT_300wc -l SKILL.md > 300task-postflight (541L), product-lifecycle (491L), doc-coauthoring (375L)Move decision trees and reference tables to references/
2FRONTMATTER_GT_500Bdescription field bytes > 500docx (785B), xlsx (945B), pptx (690B), task-splitter (469B)Condense to single-line trigger sentence; move examples to body
3INLINED_SCRIPTbash/python block embedded in markdown bodyplan-build-test (Playwright CLI commands inline)Move to scripts/run-tests.sh; invoke without loading into context
4DUPLICATE_PROCEDURESame workflow steps appear in 2+ skillsproduct-lifecycle delegates to plan-with-team (6,266 tokens combined on product-lifecycle invocation)Extract shared procedure to references/ in one skill; the other references it
5NO_TRIGGERNo description: field in frontmatter, or field is emptycode-review (0B), qa-doc-review (0B), financial-overview (0B), invoice (0B), onboard-client (0B), onboard-partner (0B), send-for-signing (0B), form-filler (0B)Add description: field with "Use when..." trigger condition
6NO_REFS_DIRNo references/ subdirectory; entire skill in one file70 of 79 skillsCreate references/ dir; move branch-specific content
7DEAD_30Duse_count=0 AND no log hits in 19-day measurement windowdoc-coauthoring, product-lifecycle, design-system, debugging (all 0 invocations)Audit whether skill is still needed; consider retire or merge
8HARDCODED_PATH/Users/makinja embedded in skill bodylearning-opportunity, vault-unlock, form-filler, plan-build-testReplace with $HOME or relative path; required for Pillar #9 VM portability
9UNREGISTEREDDisk directory exists but missing from skill-registry.db17 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)Run INSERT INTO skills (name) VALUES ('<name>'); or skill-creator registration step

Three-Tier Load Model

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

Tier 1 — Always-Loaded (frontmatter only)

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

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

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 | PoC Analysis →

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 | #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.

Token Reduction Analysis

Metric Before After (PASS path) After (ANOMALY path)
SKILL.md LOC541≤190≤190
SKILL.md bytes19,859~8,200~8,200
Tokens loaded5,367~2,216~2,216
Additional refs loaded00~3,000 (anomaly-decision-tree)
Total tokens (PASS path)5,3672,216N/A
Reduction on PASS path—59%—
Bytes reduction check—11,659 bytes saved / 19,859 = 58.7% ≥ 40%PASS

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:

Skill tokens_est inv_30d priority_score
task-postflight5,3672182.054
prompt-forge2,3722070.877
doc-coauthoring4,27403.631
product-lifecycle5,10303.708

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

Current SKILL.md section Lines Always needed? Move to
Frontmatter (description)8YES — triggerKeep in SKILL.md
§1 Preconditions32YES — fail fastKeep in SKILL.md
§2 Proveo dispatch40YES — every invocationKeep in SKILL.md
§3 Anomaly decision tree38NO — only after Proveo returns→ references/anomaly-decision-tree.md
§4 Learning-opportunity dispatch template62NO — only on ANOMALY path→ references/anomaly-decision-tree.md
§5 Memory writer procedure38NO — only if learning returns memory→ references/memory-writer.md
§6 Postflight marker writer72PARTIAL — Section 6a-6b always needed, 6c-6f only on success path6a-6b keep; 6c-6f → references/marker-writer.md
§7 mc.js ready writer52PARTIAL — format in SKILL.md; details → references/Keep dispatch shape; move table → references/
§8 Failure modes table30NO — reference only→ references/anomaly-decision-tree.md
§9 Audit trail20YES — always runsKeep in SKILL.md
v0.1 TODO + References footer30NODrop from PoC (TODO deferred)

Content Split

Stage 1 content (stays in SKILL.md core)

Stages 2-N content (moved to references/)

Existing references/ files

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 | Audit Summary