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?"

1. Yes (recommended for Claude Code users)
2. 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:

1. Always ask: "Is this detection correct? Anything to add or change?" (freeform)
2. If no description found: "What is this project in one sentence?"
3. Always ask: "Any hard constraints Claude should always follow?" (e.g., "never use npm", "always prefer server components", "use conventional commits")
4. 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.

5. 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
6. 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}:

1. 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

2. 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

3. 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

4. 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."

1. Yes — add to .gitignore (recommended for most projects)
2. 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:

1. Inform the user: "Context7 MCP is not available in this environment. I can't automatically fetch documentation."
2. Offer alternatives:
   • Skip tech docs (proceed without them)
   • User provides documentation URLs to fetch via WebFetch
   • User provides local documentation paths to index
3. 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)

1. Project header — # Name + one-line description
2. Tech Stack — bulleted list: - **Category**: Technology
3. 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.
4. Conventions — concrete, actionable rules. Use sub-sections (e.g., ### Testing, ### Naming) when a category has 3+ rules.
5. Tech Stack Docs (optional) — only if tech docs were fetched in Phase 3. Compressed index pointing to .docs/ files.
6. Implementation Plan (optional) — only if PLAN.md exists. Brief pointer to the file.
7. 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:

1. Write AGENTS.md
2. 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)
3. 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"):

1. Run Phase 1 detection as normal
2. Read current AGENTS.md content
3. 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
4. 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

5. Ask for approval — user can accept all, pick specific changes, or cancel
6. Apply approved changes — edit the file, don't regenerate from scratch
7. 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?"
8. 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.
9. Symlink check — if {create_symlink} is true, verify the CLAUDE.md symlink still exists and points to AGENTS.md; recreate if broken
10. 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.