Create Project Agency

Generate an AGENTS.md and supporting documentation for the current project. Detects framework, tooling, and structure automatically, then asks targeted questions to fill gaps.

Arguments: $ARGUMENTS

--update — Skip the existing-file prompt and go straight to update mode

Phase 0: Setup & Existing File Check

Step 1: CLAUDE.md Symlink Question

Ask the user:

"This skill generates AGENTS.md as the primary documentation file. Would you also like a CLAUDE.md symlink pointing to it?"

Yes (recommended for Claude Code users)

No — just AGENTS.md

Store the choice as {create_symlink} (true/false).

Step 2: Check for Existing Files

Check if AGENTS.md already exists in the project root.

If it exists AND --update was NOT passed:

Show the user a summary of the existing file
Ask: "AGENTS.md already exists. Would you like to: (1) Update it with new detections, (2) Regenerate from scratch, (3) Cancel?"
If "Update" → proceed to Phase 1 in update mode (see Update Mode section below)
If "Regenerate" → proceed to Phase 1 normally (will overwrite)
If "Cancel" → stop

If it exists AND --update was passed:

Proceed directly to Phase 1 in update mode

If it does not exist:

Proceed to Phase 1 normally

Also check for an existing CLAUDE.md that is NOT a symlink — if found, note it for Phase 5 (warn before replacing with a symlink).

Phase 1: Silent Detection

Scan the project root to build a detection profile. Do NOT ask the user anything yet — just gather signals. Use Glob and Read tools.

What to Detect

Package ecosystem — check for these files at the project root:

package.json → read name, description, scripts, dependencies, devDependencies, workspaces, packageManager
Lockfiles: yarn.lock → yarn, package-lock.json → npm, pnpm-lock.yaml → pnpm, bun.lock / bun.lockb → bun
requirements.txt / pyproject.toml / setup.py → Python
go.mod → Go
Cargo.toml → Rust
Gemfile → Ruby
composer.json → PHP

Framework — check for config files:

next.config.* → Next.js (read for App Router vs Pages Router signals)
nuxt.config.* → Nuxt
svelte.config.* → SvelteKit
vite.config.* → Vite
angular.json → Angular
remix.config.* → Remix
astro.config.* → Astro

TypeScript — tsconfig.json:

Check compilerOptions.strict for strict mode
Check compilerOptions.paths for path aliases

Monorepo — check for:

turbo.json → Turborepo
nx.json → Nx
pnpm-workspace.yaml → pnpm workspaces
workspaces field in root package.json → yarn/npm workspaces
lerna.json → Lerna

Linting / formatting:

.eslintrc*, eslint.config.* → ESLint
.prettierrc*, prettier.config.* → Prettier
biome.json, biome.jsonc → Biome

Testing:

vitest.config.* or vitest in devDeps → Vitest
jest.config.* or jest in devDeps → Jest
playwright.config.* or @playwright/test in devDeps → Playwright
cypress.config.* or cypress in devDeps → Cypress
pytest.ini, conftest.py, pyproject.toml [tool.pytest] → pytest

Styling:

tailwind.config.* or @tailwindcss in deps → Tailwind CSS (check v3 config file vs v4 CSS-only)
postcss.config.* → PostCSS

Backend / database:

convex/ directory → Convex
supabase/ directory or supabase in deps → Supabase
prisma/ directory → Prisma
drizzle.config.* → Drizzle
firebase.json or firebaserc → Firebase

Existing documentation:

README.md → read for project description and setup instructions
docs/ directory → list contents
Any root .md files → note them

Directory structure:

List top-level directories (exclude: node_modules, .git, dist, build, .next, .turbo, __pycache__, .venv, target, vendor)
For monorepos, also list workspace directories one level deep

Detection Output Format

Build an internal profile object (not shown to user yet):

Project: {name from package.json or directory name}
Description: {from package.json or README}
Package Manager: {detected}
Language: {TypeScript strict | TypeScript | JavaScript | Python | Go | Rust | ...}
Framework: {detected}
Monorepo: {tool} with workspaces: [{list}]
Styling: {detected}
Backend: {detected}
Testing: {tools detected}
Linting: {tools detected}
Structure: {top-level dirs}
Existing Docs: {list of .md files found}

Phase 2: Present Findings & Ask Questions

Show the detection summary in a clean format:

## Detected Project Profile

