nurosys-agent-skills

Portable AI agent skills for code review, architecture, auth, and project memory.
Works across Claude Code, Cursor, Codex, and Antigravity — one install, all your projects.

Install

npm install --save-dev nurosys-agent-skills
npm exec nurosys-agent-setup

The setup wizard detects your stack (backend / frontend / monolith) and asks which IDE(s) you use. It then wires everything automatically.

What gets created

Claude Code

| Path | Purpose | |------|---------| | .claude/skills/ | Slash commands — type /architect, /code-reviewer, etc. | | .claude/agents/ | Subagent workflows | | CLAUDE.md | Project instructions + code-review-graph MCP guidance | | AGENTS.md | Same file — shared with Codex |

Claude Code reads .claude/skills/<name>/SKILL.md and registers it as /name. The skills directory is a single symlink into the package, so every skill is available immediately with no extra configuration.

Cursor

| Path | Purpose | |------|---------| | .cursor/mcp.json | Registers the code-review-graph MCP server project-wide | | .cursor/rules/code-review-graph.mdc | Always-on MDC rule: tells Cursor to use graph tools before grep/read | | .cursor/rules/<skill>.mdc | One MDC rule per skill — Cursor injects the relevant skill into context when the task matches | | .cursor/rules/<artifact>.mdc | Project-memory rules — added after running nurosys-setup-rules |

All Cursor rules are proper MDC files with YAML frontmatter (description, globs, alwaysApply). The code-review-graph rule is always injected; skill rules are description-triggered so they only appear when relevant.

Codex

| Path | Purpose | |------|---------| | AGENTS.md | Project instructions (shared with Claude Code) | | .codex/rules/default.rules | Starlark execution policy — pre-allows npm, git, node, code-review-graph | | ~/.codex/config.toml | User-level MCP config for code-review-graph |

Antigravity

| Path | Purpose | |------|---------| | .agents/skills/ | Stack skills | | .agents/workflows/ | Workflows | | .agents/rules/ | Project-memory rules (after nurosys-setup-rules) | | GEMINI.md | Project instructions |

Skills

Invoke with /skill-name in Claude Code. Cursor pulls them in automatically via MDC rules when the task is relevant.

| Skill | What it does | |-------|-------------| | /architect | Decomposes a feature into modules with dependency ordering and per-module implementation prompts | | /code-reviewer | Full-stack review against your constitution, auth model, and quality playbook — outputs a structured REVIEW_REPORT | | /create-blueprint <type> | Generates or updates project-memory/ artifacts from your live codebase | | /auth-and-permissions | Audits auth/JWT/RBAC changes against your auth model invariants | | /explore-codebase | Fast code navigation using code-review-graph graph queries | | /debug-issue | Traces root causes using graph-powered execution flow analysis | | /refactor-safely | Plans and executes refactors with full dependency and impact analysis |

Workflows

Long-running autonomous workflows — trigger from Claude Code agents or run the shell script directly.

| Workflow | What it does | |----------|-------------| | build-feature-backend | End-to-end feature lifecycle: plan → modules → implement → review | | feature-module-runner | Implements all modules in a plan sequentially, one at a time | | backend-quality-review | Post-implementation quality gate before merge | | add-new-api-feature-module | Scaffolds a single new API module with all required files |

Quick start

1. Generate project-memory (first time only)

/create-blueprint all

Generates all artifacts in sequence: architecture → models → repo-map → constitution → auth-model → quality-playbook → core-memory. Edit them to match your project.

2. Wire IDE rules from project-memory

npm exec nurosys-setup-rules

Creates .cursor/rules/<artifact>.mdc (and .agents/rules/ for Antigravity) pointing to your project-memory/ files. Re-run any time you add a new artifact.

3. Design and implement a feature

/architect

Outputs a MODULE_WISE_PLAN.md with per-module prompts. Then run all modules autonomously:

scripts/run-feature-modules.sh documentation/features/<feature-name>/

4. Review before merging

/code-reviewer

Outputs a REVIEW_REPORT with blockers, highs, mediums, suggestions, and a merge recommendation.

Project-memory: your project's source of truth

Skills read project-memory/ to understand your architecture and enforce your rules. Generate with /create-blueprint <type>.

| File | What it defines | |------|----------------| | constitution.md | Non-negotiable rules — security, validation, DI, SQL, logging | | auth-model.md | JWT flow, guard chain, RBAC, identity propagation, tenant scoping | | repo-map.md | Module layout, naming conventions, reusable components, entry points | | architecture.md | System layers, module topology, data flow, integration points | | models.md | Domain model inventory — entities, associations, constraints | | quality-playbook.md | Anti-patterns, symptoms, preferred fixes | | core-memory.md | Historical decisions, completed modules, known patterns |

How skills work

User: /code-reviewer
   ↓
Skill reads project-memory/ (constitution, auth-model, quality-playbook)
   ↓
Skill calls code-review-graph MCP (detect_changes, get_impact_radius, get_review_context)
   ↓
Skill reads only the relevant files — targeted, not exhaustive
   ↓
Structured REVIEW_REPORT written to documentation/reports/

All skills use code-review-graph for structural analysis — callers, dependents, test coverage, impact radius — context that text search cannot provide.

Updating

After npm update nurosys-agent-skills, re-run setup to sync real files:

npm update nurosys-agent-skills
npm exec nurosys-agent-setup   # updates .cursor/rules/*.mdc and other real files
npm exec nurosys-setup-rules   # refreshes project-memory MDC rules if frontmatter changed

Symlinked files (.claude/commands/, CLAUDE.md, etc.) update automatically because they point into node_modules. Real files (.cursor/rules/code-review-graph.mdc, .cursor/mcp.json, .codex/rules/default.rules) are compared and overwritten only when content has changed.

Troubleshooting

/architect (or any skill) not showing in Claude Code
Check that .claude/skills/ is a symlink to the package skills directory (ls -la .claude/skills). Re-run npm exec nurosys-agent-setup if it's missing. Claude Code requires .claude/skills/<name>/SKILL.md — the directory name becomes the /name command.

Cursor not using graph tools / skills
Check that .cursor/rules/ contains .mdc files with valid YAML frontmatter. Re-run npm exec nurosys-agent-setup to regenerate them.

project-memory/ rules not in Cursor
Run npm exec nurosys-setup-rules after generating your project-memory artifacts. Re-run any time you add a new one.

Skills giving generic advice instead of project-specific guidance
Your project-memory/ docs may be missing or stale. Run /create-blueprint <artifact-type> to regenerate from your live codebase.

A symlink exists as a real directory
Setup skips directories it didn't create. Remove it first, then re-run:

rm -rf .claude/skills
npm exec nurosys-agent-setup

Codex support

Selecting Codex during setup wires:

1. AGENTS.md → project instructions (shared with Claude Code if both selected)
2. .codex/rules/default.rules — pre-allows npm, git, node, code-review-graph. Edit to tighten or expand command permissions. See Codex rules docs.
3. ~/.codex/config.toml — adds code-review-graph MCP. See Codex MCP docs.

License

MIT

Contributing

Issues and PRs: https://gitlab.com/nurosys/nurosys-agents/-/issues