Building repo conventions aware coding agents

Written by Stephanie Dover, Software Engineer 10+ YOE, ex GitHub, Twitch, Microsoft. Creator of Klaussy.

LinkedIn · GitHub · Klaussy Desktop · Klaussy Agents

TL;DR

I built klaussy-agents, an open-source CLI (pip install klaussy-agents) that reads your repo's conventions once and scaffolds repo-aware skills for five coding agents: Claude Code, Gemini CLI, Cursor, Codex, and GitHub Copilot. The interesting part is the adaptation layer: one Claude-authored SKILL.md gets rewritten into each agent's native form, including how sub-agent and plan-mode wording maps to each agent's own primitive. It's a scaffolder, not a runtime, it's at v0.3.2, and the per-agent translation has real seams. Repo: github.com/steph-dove/klaussy-agents.

The problem

Each AI coding agent carries repo context its own way. Claude Code reads CLAUDE.md, Gemini CLI reads GEMINI.md, Codex reads AGENTS.md, Cursor reads .cursor/rules, and Copilot reads .github/copilot-instructions.md. On top of that, each one has its own folder of reusable "skills" or "commands." So the conventions you write for one agent, and any review or plan workflow you tune in it, don't transfer to the others. Point a second agent at the same repo and it starts from zero, because it's reading a file the first agent never wrote.

You can keep all five context files and skill folders in sync by hand, but that's busywork that rots the first time one gets edited and the rest don't. The practical outcome is that whichever agent you open is the one that knows the least about your repo, unless you've redone the setup five times.

What makes a real fix possible is that all five agents now read the same open Agent Skills SKILL.md format. One folder format, genuinely portable. So a tool can discover the repo's conventions once and emit skills, adapted, into every agent's native layout. This post is about the adaptation step, because that's where it stops being a clean copy-paste.

Why hand-rolling five configs didn't scale for me

To be clear about what the alternatives actually are: hand-maintaining per-agent config works fine when you use one agent. A CLAUDE.md plus a couple of .claude/skills/ is a perfectly good setup, and if your whole team is on one tool, you don't need any of this.

Generic scaffolders (cookiecutter and friends) are great for stamping out project structure, but they don't know what a sub-agent is or how Cursor scopes a rule versus how Copilot does. The gap is specifically the multi-agent one: the same review workflow, expressed five different ways, kept in sync forever. This is a translation problem, not a templating problem. The SKILL.md spec provides a shared source format; the work klaussy does is the discovery, the per-agent adaptation, and the native wiring so I'm not hand-maintaining five copies of the same skill.

The honest framing is: the spec made portability possible. klaussy does the boring, error-prone part on top of it.

The approach

