Skip to content
Back to search

project-init

SkillWorks with Claude CodeGitHub

Set up senior-level engineering standards for a software project, new or existing. Detects the stack and current conventions, asks a few questions about stage, data, growth and regulation, then writes a short CLAUDE.md, topic rules in .claude/rules/, on-demand standards docs, ADRs, a proposed .claude/settings.json and (for existing projects) a milestone-based adoption plan, chosen from a curated catalogue of 175+ best practices (architecture, APIs, data, distributed systems, multi-tenancy, security, GDPR and EU regulation, testing, CI/CD, AI/LLM, open source, Claude Code). Use this whenever the user runs /project-init, starts or bootstraps a new project or repo, asks to set up CLAUDE.md or project rules, wants best practices or engineering standards applied to a codebase, or asks to audit an existing repo against best practices, even if they don't name the skill. Not for answering a single best-practice question in conversation.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/io-sar--project-init/badge.svg)](/listings/io-sar--project-init)

HTML

<a href="/listings/io-sar--project-init"><img src="/api/listings/io-sar--project-init/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Clone the repository into your personal Claude Code skills folder, so it is available in every project.

**Windows (PowerShell)**

git clone https://github.com/io-sar/project-init "$HOME\.claude\skills\project-init"

**macOS / Linux**

git clone https://github.com/io-sar/project-init ~/.claude/skills/project-init