- **Project**: {name} — {description or "no description found"}
- **Package Manager**: {yarn | npm | pnpm | bun | pip | ...}
- **Language**: {TypeScript (strict) | TypeScript | JavaScript | ...}
- **Framework**: {Next.js (App Router) | Nuxt 3 | SvelteKit | ...}
- **Monorepo**: {Turborepo | Nx | none} — workspaces: {list}
- **Styling**: {TailwindCSS v4 | TailwindCSS v3 | CSS Modules | ...}
- **Backend**: {Convex | Supabase | Prisma + PostgreSQL | ...}
- **Testing**: {Vitest + Playwright | Jest + Cypress | ...}
- **Linting**: {ESLint + Prettier | Biome | ...}
- **Structure**: {key directories}

Then ask targeted questions using AskUserQuestion. Only ask what detection couldn't determine:

Always ask: "Is this detection correct? Anything to add or change?" (freeform)
If no description found: "What is this project in one sentence?"
Always ask: "Any hard constraints Claude should always follow?" (e.g., "never use npm", "always prefer server components", "use conventional commits")
Always ask: "Any conventions not captured above?" (e.g., naming patterns, file organization rules, component patterns)

Keep questions minimal. If detection was thorough, questions 1 and 3 may be sufficient.

Always ask: "Which of these detected technologies would you like documentation fetched for? Select all that apply." Present each detected technology as a selectable option (multiSelect). Group by category:
- Framework: e.g., Next.js, Nuxt, SvelteKit
- Language: e.g., TypeScript, Python, Go
- Backend/DB: e.g., Supabase, Prisma, Drizzle, Convex
- Testing: e.g., Vitest, Playwright, Jest, Cypress
- Styling: e.g., TailwindCSS
- Other: any other significant detected libraries
Always ask: "Any technologies NOT detected that you'd like docs fetched for?" (freeform)

Store selections from questions 5 and 6 as {tech_docs_list}.

Phase 3: Fetch Tech Stack Documentation

For each technology in {tech_docs_list}, fetch documentation and save it locally.

Step 1: Create docs directory

Create .docs/ at the project root if it doesn't exist.

Step 2: Fetch docs for each technology

For each technology in {tech_docs_list}:

Resolve library — Use the resolve-library-id Context7 MCP tool:
- Query: the technology name (e.g., "next.js", "typescript", "tailwindcss")
- Select the best matching library ID
Query documentation — Use the query-docs Context7 MCP tool with targeted queries:
- Query topics relevant to the technology category (see Topic Guide below)
- Run up to 3 queries per technology to cover core topics
Save documentation — Write fetched content to .docs/{technology}/:
- Create subdirectory: .docs/{technology}/ (e.g., .docs/nextjs/, .docs/typescript/)
- Save each query result as a separate markdown file named by topic
- File naming: {topic}.md (e.g., routing.md, data-fetching.md)
- Prepend each file with: # {Technology} — {Topic}\n\n> Source: Context7 documentation\n\n
Build index entry — Record the files created for the compressed index

Topic Guide

Query topics based on technology category:

Frameworks (Next.js, Nuxt, SvelteKit, Remix, Astro, etc.):

Routing and navigation
Data fetching and caching
API routes / server functions

Languages (TypeScript, Python, Go, Rust, etc.):

Type system / type utilities (TS), typing (Python), etc.
Configuration and compiler options
Common patterns and idioms

Backend/DB (Supabase, Prisma, Drizzle, Convex, Firebase):

Schema definition and migrations
Querying and mutations
Authentication and security rules

Testing (Vitest, Jest, Playwright, Cypress, pytest):

Configuration and setup
Writing tests and assertions
Mocking, fixtures, and test utilities

Styling (TailwindCSS, etc.):

Configuration and customization
Utility classes and patterns
Responsive design and theming

Step 3: Ask about .gitignore

Ask the user:

"Would you like to add .docs/ to .gitignore? These are fetched artifacts that can be re-generated, but committing them ensures availability in CI and for team members without Context7."

Yes — add to .gitignore (recommended for most projects)

No — commit docs to the repository

If yes, add .docs/ to the project's .gitignore (create the file if it doesn't exist).

Step 4: Verify

After fetching, list all files created in .docs/ and confirm the count with the user:

"Fetched documentation for {N} technologies ({list}). {X} files saved to .docs/. Proceeding to generate AGENTS.md."

Fallback — If Context7 is unavailable

