A powerful suite of agent skills designed to keep AI-assisted coding sessions aligned, observant, and continuously improving.
Vibe Code Ninja is tool-agnostic. It works seamlessly with modern AI coding assistants that support the SKILL.md standard, including Claude Code, Antigravity, Cursor, Codex, and Gemini CLI.
The suite is composed of three core skills, designed to work independently but compose beautifully:
The Architect. Prevents architectural drift and maintains code-doc alignment.
Instead of loading your entire codebase, it manages 16 canonical project documents (like AGENTS.md and docs/ARCHITECTURE.md) and intelligently routes context by task to save tokens. It runs mandatory scope, decision, and deletion anti-drift checks before making code changes.
The Observer. Turns daily friction into structured insights.
Whenever you think, "I keep doing this manually" or "This should be a skill," simply tell your AI to log it. This skill captures your observations into a structured log (~/.agents/skill-gaps.md) in seconds.
The Evolver. Autonomously evolves your workflows. Run weekly, this skill reads your gap log, identifies recurring friction patterns, and drafts new skills. It includes built-in guardrails: a 7-day quarantine, three-signal routing, and mandatory manual reviews to ensure only high-quality skills graduate.
Roadmap Note:
code-graph-ninjaCurrently deferred to uphold our evidence-driven philosophy. A code-mapping skill will only be built ifskill-ninja-loggerreports ≥10 instances of "AI reads ≥3 files to locate one symbol" within 30 days.
We recommend installing these skills in the open standard directory (~/.agents/skills/), which Cursor reads natively and other tools can access via symlinks.
# 1. Extract the archive and enter the directory
cd vibe-code-ninja
# 2. Install to the open standard directory (native to Cursor)
mkdir -p ~/.agents/skills
cp -r project-ninja skill-ninja-logger skill-ninja-review ~/.agents/skills/3. Click to expand setup for your specific AI Tool
For Claude Code:
mkdir -p ~/.claude/skills
ln -s ~/.agents/skills/project-ninja ~/.claude/skills/
ln -s ~/.agents/skills/skill-ninja-logger ~/.claude/skills/
ln -s ~/.agents/skills/skill-ninja-review ~/.claude/skills/For Antigravity:
mkdir -p ~/.gemini/antigravity/skills
ln -s ~/.agents/skills/project-ninja ~/.gemini/antigravity/skills/
ln -s ~/.agents/skills/skill-ninja-logger ~/.gemini/antigravity/skills/
ln -s ~/.agents/skills/skill-ninja-review ~/.gemini/antigravity/skills/For Codex:
mkdir -p ~/.codex/skills
ln -s ~/.agents/skills/project-ninja ~/.codex/skills/
ln -s ~/.agents/skills/skill-ninja-logger ~/.codex/skills/
ln -s ~/.agents/skills/skill-ninja-review ~/.codex/skills/For Gemini CLI:
mkdir -p ~/.gemini/skills
ln -s ~/.agents/skills/project-ninja ~/.gemini/skills/
ln -s ~/.agents/skills/skill-ninja-logger ~/.gemini/skills/
ln -s ~/.agents/skills/skill-ninja-review ~/.gemini/skills/Verify Installation: Restart your AI tool and ask: "What skills do you have available?" All three skills should be listed.
Maximize your workflow by following this recommended loop:
- Install the Suite: Setup is quick and works across multiple AI assistants.
- Initialize: Run
project-ninjain INIT mode on your messiest active project. - Consult: Use
project-ninjain CONSULT mode before non-trivial code changes. Let the anti-drift checks protect your architecture. - Log Friction: Invoke
skill-ninja-loggerwhenever you hit a repetitive task ("log a skill gap"). - Evolve: Run
skill-ninja-reviewweekly to process your gap log and auto-generate new skills.
Every skill in the suite is built on three foundational philosophies:
- Token efficiency comes from routing, not compression.
project-ninjadynamically targets 1–3 specific files per task rather than loading all 16 project documents. Loading precise context is far more effective than summarizing large amounts of text. - Evidence-driven over speculative. We don't build features just because they sound cool. Skills are only auto-graduated when multiple occurrences prove a pattern is real.
- Quarantine over approval gates. New, auto-created skills land in a 7-day quarantine rather than waiting for immediate approval. This avoids prompt fatigue, letting you intervene only when something looks wrong.
vibe-code-ninja/
├── project-ninja/
│ ├── references/ # Detailed procedures (init, consult, update)
│ ├── templates/ # 16 minimal markdown templates for projects
│ └── SKILL.md # Core instructions & mode router
├── skill-ninja-logger/
│ └── SKILL.md # Friction logging instructions
├── skill-ninja-review/
│ └── SKILL.md # Weekly review and generation logic
└── README.md # You are here
(Each skill includes its own README for deeper technical details).
- For AI Coding Agents: See AGENTS.md — the single source of truth for agent rules, stack, and routing.
- Product Scope: See docs/PRODUCT.md — what we are building, for whom, and what is explicitly out of scope.
- Architecture: See docs/ARCHITECTURE.md — folder structure, file design, and how the skills execute.
- Decisions Log: See docs/DECISIONS.md — append-only log of architectural decisions.
Encountered a problem or unexpected behavior? Please open an issue and follow the steps in our Quick Guide to Reporting Issues
We’re excited to have you! Check out our Contribution Guide to learn how to make pull requests, and more ways to help shape this project.
If Vibe Code Ninja has saved you tokens, prevented architectural drift, or streamlined your workflow, consider supporting the project:
- ⭐ Star the Repo: Help others discover the "Ninja" way.
- 📣 Spread the Word: Share your workflow on X/Twitter or your blog.
- ☕ Fuel the Forge: Consider a donation to fund ongoing development and open-source initiatives.
This project is licensed under the MIT License.