ForgeFlow skills are runtime contracts, not dumping grounds. A large SKILL.md is allowed only when it remains navigable and delegates reusable detail to references.
- Keep SKILL.md focused on stage contracts: inputs, outputs, exit conditions, hard gates, and the shortest executable procedure belong inline.
- Move repeated policy into skills/_shared/: discipline, isolation, preflight, automation, and resume behavior must be centralized when more than one skill needs them.
- Move adapter-specific behavior into references/: CLI quirks, standalone fetch behavior, subagent prompts, role rubrics, and long checklists belong under
skills/<skill>/references/. - Declare dependencies in frontmatter: shared policy files must appear in
dependencies:so plugin importers and reviewers can see the contract surface without reading the whole body. - Declare a Reference inventory: each large workflow skill must include a
## Reference inventorysection with Markdown links to the references it relies on. - Prefer links over copy-paste: if the same paragraph would appear in two skills, put it in
_sharedor a skill reference and link it.
Run:
make validate-skill-modularityThe target is also part of make validate. It checks that the high-churn workflow skills (clarify, ff-plan, execute, ff-review, ship) stay under their inline size budgets, declare shared dependencies, and link required reference files.
This guard is intentionally boring. Boring is good here; entropy is the enemy, not insufficient creativity.