Modular Codebase Rules Skill

Install

Run directly with npx:

npx modular-codebase-rules-skill install

Run directly from GitHub:

npx github:lavisar/modular-codebase-rules-skill install

Install into another project:

npx modular-codebase-rules-skill install --cwd /path/to/project

Install into another project from GitHub:

npx github:lavisar/modular-codebase-rules-skill install --cwd /path/to/project

Pin i18n behavior explicitly:

npx modular-codebase-rules-skill install --i18n yes
npx modular-codebase-rules-skill install --i18n no

For CI or fully non-interactive installs, npx --yes answers npm's package download prompt, while install --yes accepts this installer's defaults:

npx --yes modular-codebase-rules-skill install --yes

Or install globally:

npm install -g modular-codebase-rules-skill

Then use:

modular-codebase-rules install

What It Does

Installs a project-local AI coding skill into .agents/skills/modular-codebase-rules/. The generated agent pointer files make AI coding agents read the skill before coding, detect the current frontend stack, and apply modular architecture, naming, API, state, styling, i18n, and validation rules that match the project.

Supported Agents

By default, the installer keeps the target repo quiet: it writes one root pointer file, AGENTS.md, and stores the full rule pack under .agents/skills/modular-codebase-rules/. In an interactive terminal, the installer shows a checkbox list so you can choose only the agent adapters this repo actually uses.

Generate every best-effort adapter only when the repo needs them:

npx modular-codebase-rules-skill install --agents all

Generate only specific adapters in CI or scripts:

npx modular-codebase-rules-skill install --agents codex,cursor,claude

In --agents all mode, the installer writes lightweight pointer files for common AI coding agents:

• Codex / OpenAI coding agents: AGENTS.md
• Claude Code: CLAUDE.md, .claude/CLAUDE.md
• Gemini: GEMINI.md, .gemini/GEMINI.md
• Cursor: .cursor/rules/modular-codebase-rules.mdc
• GitHub Copilot: .github/copilot-instructions.md
• Windsurf: .windsurfrules
• Cline: .clinerules/modular-codebase-rules.md
• Roo: .roo/rules/modular-codebase-rules.md
• DeepSeek: DEEPSEEK.md
• Qwen: QWEN.md
• Generic agents: AI_RULES.md, CONVENTIONS.md

Support is best-effort: each agent decides which instruction files it reads, but the package generates the most common project-level entrypoints.

Supported Frameworks And Tooling

The detector recognizes common frontend stacks:

• Frameworks: Next.js, Nuxt, Angular, SvelteKit, Remix, Vite, Expo, React Native, Astro
• Renderers: React, Vue, Svelte, Angular
• Languages: TypeScript, JavaScript
• Styling: Tailwind CSS v4/v3, CSS tooling, styled-components, Emotion, CVA, tailwind-merge
• Server state: TanStack Query, SWR, Apollo Client, urql, axios-based API layers
• Client state: Zustand, Redux, Jotai, Recoil, Pinia
• Routing: Next, Nuxt, SvelteKit, Angular router, React Router, Vue Router
• Tests: Vitest, Jest, Playwright, Cypress, Testing Library
• Package managers: npm, pnpm, yarn, bun
• i18n: i18next, react-i18next, next-intl, next-i18next, vue-i18n, nuxt-i18n, Angular localize, svelte-i18n, Lingui, FormatJS, Intlayer, Paraglide

Unknown stacks are still supported with universal modularity rules.

What Gets Installed

The rule pack is copied into:

.agents/skills/modular-codebase-rules/

That folder contains:

SKILL.md
project-detection.md
project-detection.json
architecture.md
coding-rules.md
checklist.md
review-backlog.md
scripts/detect-framework.mjs

The default root-level AGENTS.md file is only a pointer. It tells the agent to read:

.agents/skills/modular-codebase-rules/SKILL.md

before coding.

How It Works

1. The installer detects the project framework, package manager, state libraries, styling system, i18n setup, and validation commands.

2. Detection is cached in:

   .agents/skills/modular-codebase-rules/project-detection.md