Restart Claude Code, type `/` and check that **project-init** appears.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 114 lines
  1. ---
  2. name: project-init
  3. description: Set up senior-level engineering standards for a software project, new or existing. Detects the stack and current conventions, asks a few questions about stage, data, growth and regulation, then writes a short CLAUDE.md, topic rules in .claude/rules/, on-demand standards docs, ADRs, a proposed .claude/settings.json and (for existing projects) a milestone-based adoption plan, chosen from a curated catalogue of 175+ best practices (architecture, APIs, data, distributed systems, multi-tenancy, security, GDPR and EU regulation, testing, CI/CD, AI/LLM, open source, Claude Code). Use this whenever the user runs /project-init, starts or bootstraps a new project or repo, asks to set up CLAUDE.md or project rules, wants best practices or engineering standards applied to a codebase, or asks to audit an existing repo against best practices, even if they don't name the skill. Not for answering a single best-practice question in conversation.
  4. ---
  5. # Project init · v0.10.1
  6. Turn a catalogue of senior engineering practices into standards that fit THIS project: only what applies, with trade-offs resolved and recorded, written where Claude Code will follow them, and loaded only when they are needed.
  7. ## Ground rules, and why
  8. 1. **Write documentation and configuration only; never change application code.** Standards are adopted gradually through reviewed changes; a setup tool that rewrites code produces huge, unreviewable diffs and breaks trust.
  9. 2. **Always ask about data sensitivity and regulation; never infer them.** A wrong guess either misses legal obligations or buries a simple project in compliance work.
  10. 3. **Show before you write, and get a yes.** Existing files may hold deliberate decisions; the user decides what changes.
  11. 4. **Label every comparison CURRENT, PROPOSED and RESULT** (never "old/new"). Fixed labels remove any doubt about which side is which.
  12. 5. **Keep what loads every session small.** Everything in CLAUDE.md and in rule files without `paths:` is loaded at the start of every session; the more there is, the less reliably each rule is followed. Put detail on demand and scope rules to folders.
  13. ## Modes
  14. - **Normal**: all steps; writes files after confirmation.
  15. - **Dry run** (the user says "dry run" or asks to preview): all steps, but write nothing anywhere, including this skill's `feedback/` folder, and skip the write confirmation. Show CLAUDE.md, rule files, settings.json, ADRs and the adoption plan in full; show `docs/standards/*` as headings plus one sample section unless the user asks for all.
  16. - **Upgrade**: if CLAUDE.md contains `project-init:start`, this is an upgrade. Load the saved profile from `docs/standards/profile.md`; for projects set up before v0.10, rebuild it from the CLAUDE.md profile line, the ADRs and `docs/standards/`, and say which values were rebuilt. Run detection (Step 1) to spot changes. In Step 2 ask **only** about dimensions that are missing from the saved profile (e.g. added in a newer skill version), that detection shows have changed, or that were left open; never repeat answered questions, even the ones marked "always asked". Then show the full profile once (Step 3) with a single question: "Anything changed?". Steps 4 to 7 then propose only the differences, as CURRENT / PROPOSED / RESULT. Use it when the project reaches a new stage or milestone, or after installing a new skill version.
  17. ## Files in this skill
  18. | File | Read it in |
  19. |---|---|
  20. | `profile.md` | all steps: dimensions, tag syntax, practice fields |
  21. | `detection.md` | Step 1 |
  22. | `questions.md` | Steps 2 and 3 (in upgrade mode, only for missing, changed or open dimensions) |
  23. | `practices/TAGS.md`, then the selected practices in `practices/NN-*.md` | Steps 4 and 5 (the catalogue) |
  24. | `guides/principle-tensions.md` | Step 4, resolving `alternatives:` |
  25. | `guides/architecture-styles.md` | Step 4 and ADR 0002 (quality attributes, style, tenancy, gateway) |
  26. | `guides/branching.md`, `repo-strategy.md`, `database-selection.md`, `testing-strategy.md`, `tool-selection.md`, `llm-evaluation.md` | Step 4 when a selected practice points to them, and Step 6 for ADRs and standards docs |
  27. | `templates/*.tmpl` | Step 6 |
  28. `README.md`, `LICENSE`, `TESTING.md`, `MAINTENANCE.md`, `ROADMAP.md`, `PROPOSALS.md`, `CHANGELOG.md`, `tools/` and `feedback/` are for the repository and for maintaining the skill; you do not need them during a run.
  29. ## Step 1 · Detect
  30. Follow `detection.md`. Record every detected value with its evidence (file path), because the user confirms the profile from that evidence in Step 3. Never open `.env` or key files. In an existing project, also collect existing conventions with file and line (Step 5 compares against them), and note any existing CLAUDE.md, AGENTS.md, `.claude/rules/` and `.claude/settings.json`.
  31. ## Step 2 · Ask
  32. Follow `questions.md`: Round 1 (4 questions, always), Round 2 (up to 4, skipping what was detected), and the single follow-up only when its condition is met. Stay within the question tool's limits so no option is silently dropped.
  33. ## Step 3 · Confirm
  34. Show the confirmation screen from `questions.md`, including how many practices the profile selects. Continue only after the user confirms or corrects it; everything downstream depends on this profile.
  35. ## Step 4 · Select
  36. 1. Read `practices/TAGS.md` (one line per practice: ID, title, applies tag, flags) and evaluate every tag against the profile. Then read only the selected practices in the group files; skip groups with no selected practice. Practices with `opt-in: yes` are only suggested in the summary.
  37. 2. Resolve every practice with `alternatives:` using `guides/principle-tensions.md` in its stated order (auto tensions resolved from the profile; advisory tensions get the default and are listed for the user). A practice with `alternatives:` but no row in the tensions table is advisory: write the practice's own rule and list the alternative in the summary. Write only the chosen side; both sides would give contradictory instructions.
  38. 3. Keep a list of practices skipped only because of `stage`: the upgrade path.
  39. ## Step 5 · Gap analysis (existing projects only)
  40. Give each selected practice one status, comparing with the conventions from Step 1:
  41. - **enforced**: a tool, CI step or test checks it
  42. - **documented only**: written somewhere, nothing checks it
  43. - **missing**: not found
  44. - **conflicting**: the project does it differently
  45. Present conflicts so each decision is easy:
  46. - **Security (08) and privacy (09) conflicts: one at a time**, marked HIGH PRIORITY, each needing an explicit choice, because silently keeping a weak rule there can cause real harm.
  47. - **All other conflicts: one table**, with KEEP CURRENT pre-selected; the user changes only the rows they want.
  48. ```
  49. Conflict 2 of 3 (HIGH PRIORITY) · Security · Secrets management
  50. | Label | Rule text | Where it comes from |
  51. |------------------------------------------------|------------------------------------|---------------------|
  52. | CURRENT (in your project today) | "Store API keys in config.yaml" | README.md, line 40 |
  53. | PROPOSED (from the catalogue, not yet applied) | "Secrets only from a secret manager or env; never in committed files" | catalogue 08.1 |
  54. Impact if replaced: <one line>
  55. Recommendation: REPLACE WITH PROPOSED, because <one line>
  56. Your choice: [K] keep CURRENT · [R] replace with PROPOSED · [M] merge
  57. ```
  58. On [M], add a row `RESULT (what will be written)` and ask for confirmation. After all conflicts, show one summary table: ID · CURRENT · RESULT · decision. The default is KEEP CURRENT: an existing convention is often a deliberate choice, and consistency inside a codebase matters more than a marginally better rule.
  59. - **KEEP CURRENT** writes nothing new: the existing rule stays where it is, and the decision is recorded in `docs/standards/`. Never repeat a rule that already exists outside the generated block.
  60. - **REPLACE or MERGE of a line outside the project-init markers** (e.g. in a hand-written CLAUDE.md) is the only edit allowed outside the markers: show exactly that line as CURRENT / RESULT and change it only after an explicit yes.
  61. Map statuses for Step 6:
  62. - enforced, or a REPLACE/MERGE decision → **Enforced** (rule files); KEEP CURRENT → nothing new written
  63. - documented only, or missing but cheap to apply to new code → **Adopting** (rule files: new code follows it, existing code keeps its local pattern)
  64. - missing and needing real work on existing code → **planned**, assigned to a milestone in the adoption plan (never in rule files)
  65. In a new project every selected rule is **Enforced**.
  66. ## Step 6 · Write
  67. First list every file that will be created or changed and get a yes (skip this in dry run). For any file that already exists, show CURRENT vs RESULT before writing it. Template comments are instructions for you: strip them from written files, except the project-init markers and the one-line "Generated by" note, so no catalogue IDs or skill wording end up in the project.
  68. **Three loading tiers.** Decide for each selected practice where it lives:
  69. 1. **Always loaded** (CLAUDE.md and rule files without `paths:`): the non-negotiables and rules that apply to any file.
  70. 2. **Loaded by path** (rule files with `paths:`): add `paths:` for groups 03, 05, 06, 13 and 14 whenever their code can be located (tests, API, models/migrations, UI, AI code). With a flat layout, scope to the specific files that clearly hold that code (e.g. `app.py`, `db.py`); if none can be identified, load the rule always and count it against the budget.
  71. 3. **On demand** (`docs/standards/<group>.md`): the full rule, reason and resolved trade-off for every selected practice of the group; CLAUDE.md says when to read each file.
  72. **Budget.** The generated CLAUDE.md block stays under 120 lines and the whole CLAUDE.md under 200 lines (warn the user above that); all always-loaded rule files together stay under 250 lines. Write one short line per rule; add a reason only where it is not obvious. If the budget is exceeded, keep in rule files the security, privacy and testing rules and the ones that change Claude's day-to-day coding; move the rest to `docs/standards/` only.
  73. **Rule text hygiene.** Rule files and CLAUDE.md must stand on their own in the project: no catalogue IDs, no links to this skill's guides, no `alternatives` or `choose-when` text, no references to practices that were not selected. Write each resolved trade-off as one plain sentence.
  74. **No repeats.** Before writing a rule, check the project's existing instructions (CLAUDE.md outside the markers, AGENTS.md, existing rule files, CONTRIBUTING.md) for a rule with the same intent. If one exists, do not write it again; if the catalogue rule adds something, write only the addition, phrased as extending the existing rule. Judge by meaning, not by heading names: a "Code design" section can cover structure, a "Rules that must not break" section can cover secrets.
  75. Files:
  76. 1. `CLAUDE.md` from `templates/CLAUDE.md.tmpl`. New file: the full block. Existing file without markers: append the block at the end, headed `## Project standards`, and leave out every section whose content the file already covers, judged by meaning rather than heading (title, description, commands, structure or code layout, workflow); preserve everything else exactly, including notes and roadmaps. Existing file with markers: update only inside them. If AGENTS.md exists, import it (`@AGENTS.md`) rather than duplicating it. Non-negotiables (max 8) live only here.
  77. 2. `.claude/rules/<group>.md` from `templates/rule-file.md.tmpl`, named after the group file without its number (e.g. `security.md`), Enforced and Adopting rules only.
  78. 3. `docs/standards/<group>.md` from `templates/standard-doc.md.tmpl`, one per group with selected practices.
  79. 4. `.claude/settings.json` proposal from `templates/settings.json.tmpl` for practices with `kind: setup` (15.3, 15.4) and the autonomy model (15.10): deny reading secret files and force pushes (best effort), ask for destructive git and gh commands, merges, releases, repository settings and paid scripts, keep allow rules narrow, allow each routine command both bare and with arguments (`Bash(cmd)` and `Bash(cmd *)`), and a formatter hook only if the repository is already formatted (otherwise the first edit would reformat whole files; list "format the codebase" as a planned item instead). Deny the real secret files by name but keep `.env.example` readable, since it documents the variables without values. If Claude Code's sandbox is not available (e.g. native Windows), also propose the optional PreToolUse hook that blocks shell commands mentioning secret files; say that it matches text (so a command that only mentions the name is blocked too), can be bypassed with globs or split strings, and fails open if its interpreter breaks. Test it with sample commands before reporting, without touching real secret files. Merge with any existing settings as CURRENT / RESULT; never remove existing entries without asking.
  80. 5. `docs/adr/` from `templates/adr.md.tmpl`: if the folder exists, continue its numbering and format; otherwise start with 0001 (record architecture decisions). Then: quality attributes and architecture style (new projects), one per resolved tension that matters here, one per REPLACE decision (existing projects). If a decision is already documented elsewhere in the project (CLAUDE.md, a spec, an existing ADR, the README), do not write a new ADR: link to the existing record in `docs/standards/` and propose an ADR only if that record lacks the reasoning.
  81. 6. `docs/standards/profile.md` from `templates/profile.md.tmpl`: every dimension with its value, source (answered, detected with evidence, or default) and date; open questions; confirmed milestones. Upgrade mode reads it, so answered questions are never asked twice.
  82. 7. `docs/standards-adoption.md` from `templates/standards-adoption.md.tmpl` (existing projects): planned items grouped by milestone, security and privacy first, plus the upgrade path. Use only current or future milestones the user confirmed in Step 3 (never a milestone that is already done); if the project has none, propose M1/M2/next stage.
  83. ## Step 7 · Summarise
  84. Report, in this order:
  85. 1. Files written (or, in dry run, files that would be written) and the line counts of CLAUDE.md and the rule files against the budget.
  86. 2. Practices selected per group, and which tier each group went to.
  87. 3. Existing projects: enforced / adopting / planned counts and the items of the first milestone.
  88. 4. Opt-in suggestions, advisory tensions left at their default, regulations marked "not sure", and the upgrade path. If the repository is hosted on GitHub or a similar platform, recommend server-side branch protection for the main and integration branches (a repository setting: the user decides). Note that permission deny rules are best effort (e.g. `cat .env` through the shell is not a Read call) and recommend Claude Code's sandbox for stronger isolation.
  89. 5. Open questions (e.g. regulation "not sure") and commands left as TODO.
  90. 6. Overrides, for improving the skill: one line per user override (rejected practice, KEEP CURRENT, overridden tension) as `date · ID · chosen instead · reason`, with no project names, paths or personal data. Show these lines; append them to `feedback/overrides.md` in this skill's folder only if the user says yes, the folder is writable and this is not a dry run.
