Building repo conventions aware coding agents

A developer built klaussy-agents, an open-source CLI that reads a repository's conventions once and scaffolds repo-aware skills for five coding agents: Claude Code, Gemini CLI, Cursor, Codex, and GitHub Copilot. The tool translates a single SKILL.md file into each agent's native format, solving the problem of maintaining separate context files and skill folders for multiple agents. It is available at v0.3.2 on GitHub.

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. 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 https://agentskills.io/specification 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. 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. 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. 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: 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. .claude/skills/... is rewritten to the target agent's own skills directory, so cross-skill references don't dangle.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 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: Agent / subagent type Task GA spawn agent GA experimental 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. 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. 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. 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. A deep-dive owes you the honest version, so here's what doesn't fully reach: 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. .ignore that wouldn't do anything.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. Repo: github.com/steph-dove/klaussy-agents https://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.