klaussy init does the whole thing in one pass and defaults to all five agents. Under the hood it runs a repo-conventions discovery step once, produces a project-wide CLAUDE.md plus path-scoped .claude/rules/*.md, then translates that into each agent's native form. Path-scoped rules map onto each agent's own scoping mechanism: Copilot's .github/instructions/*.instructions.md with applyTo: frontmatter, Cursor's .cursor/rules/*.mdc with globs: frontmatter, and so on.

The same one-discovery-then-translate shape applies to skills. klaussy ships 11 namespaced workflow skills, written once in Claude Code's syntax, and writes them into each agent's dedicated skills directory. The skills are namespaced <repo>-<skill> so they don't collide across repos when an agent has several checked out.

pip install klaussy-agents
klaussy init                     # prompts for base branch, scaffolds all five agents
klaussy init --agents claude,cursor   # narrow to a subset

You can also run individual steps (klaussy skills, settings, hooks, github, and so on) if you only want part of it. The rest of this post zooms in on the skills step, because the adaptation it does is the part I'd actually want to read about.

How it works

One authored skill, five target dialects

The skills are authored in Claude Code's syntax. That means they lean on a few Claude-specific constructs: `! dynamic-shell blocks that run a command and inline its output, parallel sub-agents invoked through the Agent tool with a subagent_type, and ExitPlanMode for plan mode. None of those tokens mean anything to Gemini or Codex verbatim.

So klaussy doesn't copy the body across. It rewrites each body to capture the same intent in the target agent's terms. Three concrete rewrites happen:

• Dynamic shell blocks become explicit instructions. A ! block that silently runs git diff` and inlines the result is rewritten into a plain "run this command and use its output" instruction the other agent will actually follow.
• Path references get retargeted. A skill that points at .claude/skills/... is rewritten to the target agent's own skills directory, so cross-skill references don't dangle.
• Sub-agent and plan-mode orchestration gets an adaptation note. This is the subtle one, and it's the next section.

These directories are the targets, exactly:

.claude/skills/     # Claude Code
.gemini/skills/     # Gemini CLI
.cursor/skills/     # Cursor
.agents/skills/     # Codex (neutral .agents/ path)
.github/skills/     # GitHub Copilot

Sub-agents and plan mode

Several of the skills orchestrate parallel sub-agents. The review skill, for instance, fans out separate lenses (correctness, architecture, security, scope) and runs them concurrently. In Claude Code that's the Agent tool with a subagent_type.

Different agents handle parallel sub-agents differently. Most have their own model-invocable parallel sub-agent tool, and they name it differently; a given agent or setup might not expose one:

• Claude Code: Agent / subagent_type
• Cursor: Task (GA)
• Codex: spawn_agent (GA)
• Gemini CLI: subagents (default-on, toggled under experimental)
• GitHub Copilot: task / read_agent (plus an experimental context: fork)

So instead of hardcoding sequential, the adaptation note tells the target agent to map Claude's sub-agent wording onto its own equivalent primitive, and to fall back to sequential execution only if it genuinely has none. The note carries intent ("these lenses are independent, run them in parallel"), not Claude-specific tool names. The same goes for ExitPlanMode: the note describes the plan-then-confirm intent rather than naming a tool that only Claude has.

# Illustrative — exact wording is generated per skill, confirm in the emitted SKILL.md
# Adaptation note (appended when a skill orchestrates sub-agents):
# This skill runs independent lenses in parallel. Use your own
# parallel sub-agent tool (e.g. Task / spawn_agent / subagents / task).
# Only run them sequentially if you have no sub-agent tool.

This is the part I find genuinely teachable: portability across agents isn't "find and replace the tool name." It's separating intent from primitive, then letting each agent rebind the intent to whatever primitive it owns. The SKILL.md spec gives you a shared container; it doesn't give you shared tools, so the body has to be written to degrade gracefully.

A real skill, so this isn't abstract

To make "what a generated skill actually does" concrete: the review skill triages by diff size, then runs parallel lenses. Beyond the four standard lenses it adds an Agentic/Evals lens when the change touches AI code, and an Architecture-Decision/Design-Doc lens when the PR contains an ADR, RFC, or design doc. It's precision-biased: an empty review (nothing worth flagging) is a valid outcome. Every finding has to name a concrete trigger, and a final validation phase self-refutes false positives before anything is reported.

That whole workflow is authored once and adapted into all five agents' skills folders. The lens fan-out is exactly the piece that needs the sub-agent translation above; the precision-bias and validation phases are plain prose and carry across unchanged.

Permissions and hooks ride along

The skills step is the headline, but klaussy init also writes native permission allow-lists per agent (Claude settings.json allow/deny, Gemini settings.json tools.allowed, Cursor permissions.json terminalAllowlist, Codex config.toml approval/sandbox) and tries to keep secrets like .env, *.pem, and credentials* out of each agent's reach using that agent's own mechanism.

It also wires two cross-agent hooks: a git-commit guard that runs your detected format and lint before a commit, and a read-injection guard that scans file and fetch content for prompt-injection markers. The guard scripts pull the command or path out of whatever agent's hook payload they're handed and block with exit 2 plus stderr, which every supported agent honors. They're pure-stdlib and hardened so any parse error falls back to allow rather than crashing. The current suite is 130 tests passing, ruff clean.

A quick demo

Point it at a repo and run it:

pip install klaussy-agents
klaussy init

It prompts for the base branch, then scaffolds conventions files, skills, permissions, and hooks for all five agents. If you only want a subset, name them:

klaussy init --agents claude,cursor

After that, opening any of the configured agents in the repo means it already has the conventions file it looks for and the namespaced skills in its own directory. You're still installing and running the agents yourself; klaussy generates the files they read.

What's next, and where the seams are

A deep-dive owes you the honest version, so here's what doesn't fully reach:

• The skills are Claude-authored then adapted, not hand-tuned per agent. The adaptation captures intent, and the sub-agent note tells each agent to use its own primitive, but it's a translation, not five bespoke skill sets written from scratch for each agent's quirks. If you want a skill perfectly idiomatic to Codex, you may still tweak it by hand.
• Hook coverage is uneven, by design. The read-injection guard is wired for Claude, Gemini, and Cursor only. Codex exposes no pre-file-read hook event, and Copilot's preToolUse is fail-closed with unconfirmed read-tool args, so those two get the commit guard only. klaussy logs that rather than pretending the guard is everywhere.
• Secret exclusion isn't universally possible. Codex's sandbox governs writes and network, not reads, so there's no read-exclusion there; Copilot content-exclusion is a GitHub setting, not a committed file. klaussy says so instead of faking a .ignore that wouldn't do anything.
• It leans on the SKILL.md spec being honored. Portability is real today, but the spec and the agents are young. If an agent changes how it reads skills, klaussy has to track it.

None of those are agents being "equal." They're not. The whole point of the adaptation layer is that the agents differ and the skill set has to bend to each one. klaussy is a scaffolder: it generates files the agents read, it does not run the agents or change their model quality.

(One disambiguation: there's a separate, paid klaussy desktop app. Different product, same developer. This post is only about the open-source klaussy-agents CLI.)

Try it

Repo: github.com/steph-dove/klaussy-agents
Install: pip install klaussy-agents

{% github steph-dove/klaussy-agents %}

If you run more than one coding agent in the same repo, I'd like to know which skill survived the translation cleanly and which one came out awkward in your agent of choice. Open an issue or drop a comment with what broke.