agentleFS
abhaylaabhayla/claude-best-practices/.claude/skills/synthesize-project/SKILL.md

synthesize-project

Skill9 starsChanged 7 months agoMITView on GitHub

Provision hub patterns AND generate project-specific .claude/ patterns for a TARGET PROJECT. Writes ONLY to the target project's .claude/ directory (local) or creates a PR on the target repo (remote). NEVER writes to core/.claude/ — that is the hub template. If running from the hub repo, --repo or --local is REQUIRED. Use --skip-hub for synthesis only, --skip-synthesis for hub patterns only.

The file

Show its rules and text

We split this skill into the rules it gives an agent

35 rules. About 0 are common, 12 are distinctive, and 23 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈12

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 23

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Before anything else, detect whether you are currently running inside the claude-best-practices hub repo (the repo that contains …

    line 50
  2. Very specific:

    If --repo was NOT provided and no --local /path was given, STOP and ask: "You're running inside the hub repo.

    line 59
  3. Very specific:

    NEVER write synthesized patterns to core/.claude/.

    line 60
  4. Very specific:

    NEVER treat scanning a downstream repo as "adding patterns to the hub." That is the job of collate.py and the hub's own synthesis workflow, …

    line 61
  5. Very specific:

    If --repo owner/name is provided, set up remote file access.

    line 67
  6. Distinctive:

    Verify the repo exists and you have access:

    line 71
  7. Very specific:

    If this command fails (auth error, 404, permission denied), STOP and report the error.

    line 75
  8. Very specific:

    Local mode: No setup needed. Use Glob, Read, Grep as normal throughout all steps.

    line 94
  9. Very specific:

    For all subsequent steps: When this document says "read a file" or "use Read/Glob", use the appropriate method based on mode — local tools …

    line 96
  10. Very specific:

    Run recommend.py --provision --json to copy matching hub patterns and generate CLAUDE.md/settings.json for the project.

    line 106
  11. Very specific:

    If --skip-synthesis is set: After this step, jump directly to Step 9 (summary).

    line 141
  12. Distinctive:

    Read config files (read whichever exist):

    line 153
  13. Very specific:

    Read entry points — files matching: main.*, app.*, index.*, server.*, manage.py, wsgi.py

    line 159
  14. Very specific:

    Check for monorepo indicators: workspaces field in package.json, pnpm-workspace.yaml, lerna.json, nx.json, or multiple go.mod files at …

    line 169
  15. Very specific:

    If detected, ask: "This appears to be a monorepo with [N] packages.

    line 171
  16. Distinctive:

    If fewer than 3 conventions are identified, inform the user: "This project may not have enough code for meaningful synthesis.

    line 177
  17. Distinctive:

    Wait for user acknowledgment: before proceeding to Step 5.

    line 228
  18. Distinctive:

    Before generating patterns, load the format standards and examples that guide generation quality.

    line 232
  19. Distinctive:

    Read the pattern structure standards (these define required format):

    line 234
  20. Very specific:

    Read 2-3 existing patterns from core/.claude/ as format examples matching the project's stack:

    line 240
  21. Very specific:

    If hub patterns were copied in Step 1, read from the project's own .claude/ instead.

    line 246
  22. Distinctive:

    If the hub patterns are not available locally (project was not bootstrapped from the hub), skip this step and use the format requirements …

    line 248
  23. Very specific:

    No placeholder markers (<!-- TODO -->, <!-- FIXME -->)?

    line 353
  24. Very specific:

    If it references another skill by name, does that skill exist in the project's .claude/?

    line 354
  25. Very specific:

    If workflow_quality_gate_validate_patterns.py or dedup_check.py are not available (running outside the hub repo), perform manual validation …

    line 376
  26. Very specific:

    Generate synthesis-config.yml: if it doesn't exist — create with sharing OFF:

    line 385
  27. Very specific:

    If synthesis-config.yml already exists: Do not overwrite it. Respect existing consent settings.

    line 415
  28. Distinctive:

    NEVER generate generic best-practice patterns.

    line 424
  29. Very specific:

    NEVER write patterns with confidence: low.

    line 425
  30. Very specific:

    NEVER overwrite synthesis-config.yml if it already exists.

    line 426
  31. Very specific:

    If --update mode finds stale patterns, do NOT delete them automatically.

    line 428
  32. Distinctive:

    NEVER cap, limit, or prioritize a subset of confirmed conventions.

    line 431
  33. Distinctive:

    ALWAYS create SEPARATE PRs for each tier (must-have, nice-to-have, enhanced) in remote mode.

    line 432
  34. Distinctive:

    ALWAYS perform deep scan — read ALL evidence files needed to confirm conventions.

    line 433
  35. Distinctive:

    When deduping against hub patterns in Step 3, err on the side of KEEPING the project-specific convention.

    line 434

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

Synthesize Project Patterns

Provision hub patterns and generate project-specific .claude/ patterns by reading the actual codebase.

Critical constraints: This skill writes ONLY to the TARGET PROJECT's .claude/ directory. NEVER write to core/.claude/ — that is the hub template. In remote mode, creates a PR on the target repo. If running from the hub repo, --repo or --local is REQUIRED.

Arguments: $ARGUMENTS


Mode Detection

FlagEffect
(none)Full flow: hub provision + code synthesis
--repo owner/nameRemote mode — fetch via GitHub API, create PR
--updateDelta only — skip hub provision, synthesize only new/stale conventions
--dry-runPreview only, no writes
--skip-hubSkip Step 1 (no hub patterns, synthesis only — old behavior)
--skip-synthesisSkip Steps 2-8 (hub patterns only — equivalent to recommend.py --provision). Jumps to Step 9.

--repo can be combined with --update, --dry-run, --skip-hub, or --skip-synthesis.


STEP 0: Determine Source (Local vs Remote)

Hub repo guard (CRITICAL)

Before anything else, detect whether you are currently running inside the claude-best-practices hub repo (the repo that contains core/.claude/, registry/patterns.json, and scripts/recommend.py). Check:

# If ALL of these exist, you are in the hub repo
test -d core/.claude && test -f registry/patterns.json && test -f scripts/recommend.py

If you ARE in the hub repo:

  • --repo owner/name is REQUIRED. You MUST be targeting a different repo.
  • If --repo was NOT provided and no --local /path was given, STOP and ask: "You're running inside the hub repo. Which project should I synthesize patterns for? Use --repo owner/name or --local /path/to/project."
  • NEVER write synthesized patterns to core/.claude/. That directory is the hub's distributable template — only curated, generic patterns belong there. Project-specific patterns go to the TARGET project's .claude/.
  • NEVER treat scanning a downstream repo as "adding patterns to the hub." That is the job of collate.py and the hub's own synthesis workflow, NOT this skill.

If you are NOT in the hub repo: Proceed normally — local mode targets the current directory.


If --repo owner/name is provided, set up remote file access. Otherwise, use local tools.

Remote mode setup:

  1. Verify the repo exists and you have access:
    gh repo view owner/name --json name,defaultBranchRef
    If this command fails (auth error, 404, permission denied), STOP and report the error. Do not proceed — all subsequent gh api calls will fail.
  2. Fetch the repository file tree:
    gh api repos/owner/name/git/trees/HEAD?recursive=1 --jq '.tree[] | select(.type=="blob") | .path'
  3. Define a helper function for reading remote files (use throughout all subsequent steps instead of Read):
    # Fetch a single file's content from the repo
    gh api repos/owner/name/contents/PATH --jq '.content | @base64d'
  4. For --update mode, also fetch existing .claude/ patterns from the repo:
    gh api repos/owner/name/contents/.claude/rules --jq '.[].name'
    gh api repos/owner/name/contents/.claude/skills --jq '.[].name'

Local mode: No setup needed. Use Glob, Read, Grep as normal throughout all steps.

For all subsequent steps: When this document says "read a file" or "use Read/Glob", use the appropriate method based on mode — local tools for local mode, gh api for remote mode.


STEP 1: Provision Hub Patterns

Skip this step if: --skip-hub is set, OR --update is set (hub patterns were already provisioned on first run).

If --dry-run: Run recommend.py --json (WITHOUT --provision) to capture the gap analysis for dedup context, but do NOT copy any files. Print "Dry-run: captured hub gap analysis for dedup (no files copied)." Note: dry-run synthesis results may differ slightly from real runs since hub patterns are not physically present in the project directory.

Run recommend.py --provision --json to copy matching hub patterns and generate CLAUDE.md/settings.json for the project. The --json flag outputs structured 5-category results (must-have, improved, nice-to-have, synthesized, skip) that this skill parses.

Local mode:

# Run from the hub repo root (where recommend.py lives)
PYTHONPATH=. python scripts/recommend.py --local "$PROJECT_DIR" --provision --json

Where $PROJECT_DIR is the target project's absolute path. If the user is running this in the target project directory and the hub repo is at a known location, adjust the command accordingly.

Remote mode:

PYTHONPATH=. python scripts/recommend.py --repo owner/name --provision --json

Parse the JSON output to capture the 5-category breakdown:

  • must-have: New patterns to add (merge confidently)
  • improved: Hub has newer versions of existing patterns (review diffs)
  • nice-to-have: Optional patterns (checkbox PR in remote mode)
  • synthesized: Placeholder for Step 7 (filled by this skill)
  • skip: Patterns not relevant to this project

Also capture:

  • Number of files copied
  • Which patterns were added (rules, skills, agents)
  • CLAUDE.md status (created / updated / already existed)
  • settings.json status (created / merged / already existed)
  • Number of patterns skipped (already existed in project)

Store these counts for the summary in Step 9.

If recommend.py is not available (e.g., this skill is running in a project that doesn't have the hub repo locally), skip this step gracefully and proceed to Step 2. Print a note: "Hub repo not found — skipping hub provisioning. Use --skip-hub to suppress this message."

If --skip-synthesis is set: After this step, jump directly to Step 9 (summary). Skip Steps 2-8 entirely — synthesis-config.yml is a synthesis artifact and should not be generated when synthesis is skipped.


STEP 2: Map the Project

Gather project structure and configuration to understand what this project is and how it's built.

  1. Map the file tree — capture the top 3 levels of directory structure
    • Local: Use Glob
    • Remote: Already fetched in Step 0 — filter the tree output
  2. Read config files (read whichever exist):
    • Package configs: pyproject.toml, package.json, build.gradle, build.gradle.kts, Cargo.toml, go.mod, pom.xml, Gemfile
    • CI configs: .github/workflows/*.yml, Jenkinsfile, .gitlab-ci.yml, Dockerfile, docker-compose.yml
    • Linter/formatter configs: .eslintrc*, ruff.toml, pyproject.toml [tool.ruff], .prettierrc*, biome.json
    • Project CLAUDE.md or README.md (if they exist — these reveal stated conventions)
  3. Read entry points — files matching: main.*, app.*, index.*, server.*, manage.py, wsgi.py
  4. Find the test directory, then read one representative test file (pick the largest test file — it likely demonstrates the most conventions). If no test directory or test files are found, note "No test files detected — skipping test convention analysis" and proceed.

If --update mode: Also read all existing .claude/rules/*.md, .claude/skills/*/SKILL.md, and .claude/agents/*.md to understand what patterns already exist. For each existing pattern with synthesized: true, record its evidence files (mentioned in pattern body) for staleness detection in Step 3.

Output of this step: A mental model of the project's stack, structure, dependencies, and testing approach.

Monorepo detection

Check for monorepo indicators: workspaces field in package.json, pnpm-workspace.yaml, lerna.json, nx.json, or multiple go.mod files at different levels.

If detected, ask: "This appears to be a monorepo with [N] packages. Which package(s) should I synthesize for? (Enter names, or all for shared conventions.)" Scope Steps 3-7 to the selected package(s).

STEP 3: Identify Conventions (with Dedup Against Hub)

Based on what you learned in Step 2, identify 10-20 candidate conventions worth encoding as patterns.

If fewer than 3 conventions are identified, inform the user: "This project may not have enough code for meaningful synthesis. Consider running again after more code is written." Still generate any conventions found — even 1-2 patterns add value.

Note: The confidence field (high/medium/low) is a transient signal for identification and tier classification. It is NOT persisted in generated pattern files. Low-confidence candidates are dropped; high/medium determine the tier for remote-mode PR separation.

Read: references/identify-conventions-with-dedup-against-hub.md for detailed step 3: identify conventions (with dedup against hub) reference material.

STEP 4: Read Evidence and Confirm

For each remaining candidate convention, read the source files listed in "evidence needed."

  1. Read the files using Read — deduplicate across conventions (if two conventions need the same file, you already have it in context). Deep scan (default): Read ALL evidence files needed to confirm conventions. Do NOT cap at an arbitrary number. If total evidence files exceed 15, delegate overflow to subagents to manage context — but NEVER skip evidence files entirely.

    Subagent delegation (when evidence files > 15): Split conventions into groups of 5-8. For each group, launch a subagent with: "Read [file list]. For each convention hypothesis [list], report: confirmed/rejected/refined, key finding (1 line), counter-evidence count." Merge results before presenting the evidence report.

  2. For each convention, confirm or reject:
    • Confirmed — the convention holds across the evidence files with no major counter-examples
    • Rejected — the evidence is inconsistent, or the convention is weaker than hypothesized
    • Refined — the convention exists but needs to be stated differently than hypothesized
  3. Note any counter-evidence — files that deviate from the convention. If more than 30% of evidence files deviate, reject the convention
  4. Assess sensitivity — scan for keywords: auth, secret, token, credential, billing, payment, session, encryption, API key, password, private key. Flag patterns containing these for the user to decide on private: true.

Drop rejected conventions. Refine any that need it.

Present evidence results

Print the confirmation report:

Evidence Review ([N] conventions investigated):

CONFIRMED ([N]):
| # | Name | Type | Evidence files read | Key finding |
|---|------|------|--------------------:|-------------|
| 1 | ... | rule | 5 | [1-line summary of what was confirmed] |
| 2 | ... | skill | 3 | [1-line summary] |

REFINED ([N]):
| # | Name | Original hypothesis → Refined to |
|---|------|-----------------------------------|
| 1 | ... | [was X] → [now Y because Z] |

REJECTED ([N]):
| # | Name | Reason |
|---|------|--------|
| 1 | ... | [counter-evidence in N/M files] |

SENSITIVE ([N] — will ask before marking private):
- [name]: mentions [keyword], may contain [concern]

Proceeding to generate [N] patterns ([N] rules, [N] skills, [N] agents).

Wait for user acknowledgment before proceeding to Step 5. This is the last checkpoint before pattern generation begins.

STEP 5: Load Reference Material

Before generating patterns, load the format standards and examples that guide generation quality.

  1. Read the pattern structure standards (these define required format):
    • core/.claude/rules/pattern-structure.md (or the project's local copy if it exists)
    • core/.claude/rules/pattern-portability.md
    • core/.claude/rules/pattern-self-containment.md
    • core/.claude/rules/rule-writing-meta.md (RFC 2119 language guidance for rules)
  2. Read 2-3 existing patterns from core/.claude/ as format examples matching the project's stack:

    • Python: rules/testing.md, skills/pytest-dev/SKILL.md
    • TypeScript/Node: rules/testing.md, skills/vitest-dev/SKILL.md
    • Android: rules/android.md, skills/android-arch/SKILL.md
    • Fallback: rules/pattern-structure.md, any skill with synthesized: false

    If hub patterns were copied in Step 1, read from the project's own .claude/ instead.

If the hub patterns are not available locally (project was not bootstrapped from the hub), skip this step and use the format requirements embedded in Step 6 below.

STEP 6: Generate Patterns

For each confirmed convention, generate a complete pattern file.

For rules (always-on constraints):

---
description: >
  [1-2 sentence description of what this rule enforces and why]
globs: ["**/*.py", "**/*.ts"]  # Scope to relevant file types
synthesized: true
private: false  # Set to true if sensitive (auth, billing, secrets)
---

# [Convention Name]

[Body: what the convention is, why it matters, what to do and not do.
Include concrete examples from the project's actual code patterns.
Use MUST/MUST NOT for critical constraints.]

For skills (on-demand workflows):

---
name: [kebab-case-name]
description: >
  [1-3 sentences starting with a verb]
type: workflow
allowed-tools: "[minimal tool set]"
argument-hint: "[required-arg] [--optional-flag]"
version: "1.0.0"
synthesized: true
private: false  # Set to true if pattern mentions auth/secrets/billing
---

# [Skill Title]

## STEP 1: [Verb Phrase]
[numbered instructions with concrete file paths and commands from THIS project]

## STEP 2: [Verb Phrase]
[numbered instructions]

## CRITICAL RULES
- [constraint 1]
- [constraint 2]

Skills MUST encode project-specific multi-step procedures. Each step should reference actual file paths, commands, or patterns from the codebase. Generic workflow skills (e.g., "run tests") add no value — the skill must capture the project-specific gotchas, ordering, and coordination.

For agents (delegated review/analysis tasks):

---
name: [agent-name]
description: >
  When and why to use this agent. [1-3 sentences]
tools: ["Read", "Grep", "Glob"]  # JSON array, least-privilege
model: inherit
color: blue  # red|orange|yellow|blue|green — adjust based on agent severity
synthesized: true
private: false  # Set to true if pattern mentions auth/secrets/billing
---

# [Agent Title]

## Core Responsibilities
- [what this agent analyzes or reviews]
- [what domain knowledge it applies]

## Input
[what to pass to this agent]

## Output Format
[structured output: checklist, report, verdict]

## Decision Criteria
[project-specific rules this agent applies]

Agents MUST have a clear domain focus specific to this project. A generic "code reviewer" agent adds no value — an agent that reviews meal generation output for dietary constraint violations does.

Quality checks for each generated pattern:

Structure (pattern-structure.md):

  • Does version field exist and follow SemVer format (e.g., "1.0.0")?
  • For skills: does it have name, description, type, allowed-tools, argument-hint, version?
  • For skills: does it have a ## CRITICAL RULES section at the end?
  • For agents: does frontmatter include tools as a JSON array (e.g., ["Read", "Grep", "Glob"])?
  • For agents: does body include ## Core Responsibilities and ## Output Format sections?
  • For agents: does frontmatter include color field with a valid value (red|orange|yellow|blue|green)?
  • For rules: does it have globs: in frontmatter OR # Scope: global in first 5 lines?

Portability (pattern-portability.md):

  • Is it specific to THIS project (not generic advice)?
  • Are allowed-tools least-privilege (read-only skills don't include Write/Edit/Bash)?
  • Are project-specific file paths used as concrete examples (good) not as hardcoded assumptions (bad)?

Self-containment (pattern-self-containment.md):

  • Does it contain at least 30 lines of actual content (not a stub)?
  • Is it under 500 lines? If 500-1000, consider splitting. Over 1000 = must split.
  • No placeholder markers (<!-- TODO -->, <!-- FIXME -->)?
  • If it references another skill by name, does that skill exist in the project's .claude/?

Language (rule-writing-meta.md):

  • Does it use RFC 2119 language (MUST, MUST NOT, NEVER) for critical constraints?
  • For rules: does it provide alternatives, not just prohibitions?

Sensitivity flagging:

Scan each generated pattern for keywords: auth, secret, token, credential, billing, payment, session, encryption, API key, password, private key. If found, flag the pattern and ask the user whether to mark it private: true. Do not auto-flag silently — the user may intend for auth-related patterns to be shareable.

STEP 7: Validate and Write

  1. If --dry-run mode: Print each generated pattern with its target path and stop. Do not write any files.
  2. Validate — For each generated pattern, write it to a temp file and run validators:
    # Structural validation (required)
    PYTHONPATH=. python scripts/workflow_quality_gate_validate_patterns.py [temp-pattern-file]
    
    # Dedup check against existing patterns (required)
    PYTHONPATH=. python scripts/dedup_check.py --check [temp-pattern-file]
    If workflow_quality_gate_validate_patterns.py or dedup_check.py are not available (running outside the hub repo), perform manual validation against the quality checks above. Drop any pattern that fails.

Read: references/validate-and-write.md for detailed step 7: validate and write reference material.

STEP 8: Generate synthesis-config.yml

Skip this step if: --skip-synthesis is set (no synthesized patterns to configure).

Generate synthesis-config.yml if it doesn't exist — create with sharing OFF:

# .claude/synthesis-config.yml
#
# Synthesize Flywheel — consent configuration
#
# Sharing is bilateral: turn it ON to both contribute your synthesized
# patterns to the hub AND receive new/improved patterns from the hub.
# Turn it OFF (default) to keep everything local — synthesis still works,
# but you won't receive hub updates.
#
# You can change this at any time. Changes take effect on the next scan cycle.

allow_hub_sharing: false

# Patterns listed here are NEVER shared, even when allow_hub_sharing is true.
private_patterns: []

# Project-specific details to strip from patterns before they leave.
# Note: stripping is planned but not yet implemented in the hub scan pipeline.
strip_before_sharing:
  - file_paths
  - class_names
  - env_vars

# Set to true to receive a .claude/scan-log.yml with full scan history.
scan_log: false

If synthesis-config.yml already exists: Do not overwrite it. Respect existing consent settings.

STEP 9: Summary

Read: references/summary.md for detailed step 9: summary reference material.

CRITICAL RULES

  • NEVER write synthesized patterns to core/.claude/. That is the hub's distributable template. This skill writes ONLY to the TARGET PROJECT's .claude/ (local mode) or creates a PR on the TARGET REPO (remote mode). If you find yourself writing to core/.claude/, you are doing it wrong — STOP immediately.
  • NEVER generate generic best-practice patterns. Every pattern MUST reference specific conventions observed in THIS project's code. "Use consistent error handling" is useless. "All endpoints in src/api/ must return through the ApiResult[T] wrapper" is useful.
  • NEVER write patterns with confidence: low. Drop them. A wrong pattern actively harms — it teaches Claude Code incorrect conventions.
  • NEVER overwrite synthesis-config.yml if it already exists. The user's consent settings are sacred.
  • In local mode, this skill runs entirely in-session with no network requests (except for recommend.py which reads the hub registry locally). In remote mode (--repo), it fetches files from GitHub via gh api and creates a PR.
  • If --update mode finds stale patterns, do NOT delete them automatically. Write them to the summary as "candidates for removal" and let the developer decide.
  • Mark patterns as private: true if they mention auth, secret, token, credential, billing, payment, session, encryption, API key, password, private key, or similar sensitive topics. When in doubt, mark private.
  • Each generated pattern MUST have at least 30 lines of actual content. No stubs.
  • NEVER cap, limit, or prioritize a subset of confirmed conventions. Generate ALL of them. Do NOT pick "top 10" or defer to a follow-up run. The user expects complete, exhaustive coverage.
  • ALWAYS create SEPARATE PRs for each tier (must-have, nice-to-have, enhanced) in remote mode. NEVER combine tiers into a single PR. NEVER skip a tier that has patterns. NEVER make arbitrary decisions about which resources to include or exclude from a PR.
  • ALWAYS perform deep scan — read ALL evidence files needed to confirm conventions. Do NOT limit evidence reads to an arbitrary budget. If more than 15 files are needed, delegate to subagents, but NEVER skip evidence.
  • When deduping against hub patterns in Step 3, err on the side of KEEPING the project-specific convention. Only drop it if the hub pattern genuinely covers the same ground. A project-specific pattern that adds even small value over the hub pattern is worth keeping.

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.