Reference Enrichment Skill

Reference Enrichment Skill

Enrich an agent or skill's reference files from Level 0-2 to Level 3+, or decompose bloated body files by extracting domain content into references. Enrichment adds knowledge; decomposition moves knowledge to where progressive disclosure says it belongs. The enrichment pipeline runs five phases with explicit gates because each phase feeds the next — starting Phase 3 without Phase 2 research produces filler, not depth.

Workflow

Phase 0: DECOMPOSE

Goal: Extract domain-heavy content from a bloated SKILL.md or agent body into reference files.

When to use: When a component's body exceeds ~500 lines and contains catalogs, code examples, specification tables, or agent rosters that should live in references/ per PHILOSOPHY.md's progressive disclosure architecture.

Trigger: Invoke with --decompose argument, or when the request matches "decompose", "extract references", "slim down", "too long", or "move to references".

1. Run the detection script to identify extractable content:

   python3 scripts/detect-decomposition-targets.py --skill {name}
   

   (or --agent {name})

2. If no extractable blocks found, report "nothing to decompose" and stop

3. Save a snapshot of the original file: cp {path} /tmp/decomp-before-{name}.md

4. For each extractable block identified by the detection script: a. Read the content block and its surrounding context b. Determine the best reference filename:

   • Use the detection script's suggestion as a starting point
   • If a reference file with related content already exists, MERGE into it
   • Follow naming convention: references/{topic}.md (lowercase, hyphens) c. Create or update the reference file following references/reference-file-template.md d. Remove the content from the body (MOVE, not copy) e. Add a loading table entry in the body that maps task signals to the new reference file

5. Ensure the body retains:

   • YAML frontmatter