3. AGENTS.md is generated or updated with a marked block. Use --agents all when the repo needs Claude, Gemini, Cursor, Copilot, Windsurf, Cline, Roo, DeepSeek, Qwen, or generic adapter files too.

4. On every coding task, the agent reads the pointer, then SKILL.md.

5. SKILL.md tells the agent to read only the deeper rule files needed for the task.

This keeps token use low. Agents do not preload every rule file for every task.

Estimated Token Cost

Rough estimates at ~4 bytes per token. Actual counts vary by tokenizer and by how large project-detection.md grows for your repo.

| File | Size | ~Tokens | Read when | |---|--:|--:|---| | AGENTS.md (pointer) | 1.3 kB | ~330 | Always — this is the only file loaded on every turn | | SKILL.md | 3.8 kB | ~950 | Any coding task | | project-detection.md | ~2.1 kB | ~530 | Any coding task | | architecture.md | 6.9 kB | ~1,730 | New or moved files, module boundaries | | coding-rules.md | 14.0 kB | ~3,490 | Hooks, API, stores, styling, tests | | checklist.md | 3.3 kB | ~830 | Before final response or commit | | review-backlog.md | 4.5 kB | ~1,120 | Only in the origin repo | | Whole pack | 35.9 kB | ~9,000 | Never, under normal use |

What that means per task:

| Task | Files read | ~Tokens | |---|---|--:| | Question about the repo, no code change | pointer only | ~330 | | Small edit inside an existing file | pointer + skill + detection | ~1,800 | | New feature, new files | + architecture + coding-rules + checklist | ~7,850 | | Refactor in the origin repo | + review-backlog | ~9,000 |

The saving comes from what is always loaded, not from the total size. A monolithic CLAUDE.md / AGENTS.md holding these same rules costs ~8,400 tokens on every turn of every conversation. Here the always-loaded footprint is the ~330-token pointer, and the rest is pulled in on demand — so a session that never touches code pays ~4% of the monolithic cost, and even a full feature build pays it once rather than per turn.

Refresh Detection

Refresh after changing dependencies, lockfiles, framework config, i18n setup, or scripts:

modular-codebase-rules detect --cwd "$PWD" --write

Print without writing:

modular-codebase-rules detect --cwd "$PWD" --format markdown
modular-codebase-rules detect --cwd "$PWD" --format json

CLI

modular-codebase-rules detect [--cwd <project>] [--format json|markdown] [--write]
modular-codebase-rules install [--cwd <project>] [--force] [--i18n yes|no] [--yes] [--agents minimal|all|<ids>]
modular-codebase-rules install-agent-rules [--cwd <project>] [--force] [--agents minimal|all|<ids>]
modular-codebase-rules install-codex-skill

Useful aliases:

install-modular-codebase-rules-skill
install-ai-agent-rules
detect-codebase-framework

Maintenance Model

The skill uses progressive disclosure:

• SKILL.md is short and must be read first.
• project-detection.md is the cached stack summary.
• architecture.md is read only for file placement and module boundaries.
• coding-rules.md is read only for implementation details.
• checklist.md is read before final reporting, commit, or PR.
• review-backlog.md is legacy context and should only apply when its paths exist.

This design keeps day-to-day token consumption low while preserving deeper rules for larger tasks.

Notes

• The detector is heuristic. It should guide the agent, not replace reading nearby code.
• The package does not install runtime dependencies into your app.
• The installer is idempotent: it updates its own marked block instead of duplicating it.
• Existing instruction files are never destroyed. A file that already contains the marker block has that block updated in place. A file with unmarked content gets the block appended to the end.
• --force only changes that last case: instead of appending, it rewrites the file with just the generated block. The previous contents are copied to <file>.bak first (.bak.1, .bak.2… if a backup already exists) and the installer prints the backup paths, so nothing is lost. You rarely need this flag.
• --agents minimal is the default and writes only AGENTS.md; --agents all writes every supported adapter pointer. You can also pass comma-separated ids: codex, claude, gemini, cursor, copilot, windsurf, cline, roo, deepseek, qwen, generic.