agentleFS
tjst-ttjst-t/claude-skills/skills/project-init/SKILL.md

project-init

Skill0 starsChanged 4 months agoMITView on GitHub

Generates CLAUDE.md, docs/ARCHITECTURE.md, and Makefile for mid-to-large projects. Sets up standardized project documentation and development environment with progressive disclosure.

43 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use harness-audit, workflow and 3 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • sattva2020Skill

    harness-audit

    Audits a codebase for "AI-agent harness" maturity across six layers (context engineering, tools & MCP, memory & state, tests & evals, observability, guardrails & approvals). Scores each layer, flags AGENTS.md/CLAUDE.md drift, gives prioritized fixes. Use for "audit harness", "оцени харнес", "check agent readiness", "is this project agent-ready", "проверь готовность к AI-агентам".

    Also in 3 projects that use this

  • VercelSkill

    workflow

    Creates durable, resumable workflows using Vercel's Workflow SDK. Use when building workflows that need to survive restarts, pause for external events, retry on failure, or coordinate multi-step operations over time. Triggers on mentions of "workflow", "durable functions", "resumable", "workflow sdk", "queue", "event", "push", "subscribe", or step-based orchestration.

    Also in 3 projects that use this

  • MicrosoftSkill

    release

    Use ONLY when the user explicitly asks to cut/publish a Huabu desktop release or tag a version. Performs an outward action — bumps the version in apps/desktop/package.json, commits + annotated-tags vX.Y.Z, and pushes the branch + tag. That tag push auto-builds the macOS/Windows installers and publishes a GitHub Release. Provides `status`, `bump`, `tag-push`, and a one-command `run` (bump → tag-push).

    Also in 4 projects that use this

  • MicrosoftSkill

    handoff

    Compact the current conversation into a handoff document for another agent to pick up.

    Also in 3 projects that use this

  • GoogleSkill

    code-review

    Adversarial systems, concurrency, memory-model, and architecture code review protocol. Use this skill whenever asked to review code, PRs, diffs, or branches in Filament.

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

9 rules. 0 are common, 3 are distinctive, and 6 are very specific to this project.

  • 0

    Common

    Most of the 22 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 6

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read the project's source code, configs, and existing documentation to understand:

    line 23
  2. Very specific:

    If docs/ARCHITECTURE.md already exists, ask the user whether to overwrite, merge, or skip.

    line 35
  3. Very specific:

    If docs/DESIGN/system.json exists, also reference it — it describes the *intended* architecture, while ARCHITECTURE.md captures what the …

    line 37
  4. Very specific:

    Create or update CLAUDE.md following references/CLAUDE_TEMPLATE.md.

    line 41
  5. Very specific:

    Only if the project has a web server, API, or dev server.

    line 47
  6. Distinctive:

    If the project has no server component, skip this step.

    line 49
  7. Very specific:

    If docs/ROADMAP.json already exists, skip.

    line 53
  8. Very specific:

    When called from autopilot setup, roadmap content generation is handled separately by sprint roadmap after project-init completes.

    line 55
  9. Distinctive:

    portman is opt-in: If unavailable and the user skips, fall back to a basic Makefile target — never block the project setup on a missing …

    line 81

“Common” is measured: kept by at least 6 in 10 of the 22 edited versions of this file we could read. “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

Project Init

Sets up standardized project documentation and development environment. Run at the root of a project — new or existing.

What gets produced

  1. CLAUDE.md — Layer 1, always-in-context project overview, under ~100 lines (template at references/CLAUDE_TEMPLATE.md)
  2. docs/ARCHITECTURE.md — Layer 2, on-demand system design (template at references/ARCHITECTURE_TEMPLATE.md)
  3. Makefile — make serve / make stop targets using portman if applicable (details at references/portman-integration.md). Also include a test (and/or verify) target — sprint verify's machine verdict (run-verify.py) falls back to make verify/make test, so this gives the project deterministic, machine-derived test status for free. For per-AC granularity, have that target emit JUnit XML and declare it in .claude/verify.json (see sprint/references/verify-execution.md).
  4. docs/ROADMAP.json — blank template via sprint init (or skipped if it already exists)

