Generate Skill

Generate comprehensive, project-specific AI documentation across Claude Code, Cursor, and Codex CLI. This skill walks through five phases: analysis, user questions, suggestion, generation, and summary.

Note: This skill uses text-based prompts instead of AskUserQuestion due to a known bug where AskUserQuestion auto-completes inside plugin skills (GitHub #29547, #29733).

Phase 1: Project Analysis

Before asking any questions, silently analyze the project. Read these files if they exist:

Package and dependency detection:

• package.json — detect package manager (bun.lockb → Bun, pnpm-lock.yaml → pnpm, yarn.lock → Yarn, package-lock.json → npm), framework (react, next, vue, nuxt, svelte, express, fastapi, django, rails), test framework (vitest, jest, mocha, pytest, rspec)
• bun.lockb, pnpm-lock.yaml, yarn.lock, package-lock.json — confirm package manager
• Cargo.toml — Rust project
• pyproject.toml, requirements.txt, setup.py — Python project
• go.mod — Go project
• pom.xml, build.gradle — Java project

Configuration files:

• tsconfig.json — TypeScript project, check paths aliases
• .eslintrc, .eslintrc.js, .eslintrc.json, eslint.config.js — ESLint present
• .prettierrc, .prettierrc.js, prettier.config.js — Prettier present
• biome.json — Biome linter/formatter present
• tailwind.config.js, tailwind.config.ts — Tailwind CSS
• vite.config.ts, vite.config.js — Vite bundler
• next.config.js, next.config.ts — Next.js
• Dockerfile, docker-compose.yml — Containerized project
• .github/workflows/ — CI/CD pipeline exists
• capacitor.config.ts, capacitor.config.json — Capacitor (cross-platform native)

Project structure detection:

• Check if packages/ or apps/ directory exists → monorepo
• Check for src/ vs flat structure
• Count top-level directories to gauge complexity
• Look for apps/web, apps/mobile, apps/api → full-stack monorepo

Existing AI documentation:

• CLAUDE.md — Claude Code project guide
• .claude/rules/ — Claude Code rules directory
• .claude/skills/ — Claude Code skills directory
• .claude/agents/ — Claude Code agents directory
• .claude/commands/ — Claude Code commands directory
• .claude/settings.json — Claude Code permissions
• .cursor/rules/ — Cursor MDC rules
• .cursorrules — Legacy Cursor rules (migration candidate)
• AGENTS.md — Codex CLI root guide
• .codex/config.toml — Codex CLI config
• .env, .env.local, .env.example — Environment files (secrets detection)

Collect all findings. Build a mental model of:

• Language + framework
• Package manager
• Monorepo vs single package
• Test and lint setup
• CI/CD presence
• Secrets/env files
• Existing AI doc coverage (none / partial / good)

Phase 2: User Questions

Present the following questions one at a time and wait for the user's response before proceeding to the next question. Record all answers before moving to Phase 3.

Question 1 — Target agents:

Present the following options to the user and wait for their response:

Which AI agents do you want to generate documentation for?

1. Claude Code (Recommended) — CLAUDE.md, rules, skills, settings
2. Cursor — MDC rules, .cursorignore
3. Codex CLI — AGENTS.md, .codex/config.toml
4. All three agents

Enter the number of your choice:

Wait for the user to respond before proceeding. Parse their response to determine the selection.

Question 2 — Key conventions:

Present the auto-detected conventions and ask for confirmation or additions. Output the following (filled in with actual detected values):

I detected the following conventions. Confirm or add anything I missed:

- Package manager: [detected value]
- Framework: [detected value]
- Language: [detected value]
- Test command: [detected or "not found"]
- Lint command: [detected or "not found"]
- Build command: [detected or "not found"]
- Monorepo: [yes/no]
- CI/CD: [yes/no]

Any additional conventions, coding standards, forbidden patterns, or architectural rules I should document? (Type them out, or press Enter to skip)

Wait for the user to respond before proceeding. Record any additions verbatim.

Question 3 — Documentation depth:

Present the following options to the user and wait for their response:

How comprehensive should the generated documentation be?

1. Quick start — Core files only (CLAUDE.md + settings), minimal content
2. Standard — Full coverage with rules and examples (Recommended)
3. Comprehensive — Everything including skills, hooks, and agent definitions

Enter the number of your choice:

Wait for the user to respond before proceeding. Parse their response to determine the selection.

Phase 3: Suggest

Based on analysis and user answers, build a suggestion checklist. Present it to the user and allow customization before generating.

Decision matrix — what to suggest:

For Claude Code:

• CLAUDE.md → Always suggest (every project needs this)
• .claude/settings.json → Always suggest (permissions baseline, deny risky tools)
• .claude/rules/ → Suggest when 3+ distinct conventions identified OR project has strong style requirements
• .claude/skills/ → Suggest when repetitive workflows detected (CI/CD → testing skill, Prettier → formatting skill, deployment patterns → deploy skill)
• .claude/agents/ → Suggest when specialized read-only analysis or write-only generation roles identified
• .claude/commands/ → Suggest when project has standard one-liner automations (run tests, format, deploy preview)
• Hooks (PostToolUse) → Suggest when ESLint/Prettier/Biome detected (auto-format on write)
• Hooks (PreToolUse) → Suggest when sensitive paths need protection

For Cursor:

• .cursor/rules/general.mdc → Always suggest for Cursor users
• .cursor/rules/[framework].mdc → Suggest when framework-specific patterns detected
• .cursorignore → Suggest when .env files or secrets directories detected

For Codex CLI:

• AGENTS.md (root) → Always suggest for Codex users
• AGENTS.md (per-package) → Suggest for monorepos with distinct package conventions
• .codex/config.toml → Suggest when custom sandbox configuration needed (non-npm package managers, special env vars)
• .codexignore → Suggest when sensitive files detected

Doc type decision matrix — which format for each need:

• Persistent coding standard → Rule (.claude/rules/)
• Reusable 5+ step workflow → Skill (.claude/skills/)
• Quick one-liner automation → Command (.claude/commands/)
• Auto-formatting on save → PostToolUse Hook
• Sensitive file protection → PreToolUse Hook or deny rule in settings.json
• Specialized AI behavior → Agent (.claude/agents/)
• Exclude from AI context → .cursorignore / .codexignore / deny in settings

Present the suggestion checklist as a numbered list. Ask: "Which of these would you like to generate? (enter numbers separated by commas, or 'all')"

Phase 4: Generate

Generate all selected files with project-specific content. Do NOT use generic placeholder content — every file must reference actual project details discovered in Phase 1.

Token Efficiency (CRITICAL)

Progressive disclosure is the goal, not a line count. CLAUDE.md should contain orientation and cross-references — not exhaustive rules. Detail goes in rule files. The aim is that only context relevant to the current task loads for any given interaction.

Reference ${CLAUDE_PLUGIN_ROOT}/reference/best-practices.md for full authoring guidance. Rough typical ranges:

File Type	Typical Range
CLAUDE.md	100–200 lines
Rule file (.claude/rules/)	50–200 lines
alwaysApply MDC body	Keep brief — loads every interaction
AGENTS.md root	Concise overview

Anti-redundancy: Never repeat the same rule verbatim across files. Cross-reference instead: "See .claude/rules/[topic].md"
Progressive disclosure: Brief mention in CLAUDE.md → full detail in rule/reference file.
Compactness: Tables > prose. Imperative voice > explanatory paragraphs.

CLAUDE.md generation:
Structure:

# [Project Name] AI Assistant Guide

## Quick Context
[1-2 sentence project description based on package.json name/description and detected framework]

**Tech Stack**: [detected stack]
**Architecture**: [monorepo/single-package, brief structure]

## Package Structure (if monorepo)
[Diagram of packages/ or apps/ directories]

## Critical Rules (ALWAYS APPLY)
[Project-specific rules based on confirmed conventions]

## Key Commands
[Actual commands from package.json scripts: dev, build, test, lint]

## File Naming
[Detected conventions or standard for framework]

## Core Hooks / Services / Utils
[Framework-specific: top-level hooks, services if detected]

.claude/settings.json generation:
Always include deny rules for:

• Risky shell commands: rm -rf /, :(){ :|:& };:, > /dev/sda
• If .env files detected: deny reading .env* files
• If AWS/cloud detected: deny writing to cloud configs without confirmation

Always include allow rules for:

• Common dev tools: npm, bun, pnpm, yarn (use detected package manager)
• git operations
• Detected test runner

.claude/rules/ generation:
Create focused, single-topic rule files. Name them descriptively: coding-standards.md, date-handling.md, api-patterns.md, testing.md, etc. If a rule file starts covering many distinct topics, split it further.

Cursor MDC rules generation:
Use identical content to Claude rules but convert format:

• Add YAML frontmatter with description, alwaysApply, and optional globs
• Convert XML-style tags to bold headers (ALWAYS/NEVER patterns)

AGENTS.md generation:
Structure matches Codex CLI expectations:

# [Project Name] — Agent Guide

## Overview
[Brief project context]

## Commands
[All detected run/build/test/lint commands]

## Repository Layout
[Actual directory structure]

## Coding Standards
[Same conventions as CLAUDE.md, formatted for Codex]

## Testing
[Test framework, how to run, what to verify]

Use templates from the scaffold skill's templates/ directory as base patterns when available. Check: /plugins/docsmith/skills/scaffold/templates/

Phase 5: Summary

After all files are created, output a structured summary:

## Docsmith Generation Complete

### Files Created
- [list every file with its path]

### Coverage
- Claude Code: [coverage level]
- Cursor: [coverage level or "not configured"]
- Codex CLI: [coverage level or "not configured"]

### Next Steps
1. Review generated files and adjust any project-specific details
2. Commit all AI doc files to version control
3. If hooks were generated, verify permissions in settings.json
4. Run `/docsmith:audit` after a week to check documentation health
5. [Any project-specific next steps based on what was detected]