agentleFS
abhaylaabhayla/claude-best-practices/.claude/skills/provision-report/SKILL.md

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.

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
  1. Distinctive:

    MUST produce output conforming to this format.

    line 17
  2. Distinctive:

    Every provision report has 4 sections printed in this order:

    line 32
  3. Distinctive:

    If a PR was skipped (empty tier or PR already exists):

    line 110
  4. Distinctive:

    Always the last line before the closing ruler:

    line 117
  5. Distinctive:

    MUST call these functions or replicate this exact format.

    line 139
  6. Distinctive:

    When reviewing provision output, verify:

    line 143
  7. Distinctive:

    MUST include all 4 columns (Type, Name, Action, Reason) in every tier table

    line 156
  8. Distinctive:

    MUST provide a non-empty Reason for every pattern — never leave it blank

    line 157
  9. Distinctive:

    MUST sort by type then name alphabetically within each tier

    line 158
  10. Distinctive:

    MUST show the totals line matching actual counts

    line 159
  11. Distinctive:

    MUST use the exact Action values from the table above (not freeform text)

    line 160
  12. Distinctive:

    MUST show PR URLs in remote mode with action hints in parentheses

    line 161
  13. Distinctive:

    MUST NOT omit the Reason column or use generic reasons like "recommended"

    line 165
  14. Distinctive:

    MUST NOT mix patterns from different tiers in the same table section

    line 166
  15. Very specific:

    MUST NOT show config status (CLAUDE.md, settings.json) in remote mode output

    line 167
  16. Distinctive:

    MUST NOT show PR links in local mode output

    line 168
  17. Distinctive:

    MUST NOT change column widths without updating this spec (breaks alignment for scripts parsing the output)

    line 169
  18. Very specific:

    MUST NOT add new Action values without updating both recommend.py and this reference

    line 170

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

  1. Tier tables — one per non-empty tier (must-have, improved, nice-to-have, skip)
  2. Config status — CLAUDE.md, settings.json (local mode only)
  3. PR links — with action hints (remote mode only)
  4. 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 rule

Column Definitions

ColumnWidthContent
Type8 chars, left-alignedOne of: skill, agent, rule, hook
Name40 chars, left-alignedPattern name (kebab-case)
Action22 chars, left-alignedWhat will happen to this pattern
ReasonvariableWhy this tier was assigned

Action Values

TierAction ValueMeaning
must-haveadd (new)New pattern, not in project yet
improvedupgrade (hub newer)Hub has a newer version, overwrites existing
nice-to-haveoptionalAvailable but not auto-applied
skipskipNot relevant to this project

Reason Values

Reasons explain WHY a pattern was placed in its tier. Every item MUST have a non-empty reason.

ReasonMeaning
dependency detected in projectDEP_PATTERN_MAP matched a project dependency (e.g., vue in package.json promoted vue-dev)
matches detected stackStack prefix matches auto-detected stack (e.g., fastapi-db-migrate for fastapi-python stack)
core workflow skillIn CORE_WORKFLOW_SKILLS set (implement, fix-loop, tdd, etc.)
core ruleIn MUST_HAVE_RULES set (context-management, rule-writing-meta)
core agentIn MUST_HAVE_AGENTS set (security-auditor-agent)
essential safety hookIn MUST_HAVE_HOOKS set (dangerous-command-blocker, secret-scanner)
useful but optionalIn NICE_TO_HAVE_UNIVERSAL_SKILLS set
optional skill/rule/agent/hookUniversal pattern not in any priority list
stack override (not essential)In NICE_TO_HAVE_STACK_OVERRIDES (matches stack but downgraded)
wrong stackStack-prefixed pattern that doesn't match project's stacks
always-skip listIn ALWAYS_SKIP set (meta skills, wrong-domain)
hub vX.Y.Z > project vA.B.CImproved tier: hub version is newer
project has no version, hub has vX.Y.ZImproved tier: project pattern lacks version
same version (X.Y.Z) but different contentImproved 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: N

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

  1. Type (alphabetical: agent, hook, rule, skill)
  2. Name (alphabetical within type)

Implementation Reference

The canonical implementation lives in scripts/recommend.py:

  • tier_resource_with_reason() — returns (tier, reason) tuples
  • analyze_gaps() — populates reason field on every gap item
  • main() 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.py and this reference

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.