provision-report
Skill9 starsChanged 7 months agoMITView on GitHub
Reference guide for the canonical provision summary format used by recommend.py and /synthesize-project. Defines the 4-section tabular layout with Type, Name, Action, and Reason columns. Consult when building or modifying any provisioning output to ensure format consistency.
In this repository44 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- anthropic-multi-agent-research-system-skillSkill
- apply-selectionsSkill
- bootstrap-dogfood-projectSkill
- brainstormSkill
- branch-choiceSkill
- cc-adoption-scoutSkill
- claude-guardianSkill
- continueSkill
- end-sessionSkill
- executing-plansSkill
- five-advisorsSkill
- get-work-doneSkill
- git-branch-lifecycleSkill
- githubSkill
- grill-meSkill
- hook-transcript-fixture-testSkill
- instagramSkill
- linkedinSkill
- modern-data-pipeline-diagramSkill
- pattern-qualitySkill
- platform-event-live-probeSkill
- plugin-lifecycleSkill
- promote-to-coreSkill
- prompt-auto-enhanceSkill
- redditSkill
- review-new-claude-featuresSkill
- save-sessionSkill
- scan-discovery-reportSkill
- scan-repoSkill
- scan-urlSkill
- self-improveSkill
- skill-evaluatorSkill
- skill-masterSkill
- ssot-workflow-auditSkill
- start-sessionSkill
- synthesize-hubSkill
- synthesize-projectSkill
- twitter-xSkill
- verify-effect-at-destinationSkill
- workflow-doc-reviewerSkill
- writing-plansSkill
- writing-skillsSkill
- youtube-transcriptSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
18 rules. About 0 are common, 16 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈16
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 17
MUST produce output conforming to this format.
- Distinctive: line 32
Every provision report has 4 sections printed in this order:
- Distinctive: line 110
If a PR was skipped (empty tier or PR already exists):
- Distinctive: line 117
Always the last line before the closing ruler:
- Distinctive: line 139
MUST call these functions or replicate this exact format.
- Distinctive: line 143
When reviewing provision output, verify:
- Distinctive: line 156
MUST include all 4 columns (Type, Name, Action, Reason) in every tier table
- Distinctive: line 157
MUST provide a non-empty Reason for every pattern — never leave it blank
- Distinctive: line 158
MUST sort by type then name alphabetically within each tier
- Distinctive: line 159
MUST show the totals line matching actual counts
- Distinctive: line 160
MUST use the exact Action values from the table above (not freeform text)
- Distinctive: line 161
MUST show PR URLs in remote mode with action hints in parentheses
- Distinctive: line 165
MUST NOT omit the Reason column or use generic reasons like "recommended"
- Distinctive: line 166
MUST NOT mix patterns from different tiers in the same table section
- Very specific: line 167
MUST NOT show config status (CLAUDE.md, settings.json) in remote mode output
- Distinctive: line 168
MUST NOT show PR links in local mode output
- Distinctive: line 169
MUST NOT change column widths without updating this spec (breaks alignment for scripts parsing the output)
- Very specific: line 170
MUST NOT add new Action values without updating both recommend.py and this reference
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Provision Report Format Standard
Reference specification for the provision summary output format. All provisioning
operations (recommend.py --provision, /synthesize-project, /synthesize-hub)
MUST produce output conforming to this format.
Origin
This format was created after the 3-layer tiering upgrade (2026-03-16) when
recommend.py --provision against AlgoChanakya produced output that lacked
visibility into WHY each pattern was selected or skipped. The user requested
Type, Name, Action, and Reason columns to make provisioning decisions reviewable
and auditable. The format is now enforced by tier_resource_with_reason() in
scripts/recommend.py.
Report Structure
Every provision report has 4 sections printed in this order:
- Tier tables — one per non-empty tier (must-have, improved, nice-to-have, skip)
- Config status — CLAUDE.md, settings.json (local mode only)
- PR links — with action hints (remote mode only)
- Totals — single-line count per tier
Tier Table Format
Each tier section uses a fixed-width tabular layout:
--- MUST-HAVE (N) ---
Type Name Action Reason
---- ---- ------ ------
skill tailwind-dev add (new) dependency detected in project
skill vue-dev add (new) dependency detected in project
rule context-management add (new) core ruleColumn Definitions
| Column | Width | Content |
| Type | 8 chars, left-aligned | One of: skill, agent, rule, hook |
| Name | 40 chars, left-aligned | Pattern name (kebab-case) |
| Action | 22 chars, left-aligned | What will happen to this pattern |
| Reason | variable | Why this tier was assigned |
Action Values
| Tier | Action Value | Meaning |
| must-have | add (new) | New pattern, not in project yet |
| improved | upgrade (hub newer) | Hub has a newer version, overwrites existing |
| nice-to-have | optional | Available but not auto-applied |
| skip | skip | Not relevant to this project |
Reason Values
Reasons explain WHY a pattern was placed in its tier. Every item MUST have a non-empty reason.
| Reason | Meaning |
dependency detected in project | DEP_PATTERN_MAP matched a project dependency (e.g., vue in package.json promoted vue-dev) |
matches detected stack | Stack prefix matches auto-detected stack (e.g., fastapi-db-migrate for fastapi-python stack) |
core workflow skill | In CORE_WORKFLOW_SKILLS set (implement, fix-loop, tdd, etc.) |
core rule | In MUST_HAVE_RULES set (context-management, rule-writing-meta) |
core agent | In MUST_HAVE_AGENTS set (security-auditor-agent) |
essential safety hook | In MUST_HAVE_HOOKS set (dangerous-command-blocker, secret-scanner) |
useful but optional | In NICE_TO_HAVE_UNIVERSAL_SKILLS set |
optional skill/rule/agent/hook | Universal pattern not in any priority list |
stack override (not essential) | In NICE_TO_HAVE_STACK_OVERRIDES (matches stack but downgraded) |
wrong stack | Stack-prefixed pattern that doesn't match project's stacks |
always-skip list | In ALWAYS_SKIP set (meta skills, wrong-domain) |
hub vX.Y.Z > project vA.B.C | Improved tier: hub version is newer |
project has no version, hub has vX.Y.Z | Improved tier: project pattern lacks version |
same version (X.Y.Z) but different content | Improved tier: content diverged at same version |
Config Status Section (Local Mode)
--- CONFIG ---
CLAUDE.md: created|replaced|appended|skipped
settings.json: created|merged|skipped
Files copied: NPR Links Section (Remote Mode)
--- PRs CREATED ---
must-have https://github.com/owner/repo/pull/N (merge confidently)
improved https://github.com/owner/repo/pull/N (review diffs)
nice-to-have https://github.com/owner/repo/pull/N (check boxes, comment /apply)If a PR was skipped (empty tier or PR already exists):
improved (skipped)Totals Line
Always the last line before the closing ruler:
TOTAL: N must-have, N improved, N nice-to-have, N skip
====================================================================================================Sort Order
Within each tier table, items are sorted by:
- Type (alphabetical: agent, hook, rule, skill)
- Name (alphabetical within type)
Implementation Reference
The canonical implementation lives in scripts/recommend.py:
tier_resource_with_reason()— returns(tier, reason)tuplesanalyze_gaps()— populatesreasonfield on every gap itemmain()Step 6b — prints the summary using the format above
Any new provisioning pathway (new scripts, skills, or agents that produce provision output) MUST call these functions or replicate this exact format.
Validation Checklist
When reviewing provision output, verify:
- Every tier section has the 4-column header (Type, Name, Action, Reason)
- No pattern appears in more than one tier
- Reason is never empty — every item has an explanation
- Sort order is type-then-name alphabetical
- Totals line counts match the actual items listed
- Remote mode shows PR URLs; local mode shows config status
- Dep-promoted patterns show "dependency detected in project" as reason
- Improved patterns show version comparison as reason
MUST DO
- MUST include all 4 columns (Type, Name, Action, Reason) in every tier table
- MUST provide a non-empty Reason for every pattern — never leave it blank
- MUST sort by type then name alphabetically within each tier
- MUST show the totals line matching actual counts
- MUST use the exact Action values from the table above (not freeform text)
- MUST show PR URLs in remote mode with action hints in parentheses
MUST NOT DO
- MUST NOT omit the Reason column or use generic reasons like "recommended"
- MUST NOT mix patterns from different tiers in the same table section
- MUST NOT show config status (CLAUDE.md, settings.json) in remote mode output
- MUST NOT show PR links in local mode output
- MUST NOT change column widths without updating this spec (breaks alignment for scripts parsing the output)
- MUST NOT add new Action values without updating both
recommend.pyand this reference
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

