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 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.
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
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.