README.md · README · 74 lines
  1. # project-init
  2. A [Claude Code](https://code.claude.com) skill that sets up senior-level engineering standards for a software project, new or existing, and keeps them up to date.
  3. It looks at the repository, asks a few short questions (stage, data, growth, regulation, hosting), and picks the practices that fit **this** project from a catalogue of 180+ language-agnostic best practices. It then writes them where Claude Code follows them, loading each rule only when it is needed.
  4. **Status:** pre-1.0 (see [ROADMAP.md](ROADMAP.md)). Tested on a real existing project; feedback welcome.
  5. ## What it does
  6. - **Detects** the stack, hosting, tests, CI, existing conventions and milestones from the repository.
  7. - **Asks** only what it cannot detect: one or two short rounds of multiple-choice questions.
  8. - **Selects** practices by profile: a solo prototype gets a light setup, while a multi-tenant production platform with personal data gets architecture, security, GDPR and operations rules. Trade-offs such as SOLID vs YAGNI, Gitflow vs trunk-based, or monolith vs microservices are resolved from the profile and recorded as decisions (ADRs).
  9. - **Respects existing projects:** it never changes application code, keeps your CLAUDE.md content, shows every conflict as CURRENT / PROPOSED / RESULT, and plans the rest by milestone instead of refactoring.
  10. - **Writes, after your approval:**
  11. - a short generated block in `CLAUDE.md`
  12. - `.claude/rules/*.md` (a few always loaded, the rest only for matching folders)
  13. - `docs/standards/*.md` (full reasons, read on demand) and `docs/standards/profile.md`
  14. - a proposed `.claude/settings.json` (blocks secret files and force pushes, asks before destructive or paid actions)
  15. - ADRs in `docs/adr/`, and for existing projects `docs/standards-adoption.md`
  16. The catalogue covers foundations, code quality, testing (including negative, boundary, failure-path and exploratory testing), architecture, APIs, data, distributed systems, security, EU privacy and regulation (GDPR, NIS2, AI Act, CRA, EAA), operations, CI/CD, performance and cost, frontend, AI/LLM features, working with Claude Code (including agent autonomy), ways of working, and open-source maintenance.
  17. ## Install
  18. Clone the repository into your personal Claude Code skills folder, so it is available in every project.
  19. **Windows (PowerShell)**
  20. ```powershell
  21. git clone https://github.com/io-sar/project-init "$HOME\.claude\skills\project-init"
  22. ```
  23. **macOS / Linux**
  24. ```bash
  25. git clone https://github.com/io-sar/project-init ~/.claude/skills/project-init
  26. ```
  27. Restart Claude Code, type `/` and check that **project-init** appears.
  28. ## Update
  29. ```powershell
  30. git -C "$HOME\.claude\skills\project-init" pull
  31. ```
  32. Then restart Claude Code, and run upgrade mode in your projects (see below).
  33. ## Use
  34. In Claude Code, inside your project:
  35. | Goal | Prompt |
  36. |---|---|
  37. | Preview without writing anything | `Run /project-init in DRY-RUN mode.` |
  38. | Set up standards | `/project-init` |
  39. | Update an existing setup after a new version or a new milestone | `Run /project-init in upgrade mode. Propose only the differences. Don't write anything until I approve.` |
  40. Tip: try it first in a separate git worktree or branch, and review the result like a pull request.
  41. ## Repository layout
  42. | Path | What it is |
  43. |---|---|
  44. | `SKILL.md` | The workflow Claude follows |
  45. | `profile.md`, `questions.md`, `detection.md` | Project profile, questions and detection rules |
  46. | `practices/` | The catalogue: one file per group, plus a generated index (`TAGS.md`, `INDEX.md`) |
  47. | `guides/` | Decision guides: trade-offs, architecture styles, testing, databases, repos, branching, tools, LLM evaluation |
  48. | `templates/` | Templates for the files the skill writes |
  49. | `evals/`, `TESTING.md` | Test cases and prompts for evaluating the skill |
  50. | `tools/` | `validate_catalogue.py` (checks every rule) and `build_handbook.py` (one readable PDF/HTML handbook) |
  51. | `ROADMAP.md`, `PROPOSALS.md`, `CHANGELOG.md`, `MAINTENANCE.md` | Status, ideas inbox, history and how the catalogue stays current |
  52. ## Contributing
  53. Issues with proposals, corrections or real-run findings are welcome. For a new or changed practice, include the rule, why it matters, when it should apply, and a source. Run `python3 tools/validate_catalogue.py` before opening a pull request.
  54. ## Disclaimer
  55. The privacy and regulation practices are engineering guidance, not legal advice.
  56. ## Licence
  57. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.