Inject docs

Framework Documentation Injector

Inject compressed framework-specific best practices and documentation into the current project's CLAUDE.md or AGENTS.md file. This gives AI coding agents passive access to framework knowledge without requiring tool calls or skills.

Supported Frameworks

Framework	Detection Method	Documentation Source
Next.js	next in package.json	Vercel's agents-md codemod (version-aware)
FastAPI	fastapi in requirements.txt/pyproject.toml	zhanymkanov/fastapi-best-practices

Anti-Hallucination Guidelines

CRITICAL:

1. Auto-detect the framework before running anything - check project files to identify the framework
2. Do NOT assume tools are available - verify Node.js/Python tooling exists based on framework
3. Do NOT claim success until verifying the target file exists and contains actual content
4. Read actual output - report what the commands say, not what is expected

Implementation Workflow

Phase 0: Framework Detection & Validation (REQUIRED)

Before running anything, auto-detect the framework and verify prerequisites:

1. Detect the framework:

   • Check for package.json with next dependency → Next.js project
   • Check for pyproject.toml with fastapi dependency → FastAPI project
   • Check for requirements.txt containing fastapi → FastAPI project
   • If multiple frameworks detected, prioritize based on arguments or ask user
   • If no framework detected, STOP and inform the user: "Could not detect a supported framework (Next.js or FastAPI)."

2. Detect framework version (if applicable):

   • For Next.js: extract version from package.json
   • For FastAPI: extract version from pyproject.toml or requirements.txt
   • Report the detected version to the user

3. Detect target file:

   • Check if CLAUDE.md exists in the project root - use CLAUDE.md
   • Else check if AGENTS.md exists - use AGENTS.md
   • If neither exists, default to CLAUDE.md (Claude Code's native format)
   • Inform the user which file will be updated

Phase 1: Run Framework-Specific Injection

Option A: Next.js Projects

Execute the Vercel codemod with the --output flag, in the project root:

npx @next/codemod@canary agents-md --output <TARGET_FILE>

Where <TARGET_FILE> is the file detected in Phase 0 (e.g., CLAUDE.md or AGENTS.md).

What this does:

• Auto-detects the Next.js version from package.json
• Downloads version-matching documentation from Vercel's servers
• Injects a compressed pipe-delimited index into the target file
• Downloads full docs to .next-docs/ and adds it to .gitignore
• Non-interactive mode (no prompts, thanks to --output)

Important:

• Requires network access
• Non-destructive: injects/updates the index section without overwriting existing content
• Compresses ~40KB of docs into ~8KB (Vercel's agent evals showed 100% pass rate vs 53% baseline)
• Target file priority: CLAUDE.md (if exists) → AGENTS.md (if exists) → CLAUDE.md (default)

Option B: FastAPI Projects

Run the bundled injection script using this skill's own absolute directory path — not $(dirname "$0"). That trick resolves against the shell's path when run through the Bash tool, not this SKILL.md's location, so it silently points at the wrong (or a nonexistent) script. Use the directory this SKILL.md was loaded from instead:

uv run <absolute-path-to-this-skill-dir>/scripts/inject_fastapi_docs.py

The script:

• Detects whether CLAUDE.md or AGENTS.md exists and targets the right file
• Checks if a "FastAPI Best Practices" section already exists (updates it if so, appends if not)
• Injects compressed best practices covering: domain-driven structure, async patterns, Pydantic validation, dependency injection, SQLAlchemy integration, error handling, testing, and Ruff code quality

See references/fastapi-best-practices.md for the exact content injected.

Phase 2: Verify Results

After Phase 1 completes:

1. Confirm the target file was updated - read it back and check it contains the injected framework content (pipe-delimited Next.js index, or the ## FastAPI Best Practices section)
2. Check size - note the approximate size before/after (Next.js codemod prints this; for FastAPI, compare file sizes yourself)
3. Do not report success on command exit code alone — verify the content actually landed.

Phase 3: Report

Summarize for the user:

• Framework and version detected
• Which file was updated (CLAUDE.md or AGENTS.md), created vs. updated
• Confirmation that framework docs were injected, with approximate size
• Suggest reviewing the diff and committing

Examples

Next.js project with existing CLAUDE.md

> inject Next.js docs

Detected Next.js 15.2.3 in package.json
Found existing CLAUDE.md - will inject documentation there
Running: npx @next/codemod@canary agents-md --output CLAUDE.md
Updated CLAUDE.md (2.1 KB -> 10.3 KB)
Added .next-docs to .gitignore

Review the changes and commit when ready:
  git add CLAUDE.md .gitignore && git commit -m "docs: add Next.js agents-md framework reference"

FastAPI project with no existing docs file

> inject FastAPI best practices

Detected FastAPI 0.115.0 in pyproject.toml
No CLAUDE.md or AGENTS.md found - creating CLAUDE.md
Ran scripts/inject_fastapi_docs.py
Created CLAUDE.md (0 B -> 6.8 KB) with "FastAPI Best Practices" section

Review the changes and commit when ready:
  git add CLAUDE.md && git commit -m "docs: add FastAPI best-practices reference"

Unsupported framework

> inject docs for this Django app

Checked package.json, pyproject.toml, requirements.txt - no `next` or
`fastapi` dependency found.

Could not detect a supported framework (Next.js or FastAPI). This skill
only injects docs for those two. No files were changed.