agentleFS
AlexisBalayreAlexisBalayre/claude-code-config/.claude/skills/adapt-to-project/SKILL.md

adapt-to-project

Skill2 starsChanged 29 days agoMITView on GitHub

Fit this Claude Code template to the repository it was copied into by filling .claude/project.env, AGENTS.md, the conventions docs and their rule loaders, and the architecture, security and glossary docs, then pruning skills and agents the project cannot use.

  • Reads credentials

3 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

7 rules. About 0 are common, 2 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

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

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

    Facts come from the code; decisions come from the user: Never invent a convention, a rationale, or a security property.

    line 12
  2. Very specific:

    If the repo already had its own CLAUDE.md, AGENTS.md, .cursor/rules, CONTRIBUTING.md or style guide, those are primary sources: merge their …

    line 18
  3. Distinctive:

    Patterns: read 5-10 representative source files per area and 3-5 tests.

    line 28
  4. Very specific:

    Add the project's safe commands to permissions.allow in .claude/settings.json (e.g.

    line 40
  5. Distinctive:

    No dangling references: grep the repo for each deleted skill, agent and doc name.

    line 80
  6. Very specific:

    Every .claude/rules/*.md import target exists, and every docs/conventions/*.md has a loader.

    line 81
  7. Very specific:

    Run the quality gate for real: add a trivial edit to one source file, run CLAUDE_PROJECT_DIR="$PWD" .claude/hooks/quality-checks.sh, …

    line 83

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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

Adapt to project

The template ships stack-agnostic: every project-specific slot carries a TODO(adapt) marker, and every hook no-ops until .claude/project.env names a command. This skill turns the skeleton into this project's config. It is re-runnable: fill only what is still TODO(adapt) or what the focus argument names, and never overwrite filled content without asking.

Facts come from the code; decisions come from the user. Never invent a convention, a rationale, or a security property. What the code cannot tell you becomes a question, or stays a TODO(adapt) the report lists as deferred.

1. Inventory

  1. Confirm you are in a worktree on a feature branch (see AGENTS.md §Git workflow).
  2. List the open slots: grep -rn "TODO(adapt):" --exclude-dir=node_modules --exclude-dir=.worktrees --exclude-dir=adapt-to-project . (the colon form marks a slot; the bare form is a mention).
  3. If the repo already had its own CLAUDE.md, AGENTS.md, .cursor/rules, CONTRIBUTING.md or style guide, those are primary sources: merge their content into the template files, never discard it.

2. Survey

Delegate to an Explore subagent on a large repo so file dumps stay out of context. Establish:

  • Stack and package manager: manifests and lockfiles (package.json, pyproject.toml, go.mod, Cargo.toml, pom.xml, build.gradle, Gemfile, ...).
  • Real commands: lint, format, typecheck, test, install, dev, codegen, migrations. CI workflows and task runners (Makefile, justfile, package.json scripts) show what the team actually runs.
  • Areas: top-level layout, workspace members, and the boundaries where rules change (API, database, frontend, workers, infra).
  • Generated code: codegen configs, generated/ directories, protobuf/OpenAPI outputs.
  • Patterns: read 5-10 representative source files per area and 3-5 tests. Note naming, layering, error handling, logging and test layout that recur. A pattern the code breaks more often than it follows is not a convention; ask instead.

3. Confirm the profile

Present in one message: the detected stack, the proposed .claude/project.env values, the list of areas with their path globs, and the questions the code could not answer (code owners, whether the automated PR review is wanted, which personal-integration tools are in use). Wait for answers before writing.

4. Project profile

  1. Fill .claude/project.env and delete its TODO(adapt) line. Run every command once before writing it: LINT_CMD and FORMAT_FIX_CMD against one real source file (they receive file paths as arguments; wrap a tool that doesn't accept paths), TYPECHECK_CMD and TEST_CMD as-is. A command that fails on a clean trunk is not ready; report it rather than writing it.
  2. Set SOURCE_EXTENSIONS to the project's languages and narrow the extension glob in .claude/rules/core-conventions.md to match.
  3. GENERATED_PATHS_REGEX from the generated code found. FILE_NAMING_* only when the codebase already follows one naming rule consistently (count violations with git ls-files); otherwise leave empty.
  4. GIT_TRUNK from git symbolic-ref --short refs/remotes/origin/HEAD (strip origin/).
  5. Add the project's safe commands to permissions.allow in .claude/settings.json (e.g. Bash(<test command>*)).
  6. .github/CODEOWNERS: the owners the user named.

5. Conventions

docs/conventions/ holds obligations only; system description belongs in docs/reference/. Don't restate what the linter or formatter already enforces. Each doc is paid in tokens once per session per area, so keep each lean.

  1. core.md and testing.md: replace each TODO(adapt) section with observed rules, or delete the section when the project has nothing to say.
  2. For each area whose rules differ from core, create:
    • docs/conventions/<area>.md with the same title and genre-contract line as core.md;
    • .claude/rules/<area>-conventions.md: paths: frontmatter plus a single @docs/conventions/<area>.md import, nothing else;
    • a row in the AGENTS.md Conventions table and in .claude/rules/README.md.
  3. .claude/spot-checks.tsv: add only cheap, near-zero-false-positive structural checks for rules the linter cannot express (a forbidden import in a layer, a banned API in a directory). Each message cites its conventions section.

6. Knowledge docs

  • AGENTS.md: heading, one-paragraph description, role, extra key commands and their gotchas.
  • docs/reference/architecture.md: components, layout, request and data flow, external dependencies.
  • docs/explanation/security-model.md: from the auth middleware, secret loading and input validation code. Mark unverified properties as open questions, never as guarantees.
  • docs/glossary.md: the 5-15 domain nouns that recur across modules, defined as the code uses them.
  • docs/README.md: list the area docs you created.

7. Prune

Present a keep-or-delete table for every skill and agent, with a one-line reason each, and delete only after the user confirms. Coupled sets go together:

SetDelete when
migration-reviewer agentthe project has no database schema or migrations
CI review pipeline: .github/workflows/claude-code-review.yml, tools/review/, pr-ci-review, review-retro, the review-* agentsthe repo is not on GitHub, or the user doesn't want automated PR review
obsidian-vault + daily-notethe user doesn't use Obsidian
backfill-issuesno issue-tracker MCP (to-spec / to-tickets fall back to local files, keep them)
fix-sonar / wiz + fix-wizno SonarQube / no Wiz
prototype/UI.mdthe project has no UI (keep LOGIC.md)

Then drop the matching keys from .env.example and update every catalog: .claude/skills/README.md, .claude/agents/README.md, the counts and trees in .claude/README.md and README.md.

8. Verify

  1. The step 1 grep returns only slots the user chose to defer.
  2. No dangling references: grep the repo for each deleted skill, agent and doc name.
  3. Every .claude/rules/*.md import target exists, and every docs/conventions/*.md has a loader.
  4. bash -n .claude/hooks/*.sh scripts/*.sh, and hooks and scripts are executable.
  5. Run the quality gate for real: add a trivial edit to one source file, run CLAUDE_PROJECT_DIR="$PWD" .claude/hooks/quality-checks.sh, confirm it passes, then revert the edit.

9. Report

End with a table of what was filled, created, deleted and deferred, plus the verification results. Suggest committing the adaptation as its own PR.

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.