Command — project init

1. Scan

Read the project's source code, configs, and existing documentation to understand:

  • Language and framework (go.mod, package.json, Cargo.toml, pyproject.toml, etc.)
  • Project structure (directory layout, entry points)
  • Existing CLAUDE.md, README, docs/ contents
  • Existing Makefile targets
  • Whether the project has a web server or API (→ portman integration applies)

2. Generate docs/ARCHITECTURE.md

Read the source code and generate an architecture document following references/ARCHITECTURE_TEMPLATE.md. Focus on: what the major components are and how they relate, where the entry points are, how data flows through the system. The goal is for Claude Code to understand the system without reading every source file.

If docs/ARCHITECTURE.md already exists, ask the user whether to overwrite, merge, or skip. This is a scope decision, not a routine auto-decision.

If docs/DESIGN/system.json exists, also reference it — it describes the intended architecture, while ARCHITECTURE.md captures what the code currently looks like.

3. Generate or update CLAUDE.md

Create or update CLAUDE.md following references/CLAUDE_TEMPLATE.md. Always read the template first — it defines the required structure including the References section with pointers to all Layer 2 docs.

If CLAUDE.md already exists, merge, don't replace: reorganize existing content into the template structure rather than discarding it. Every piece of information must either appear in the updated version or be explicitly flagged to the user for a decision. Show the user a diff or summary of what changed before writing the file.

4. Integrate portman (if applicable)

Only if the project has a web server, API, or dev server. See references/portman-integration.md for the full procedure (prerequisites check, pattern selection, Makefile targets, CLAUDE.md updates, .gitignore).

If the project has no server component, skip this step.

5. Initialize roadmap

If docs/ROADMAP.json already exists, skip. Otherwise, call sprint init from the sprint skill to set up a blank template. If the sprint skill is not available, create a blank docs/ROADMAP.json manually.

When called from autopilot setup, roadmap content generation is handled separately by sprint roadmap after project-init completes. project-init only creates the blank template if needed.

6. Summary

Present to the user: files created or modified, project structure that was set up, any manual steps still needed (e.g., installing portman).

Document Hierarchy

{project-root}/
├── CLAUDE.md                    # Layer 1: Always in context. Minimal.
└── docs/
    ├── ARCHITECTURE.md          # Layer 2: System design. Read on demand.
    ├── ROADMAP.json             # Layer 2: Sprint tracking. Managed by sprint.
    └── sprint-logs/             # Sprint execution logs. Managed by sprint.
        └── {SprintID}/

Layer 1 (CLAUDE.md) should be under ~100 lines. If it's growing beyond that, content should be moved to Layer 2 documents.

Important Behaviors

  • CLAUDE.md is Layer 1 — every line costs tokens on every interaction. Only include information Claude Code needs on EVERY task. Everything else goes in docs/ with a pointer from CLAUDE.md.
  • Merge, don't replace existing CLAUDE.md. The user has invested in their existing documentation; the goal is to reorganize it into the template structure, not to silently overwrite. Always show a diff or summary before writing.
  • Development rules belong in CLAUDE.md even though they could go in a separate doc — Claude Code needs them on every coding task.
  • Existing ARCHITECTURE.md overwrite is a scope decision, not a routine auto-decision. Always ask the user (overwrite / merge / skip).
  • portman is opt-in. If unavailable and the user skips, fall back to a basic Makefile target — never block the project setup on a missing tool.

Reference Files

  • references/CLAUDE_TEMPLATE.md — CLAUDE.md structure and format
  • references/ARCHITECTURE_TEMPLATE.md — ARCHITECTURE.md structure and format
  • references/portman-integration.md — portman prerequisites, pattern selection, Makefile targets

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.