| name | agent-skill-compaction |
| description | Compacts and organizes project agent and skill Markdown under .pi/agents and .pi/skills without weakening contracts. Use after any agent/skill edit, or invoke directly to clean the full recursive tree by default. |
Compaction
Compact policy; preserve meaning. Default: .pi/{agents,skills}/**/*.md;
args may narrow.
flowchart LR
A[Inventory] --> B[Capture contracts]
B --> C[Compact by concept]
C --> D[Validate]
D --> E{Pass?}
E -- no --> C
E -- yes --> F[Independent review]
Rule
long prose -> short rules -> arrow map -> command table
- Group/deduplicate concepts; use terse fragments.
- Tables: commands/ownership/states. Mermaid: branches.
- Keep needed examples.
- Preserve: front matter; prohibitions; exceptions; approvals; safety; ownership; evidence; freshness; acceptance; revert/escalation; tools; budgets; selectors; paths; commands; flags; schemas; outputs; test literals; links/anchors/URLs; formulas; addresses;
SKILL.md/reference boundaries.
Run
- Baseline:
.pi/skills/agent-skill-compaction/scripts/audit.py --output /tmp/agent-skill-before.json.
- Read related files. Compact agents, then each skill tree.
- Compare with
HEAD or baseline.
- Check:
.pi/skills/agent-skill-compaction/scripts/audit.py --baseline /tmp/agent-skill-before.json --check.
- Run contexts, focused tests, and
test-skill-scripts.py.
- Run
git diff --check; require empty staged diff.
- Get semantic review.
Missing command -> report; run nearest structural check. Never skip silently.
Bounds
Markdown policy only. No semantic changes; code, target metadata, lifts,
generated state, stage, commit, or push. Preserve unrelated dirt. Failed
contract -> repair/revert scoped rewrite; never waive.
Report files, size delta, checks, review, skips, risks. See checklist.
