project-init
Skill2 starsChanged 6 months agoMITView on GitHub
Initialize AI context for an existing project — deep scan the codebase, detect tech stack, identify subprojects and major modules, generate root `AGENTS.md`, `ARCHITECTURE.md`, `TESTING.md`, and directory-scoped `AGENTS.md` files for subprojects and significant directories. Works with monorepos, polyglot projects, and large codebases via iterative scanning.
- Reads credentials
43 other projects use a version of this.
Adopted by
Most recently taken up by
- emadabdulrahim/claude-skillstheir own version, first seen Nov 16, 2026
- tjst-t/claude-skillstheir own version, first seen Nov 16, 2026
- mridun-gupta/project-init.skillstheir own version, first seen Nov 15, 2026
- veraetogrex-portfolio/solo-sddtheir own version, first seen Nov 15, 2026
- CT-masato-hino/claude-code-project-packtheir own version, first seen Nov 15, 2026
- AlexZio00/sovereign-skillstheir own version, first seen Nov 14, 2026
Used with
Projects with it also use harness-audit, workflow and 1 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.
sattva2020Skillharness-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
VercelSkillworkflow
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
MicrosoftSkillhandoff
Compact the current conversation into a handoff document for another agent to pick up.
Also in 3 projects that use this
Other versions43 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 43
- bkywksj/knowledge-base★ 340same name
- zephyrwang6/myskill★ 339same name
- AlexZio00/sovereign-skills★ 158same name
- claude-world/director-mode-lite★ 80same name
- agencia-conversion/agentic-seo-skills★ 51same name
- u9401066/pubmed-search-mcp★ 28same name
- mathruffian-dot/cross-device-agent-skills★ 27same name
- ecodelearn/template-claude-code-open★ 25same name
- peter-tu-zynkr/zynkr-skill-builder★ 21same name
- SpaceZephyr/allSkills★ 14same name
33 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository40 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- ai-skillsSkill
- analyze-localSkill
- analyze-prodSkill
- analyzeSkill
- architectureSkill
- asset-validationSkill
- blog-postSkill
- bugfixSkill
- cloud-platformsSkill
- code-reviewSkill
- content-creationSkill
- context-engineeringSkill
- create-prSkill
- deployment-proceduresSkill
- deploy-productionSkill
- deploy-stagingSkill
- docsSkill
- feature-devSkill
- geo-writerSkill
- humanizerSkill
- infra-changeSkill
- marketing-operationsSkill
- marketingSkill
- ml-pipelineSkill
- planSkill
- pre-commitSkill
- productSkill
- prompt-engineeringSkill
- qaSkill
- releaseSkill
- run-testsSkill
- security-scanSkill
- seo-reviewSkill
- social-media-managerSkill
- test-localSkill
- test-strategySkill
- ui-ux-designSkill
- worktree-isolationSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
14 rules. 0 are common, 10 are distinctive, and 4 are very specific to this project.
0
Common
Most of the 22 edited versions we read keep these.
10
Distinctive
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 67
If files exist — read them, note gaps.
- Distinctive: line 82
Import style and module organization
- Very specific: line 109
Use the matching stack-specific template from .codex/templates/ as a starting point.
- Distinctive: line 118
Keep concise — avoid repeating what scoped AGENTS.md files will cover
- Very specific: line 124
Use templates/architecture.template.md as the starting point.
- Distinctive: line 128
Document what exists now, not aspirations.
- Very specific: line 140
Create TESTING.md at the project root using templates/testing.template.md (root template section).
- Very specific: line 142
Key data sources: test config files → test types and commands.
- Distinctive: line 152
Keep service-specific — do not repeat root TESTING.md content
- Distinctive: line 223
After approval, create all files.
- Distinctive: line 225
Verify it was created successfully
- Distinctive: line 228
If updating existing files — show the diff and request confirmation.
- Distinctive: line 232
After all files are created:
- Distinctive: line 252
Precedes: All other workflows — run this first on a new project
“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.
Files
Project Init
Deep-scan an existing project and generate AI context files (AGENTS.md, ARCHITECTURE.md, TESTING.md) for the root and all significant subprojects. After completion, the runtime has the context it needs: tech stack, conventions, structure, setup, testing, security.
1. Initial Reconnaissance
1a. Root Structure Scan
// turbo
ls -la # or Get-ChildItem on WindowsIdentify stack signals:
| Signal | Indicates |
package.json, tsconfig.json | Node.js / TypeScript |
pom.xml, build.gradle | Java / Spring |
pyproject.toml, requirements.txt | Python |
go.mod | Go |
*.csproj, *.sln | .NET |
Cargo.toml | Rust |
Dockerfile, docker-compose.yml | Containerized |
terraform/, *.tf | Infrastructure as Code |
helm/, k8s/, charts/ | Kubernetes |
Multiple package.json / pom.xml | Monorepo |
nx.json, turbo.json, pnpm-workspace.yaml, lerna.json | Monorepo tooling |
content/blog/, posts/, .mdx files with frontmatter | Blog / file-based content |
llms.txt | AI search optimization |
1b. Detect Project Boundaries
Identify project boundaries — directories that are independent units:
- Monorepo:
apps/,packages/,services/,libs/with own config files - Single project: One root config, directories are modules (
src/,app/,internal/)
Build a project map:
Project Root
├── [subproject-1] (type: service, stack: Java Spring Boot)
├── [subproject-2] (type: frontend, stack: Next.js + TypeScript)
├── [subproject-3] (type: infra, stack: Terraform)
└── [shared-lib] (type: library, stack: TypeScript)1c. Check for Existing Context Files
// turbo
find . -name "AGENTS.md" -o -name "ARCHITECTURE.md" -o -name "TESTING.md" -o -name "FEATURES.md" | head -20If files exist — read them, note gaps. Create missing files, update outdated ones (with user confirmation).
2. Deep Scan — Iterative
Process one boundary at a time. Scan limits: max 10 boundaries, 20 files per boundary, 3 levels deep. For 100+ file boundaries, summarize from directory listing and configs only.
2a. Per-Boundary Scan Sequence
For each subproject or the root project:
- Config files first —
package.json,pom.xml,pyproject.toml,go.mod,*.csproj,tsconfig.json,.eslintrc,Dockerfile - Entry points —
main.ts,App.tsx,main.py,Main.java,main.go,Program.cs - Directory structure — list 2–3 levels deep to understand module organization
- Key patterns — read 1–2 representative files from each major directory to understand conventions:
- Naming patterns (files, classes, functions)
- Import style and module organization
- Error handling patterns
- Testing patterns (find test files)
- CI/CD —
.github/workflows/,Jenkinsfile,.gitlab-ci.yml,cloudbuild.yaml - Docs —
README.md,docs/,CONTRIBUTING.md - Content — two patterns to detect:
- Static content files —
static-content/,data/dirs with TS/JS exports. Map content file → sections → consuming pages - File-based content (blog/docs) —
content/blog/,posts/, MDX/MD directories. Read 1-2 sample files to extract: frontmatter format (all fields, types, required/optional), file naming convention, cover image path pattern, tags/categories, discovery assets (llms.txt, sitemap config, RSS feed)
- Static content files —
- UI conventions — grep for icon libs (
lucide,solar,phosphor), animation libs (framer-motion,gsap), component libs (shadcn,radix,mui), icon registries - AI tooling —
.codeiumignore,.cursorignore,.gitignore— paths AI tools cannot access
2b. Identify Significant Directories
Identify directories warranting their own scoped AGENTS.md. Criteria (any one): 10+ files with distinct responsibility, clear architectural layer, different conventions than parent, public API surface, generated code, infrastructure code.
Common significant directories:
| Stack | Significant Directories |
| Java Spring Boot | controller/, service/, repository/, model/, config/, exception/ |
| Next.js / React | app/, components/, lib/, hooks/, api/, middleware/ |
| FastAPI / Python | routers/, services/, models/, schemas/, dependencies/ |
| Go | cmd/, internal/, pkg/, handler/, store/, middleware/ |
| .NET | Controllers/, Services/, Models/, Data/, Middleware/ |
3. Generate Root AGENTS.md
Use the matching stack-specific template from .codex/templates/ as a starting point. If no stack matches, use .codex/templates/universal-agents.template.md. Fill in all sections based on deep scan results from Step 2.
Critical rules:
- State the tech stack explicitly — this drives Codex role selection and overlay activation
- Include real setup commands — extracted from config files and CI, copy-pastable
- Link to
ARCHITECTURE.mdandTESTING.mdin the Architecture reference and Testing Instructions sections - Map content architecture (if applicable) — which content files drive which pages. Prevents repeated
code_searchduring content edits - Document UI conventions (if applicable) — icon set + variant + registry, animation library, component library
- Document blog conventions (if applicable) — frontmatter format, file naming, discovery assets. Enables
blog-postskill workflow - Keep concise — avoid repeating what scoped AGENTS.md files will cover
4. Generate ARCHITECTURE.md
Apply system-architect role for this step. The system architect owns the ARCHITECTURE.md file — creation, updates, and reviews.
Use templates/architecture.template.md as the starting point. Fill in all 11 sections based on the deep scan results from Step 2.
Rules:
- Mermaid/ASCII diagrams for all visual elements
- Document what exists now, not aspirations. Include versions
- Focus on relationships and data flows
- Monorepos: Root ARCHITECTURE.md (system-wide) + per-subproject for each service with own build config. Skip doc-only, config-only, type-only dirs
5. Generate TESTING.md
Apply qa-engineer role for this step. The QA engineer owns the TESTING.md file — creation, updates, and reviews.
Use templates/testing.template.md as the starting point. Fill in all sections based on the deep scan results from Step 2.
5a. Root TESTING.md
Create TESTING.md at the project root using templates/testing.template.md (root template section). Fill in all placeholders based on deep scan results from Step 2. All sections in the template are required — remove only those marked with <!-- Remove ... --> comments.
Key data sources: test config files → test types and commands; CI pipeline → pipeline stages; directory listing → test organization; .env.example → credential structure.
5b. Per-Service TESTING.md (Monorepos)
For each subproject/service identified in Step 1b, create a scoped TESTING.md using templates/testing.template.md (per-service template section at the bottom of the file).
Rules:
- Include actual commands — copy-pastable, tested
- Reference root
.envfor credentials (test_prefixed vars), do not duplicate - List key test scenarios for critical paths (auth, payments, data mutations)
- Keep service-specific — do not repeat root TESTING.md content
5c. Single-Project (Non-Monorepo)
For single-project repos, create only root TESTING.md (no per-service files). Include all service-level detail directly in the root file.
6. Generate Scoped AGENTS.md Files
For each significant directory identified in Step 2b, create a scoped AGENTS.md:
# AGENTS.md
## Purpose
[1 sentence: what this directory contains and its role in the architecture]
## Conventions
[Directory-specific patterns, naming, file organization]
## Key Files
[Important files with brief descriptions]
## Patterns
[Code patterns used in this directory — how to add new items]
## Testing
[How to test code in this directory specifically]
## Do NOT
[Directory-specific anti-patterns and constraints]Rules for scoped AGENTS.md:
- Never repeat root AGENTS.md content — reference it if needed
- Be directory-specific — only include information relevant to THIS directory
- Include "how to add new X" — the most common operation in each directory
- Keep it short — 20–50 lines. Developers read these frequently
- State constraints — what should NOT be in this directory
Example
src/controllers/AGENTS.md — Purpose, naming convention ({Resource}Controller.java), injection rules (constructor, never repositories directly), validation (@Valid), "Adding a New Controller" steps.
7. Review and Confirm
Present a summary of all files to be created:
## Project Init Summary
### Files to create:
- [ ] AGENTS.md (root) — [X lines]
- [ ] ARCHITECTURE.md (root) — [X lines]
- [ ] TESTING.md (root) — [X lines]
- [ ] [service-1]/TESTING.md — [X lines] (monorepo only)
- [ ] [service-2]/TESTING.md — [X lines] (monorepo only)
- [ ] src/controllers/AGENTS.md — [X lines]
- [ ] src/services/AGENTS.md — [X lines]
- [ ] ...
### Project map:
[project boundary diagram from Step 1b]
### Tech stack detected:
[list of technologies, frameworks, tools]Wait for user APPROVE before writing files. User may skip directories, add undetected ones, or adjust content.
8. Write Files
After approval, create all files. For each file:
- Write the content
- Verify it was created successfully
- Report any issues
If updating existing files — show the diff and request confirmation.
9. Verify
After all files are created:
// turbo
find . -name "AGENTS.md" -o -name "ARCHITECTURE.md" -o -name "TESTING.md" | sortVerify:
- Root
AGENTS.mdexists and contains correct tech stack - Root
AGENTS.mdlinks toTESTING.mdin Testing Instructions section - Root and per-subproject
ARCHITECTURE.mdfiles exist - Root
TESTING.mdexists with all test types, commands, infrastructure - Per-service
TESTING.mdfiles exist for each subproject (monorepos) - All significant directories have scoped
AGENTS.md - No redundancy between root and scoped files
- All test commands are accurate and copy-pastable
- No secrets, PII, or hardcoded credentials in any file (especially
.envtest values)
Integration
- Precedes: All other workflows — run this first on a new project
- Templates:
.codex/templates/*-agents.template.md,.codex/templates/architecture.template.md,.codex/templates/testing.template.md - Roles:
system-architectrole (ARCHITECTURE.md creation/review),qa-engineerrole (TESTING.md creation/review),cloud-architectrole (cloud infrastructure context),devops-architectrole (CI/CD architecture context) - Skills:
test-strategyskill (test strategy, coverage targets) - Enables:
planskill,feature-devskill,bugfixskill,test-localskill,run-testsskill
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
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.