If Context7 MCP tools (resolve-library-id, query-docs) are not available:

Inform the user: "Context7 MCP is not available in this environment. I can't automatically fetch documentation."
Offer alternatives:
- Skip tech docs (proceed without them)
- User provides documentation URLs to fetch via WebFetch
- User provides local documentation paths to index
If skipping, proceed to Phase 4 without tech docs index

Phase 4: Generate AGENTS.md

Write the file using the template structure from references/claude-md-template.md. Read that file now for the exact format.

Section Order (strict)

Project header — # Name + one-line description
Tech Stack — bulleted list: - **Category**: Technology
Project Structure — fenced ASCII tree, 1-2 levels deep. Add inline comments for non-obvious directories. Include "Future additions" line if the user mentioned planned directories.
Conventions — concrete, actionable rules. Use sub-sections (e.g., ### Testing, ### Naming) when a category has 3+ rules.
Tech Stack Docs (optional) — only if tech docs were fetched in Phase 3. Compressed index pointing to .docs/ files.
Implementation Plan (optional) — only if PLAN.md exists. Brief pointer to the file.
Doc Index — compressed pipe-delimited format. Only list files that actually exist. Always include the index maintenance rule.

Writing Rules

Be concrete, not generic. "Use yarn for all package management" is good. "Follow best practices" is not.
Omit sections with nothing to say. If there's no monorepo, don't include a structure section showing a flat project.
Use the user's words from their answers in Phase 2 for constraints and conventions.
Keep it under 80 lines. AGENTS.md should be scannable. Link to docs for details. The Tech Stack Docs index section doesn't count toward the 80-line target since it's a machine-generated reference.
No placeholder content. Every line should be real information about this project.

Tech Stack Docs Section (if Phase 3 fetched docs)

If tech docs were fetched in Phase 3, include this section between Conventions and Implementation Plan:

## Tech Stack Docs

Prefer retrieval-led reasoning over pre-training-led reasoning for any tech stack tasks. Consult the relevant documentation below before implementing features or making technical decisions.

\```
[{ProjectName} Tech Docs]|root: ./.docs
|nextjs:{routing.md, data-fetching.md, api-routes.md}
|typescript:{type-system.md, configuration.md, patterns.md}
|tailwindcss:{configuration.md, utilities.md, theming.md}
\```

The format mirrors the Doc Index but uses the .docs/ root. Each entry lists the actual files saved during Phase 3. Only include entries for technologies that have docs fetched.

Phase 5: Verify & Iterate

Show the generated AGENTS.md content to the user. Ask:

"Here's the generated AGENTS.md. Would you like any adjustments before I write it?"

If the user requests changes, make them. When approved:

Write AGENTS.md
If {create_symlink} is true:
- If CLAUDE.md exists as a real file (not a symlink), warn the user: "CLAUDE.md exists as a standalone file. Creating the symlink will replace it. Proceed?"
- Create symlink: ln -s AGENTS.md CLAUDE.md (relative path)
Remind: "Don't forget to commit AGENTS.md" (and "CLAUDE.md" if the symlink was created) "to your repository."

Phase 6: Guided Documentation Creation

After AGENTS.md is finalized, offer to create supporting documentation.

Presenting the Menu

Show only doc types that make sense for the detected project:

Doc	When to Offer	File Path
Architecture	Always (non-trivial projects)	`docs/architecture.md`
Testing	When testing tools were detected	`docs/testing.md`
Vision	When user describes an ambitious product	`docs/vision.md`
Contributing	When project likely has collaborators (GitHub remote, multiple contributors in git log)	`docs/contributing.md`
Implementation Plan	When project is in active development	`PLAN.md`

Present as a selectable menu:

"Would you like to create any supporting documentation? Select all that apply, or skip to finish."

Architecture (recommended for most projects)
Testing conventions
Product vision
Contributing guide
Implementation plan (PLAN.md)
Skip — I'm done

Flow for Each Selected Doc

For each doc the user selects:

1. Ask targeted questions (3-5, tailored to what was detected):

Architecture (docs/architecture.md):

"What's the rationale behind your tech stack choices?" (pre-fill from detection)
"Describe your core domain model — what are the key entities and their relationships?"
"What are the main data flows? (e.g., user action → API → database → real-time update)"
"How is this deployed? (Vercel, AWS, self-hosted, etc.)"
"Any planned architectural changes or future components?"

Testing (docs/testing.md):

"What's your testing philosophy? (e.g., test as user stories, test pyramid, TDD)"
"File naming conventions for tests?" (pre-fill if detected: *.test.ts, *.spec.ts)
"Any test data conventions? (factories, fixtures, test email domains, cleanup strategy)"
"What should be unit tested vs E2E tested?"
"Any testing-specific tooling? (MSW, test containers, custom fixtures)"

Vision (docs/vision.md):

"What problem does this project solve?"
"Who is the target audience?"
"What differentiates this from alternatives?"
"What's the core UX philosophy?"

Contributing (docs/contributing.md):

"What are the steps to set up the dev environment from scratch?"
"What's the PR process? (branch naming, review requirements, merge strategy)"
"Any code review expectations?"
"Required checks before merging? (tests, linting, type-check)"

Implementation Plan (PLAN.md):

"What phase is the project in now?"
"What's been completed so far?"
"What are the next 3-5 steps?"
"Any key decisions already made that should be recorded?"

2. Generate the doc from answers + detected signals. Follow the same writing rules as Phase 4: concrete, not generic. Use the template examples as quality benchmarks — read them from references/claude-md-template.md for format guidance.

3. Show output and ask for adjustments.

4. Write the file and update the Doc Index in AGENTS.md:

Add a new entry in the pipe-delimited format
Entry format: |{key}:{{file path} - {compressed single-line summary}}

5. Move to the next selected doc or finish.

After All Docs Are Created

Show a summary of everything that was created:

## Created files:
- AGENTS.md
- CLAUDE.md → AGENTS.md (symlink, if opted in)
- docs/architecture.md
- docs/testing.md
(etc.)

Remember to commit these files to your repository.

Update Mode

When running in update mode (existing AGENTS.md + --update flag or user chose "Update"):

Run Phase 1 detection as normal
Read current AGENTS.md content
Diff detection against current content — identify:
- New technologies/tools detected but not in AGENTS.md
- Directory structure changes
- New documentation files not in the Doc Index

Present proposed changes to the user:

## Proposed Updates to AGENTS.md

**Add to Tech Stack:**
- Vitest (detected in devDependencies)

**Update Structure:**
- New directory: `apps/mobile/`

**Update Doc Index:**
- Add: docs/contributing.md

**No changes to:**
- Conventions (still accurate)
- Project description

Ask for approval — user can accept all, pick specific changes, or cancel
Apply approved changes — edit the file, don't regenerate from scratch
Never remove content without asking — if something in AGENTS.md wasn't detected, ask before removing: "I didn't detect {X} anymore. Should I remove it from AGENTS.md?"
Tech docs check — check if .docs/ exists and if any newly detected technologies are missing docs. If new technologies detected since last run, offer to fetch docs for them. If .docs/ exists, verify the Tech Stack Docs Index in AGENTS.md matches the actual files — add/remove index entries as needed.
Symlink check — if {create_symlink} is true, verify the CLAUDE.md symlink still exists and points to AGENTS.md; recreate if broken
Migration — if only CLAUDE.md exists (no AGENTS.md), offer to migrate: rename CLAUDE.md to AGENTS.md and create a symlink back

Important Guidelines

Use Glob and Read tools for all file detection — never guess what exists
Read references/claude-md-template.md before generating any AGENTS.md content — it contains the canonical format and examples
Don't fabricate information — if you can't detect something and the user didn't mention it, leave it out
Keep AGENTS.md under 80 lines — it's a quick reference, not exhaustive documentation
The Doc Index uses pipe-delimited format — match the exact format shown in the template
Always create the docs/ directory before writing files into it
Update AGENTS.md's Doc Index every time a new doc is created
When the user opts for a CLAUDE.md symlink, create it using a relative path (ln -s AGENTS.md CLAUDE.md). Never write content to the symlink directly.
Use Context7 MCP tools (resolve-library-id then query-docs) to fetch tech documentation. Limit to 3 queries per technology.
Save all tech documentation to .docs/{technology}/ using lowercase kebab-case directory names (e.g., .docs/nextjs/, .docs/tailwindcss/).
The Tech Stack Docs Index is separate from the project Doc Index. Tech docs point to .docs/, project docs point to ./docs/ or ./.
Ask the user about .gitignore for .docs/ — some teams want to commit docs for offline/CI use, others prefer to treat them as fetched artifacts.

create-project-agency