I got tired of AI agents trashing my codebase, so I built a skill to fix that

#ai #vibecoding #productivity #opensource

Every AI coding agent I've used hits the same wall. It always starts the same way.

You ask it to add a feature. It rewrites half the file in its preferred naming convention. Your snake_case Python suddenly has camelCase crammed in. The test framework you carefully chose? Gone, replaced by a different one the model apparently likes better.

So you fight it back into shape. Then you ask it to fix a bug. Same thing happens. It "tidies up" a few unrelated functions while it's in there. Opens three files you didn't ask it to touch. Leaves a commented-out console.log in production code.

Then the worst one: you hit three failures in a row on a gnarly bug, and the agent just keeps trying random things. No backoff. No ask-for-help. Just vibes and increasingly desperate code changes until the whole file is a mess.

I've context-window-pasted my way through this more times than I want to admit. Not because the agents are bad — they're genuinely powerful — but because there's no agreed-upon discipline baked in. No "read the room before you touch anything." No "when you're stuck three times in a row, stop and ask."

So I spent some time vibe coding a skill file to fix that, and turned it into 🐿️ Squirrel.

What it actually does

Squirrel is a single Markdown file (SKILL.md) that you drop into your AI agent's instruction path. It installs a full 8-phase engineering discipline into your agent, without you having to remind it every session.

[1] 🔍 Discover  → Audit the project before touching a single line
[2] 📋 Plan      → Task list with dependencies and done-criteria
[3] 💻 Build     → Write or modify code
[4] 🧪 Test      → Run existing tests, write new ones
[5] 🐛 Bug Hunt  → Static analysis + manual checklist
[6] ✨ Polish    → Lint, format, type check
[7] 📖 Document  → README + inline docs (update, don't overwrite)
[8] 🚀 Ship      → Final checklist before handoff

The key insight is Step 0 — before the agent does anything, it figures out what kind of project it's looking at:

What it sees	Mode
Empty directory	🆕 Greenfield — start from scratch
Source files, no tests	🔧 In-Progress — audit first, then improve
Source + tests + CI + README	🏗️ Mature — targeted improvements only
"fix this bug / add this feature"	🎯 Targeted — abbreviated audit, scoped work

Then it announces the mode to you. So you know it read your code before it started writing.

The "respect existing code" problem

This is the thing I cared most about getting right. Squirrel explicitly teaches the agent:

Match the existing naming convention — if the project uses snake_case, don't introduce camelCase
Use the existing test framework — don't swap in a new one because it's newer
Read 2-3 similar files before writing a new one, to understand the pattern
Touch only what's necessary — "add a password reset endpoint" is not permission to refactor the auth module

In practice this means adding something like this to the SKILL.md:

## For existing code:
- **Match the codebase's style** — check .eslintrc, pyproject.toml, rustfmt.toml
- **Read before writing** — look at 2-3 similar existing functions first
- **Touch only what's necessary**
- **Leave the codebase better than you found it**, scoped to what you touched

Sounds obvious, right? But without it being explicit in the agent's instruction context, most models default to "write it my way."

Solving the infinite debugging loop

The part I found most satisfying to design: the 3-Strike Rule.

Strike 1: Fix the specific error. Run tests. Move on.

Strike 2: Re-read the code more carefully. Try a different approach.

Strike 3: STOP. Revert. Write a failure report. Ask the user.

## After Strike 3:
1. STOP all edits
2. REVERT to last known working state (git stash)
3. Write a failure report:
   - What I tried
   - What went wrong
   - Where I think the problem is
   - What I've ruled out
4. ASK THE USER
5. NEVER: leave code broken, delete failing tests, shotgun-debug

This alone has saved me from agent death spirals more than once. Instead of watching it make 12 increasingly confused changes to the same function, it stops at 3, tells me what it knows, and asks. Like a junior engineer would.

Works on 8 platforms, install in one line

The whole thing is just Markdown. Every major AI coding agent reads Markdown instructions — the YAML frontmatter is consumed by OpenCode, silently ignored by everything else.

# Auto-detect your agent and install
curl -fsSL https://raw.githubusercontent.com/flyingsquirrel0419/squirrel-skill/main/install.sh | bash

# Or for a specific platform
bash install.sh --platform cursor
bash install.sh --platform claude-code
bash install.sh --platform aider

Supported: OpenCode, Codex, Claude Code, Cursor, Windsurf, Aider, Cline, GitHub Copilot.

If you just want minimal setup that covers four platforms at once, drop AGENTS.md in your project root. Natively read by Codex, Cursor, Cline, and Claude Code.

For Cursor specifically, add the frontmatter:

---
description: Squirrel full-cycle development skill
alwaysApply: true
---

Then paste the SKILL.md content below it.

Reference files included

Squirrel ships with supplementary templates the agent loads on demand — not all upfront, only when relevant:

File	Loaded when
`references/plan_template.md`	Phase 1, creating Plan.md
`references/readme_template.md`	Phase 7, writing a new README
`references/stack_hints.md`	Phase 3, unfamiliar languages or stacks
`references/ci_templates.md`	Phase 8, setting up GitHub Actions

The CI templates cover Node.js, Python, Go, Rust — ready-to-use starting points, not drop-in guarantees.

What vibe coding this taught me

I built Squirrel as a vibe coding exercise — give the agent a clear goal, iterate fast, let it do the heavy lifting. It was the first time I really leaned into that workflow end-to-end on something I cared about shipping.

The irony isn't lost on me: I needed better agent discipline to build a skill that teaches agents discipline. Every time the agent went sideways during development, I'd notice what rule was missing and add it to SKILL.md. The 3-Strike Rule came from a particularly painful afternoon of watching it loop on a bash parsing edge case.

By the end, the skill file had basically written itself — not because the AI wrote it, but because the failures showed me exactly what needed to be in it.

Getting started

# One liner
curl -fsSL https://raw.githubusercontent.com/flyingsquirrel0419/squirrel-skill/main/install.sh | bash

# Then tell your agent what you want:
> squirrel this project — add tests, fix lint errors, write README
> build me a REST API for a todo app with TypeScript
> fix this bug in src/auth/login.py