{"slug": "building-repo-conventions-aware-coding-agents", "title": "Building repo conventions aware coding agents", "summary": "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.", "body_md": "I built **klaussy-agents**, an open-source CLI (`pip install klaussy-agents`\n\n) 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`\n\ngets 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.\n\nEach AI coding agent carries repo context its own way. Claude Code reads `CLAUDE.md`\n\n, Gemini CLI reads `GEMINI.md`\n\n, Codex reads `AGENTS.md`\n\n, Cursor reads `.cursor/rules`\n\n, and Copilot reads `.github/copilot-instructions.md`\n\n. 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.\n\nYou 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.\n\nWhat makes a real fix possible is that all five agents now read the same open [Agent Skills](https://agentskills.io/specification) `SKILL.md`\n\nformat. 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.\n\nTo be clear about what the alternatives actually are: hand-maintaining per-agent config works fine when you use one agent. A `CLAUDE.md`\n\nplus a couple of `.claude/skills/`\n\nis a perfectly good setup, and if your whole team is on one tool, you don't need any of this.\n\nGeneric 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`\n\nspec 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.\n\nThe honest framing is: the spec made portability possible. klaussy does the boring, error-prone part on top of it.\n\n`klaussy init`\n\ndoes 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`\n\nplus path-scoped `.claude/rules/*.md`\n\n, 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`\n\nwith `applyTo:`\n\nfrontmatter, Cursor's `.cursor/rules/*.mdc`\n\nwith `globs:`\n\nfrontmatter, and so on.\n\nThe 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>`\n\nso they don't collide across repos when an agent has several checked out.\n\n```\npip install klaussy-agents\nklaussy init                     # prompts for base branch, scaffolds all five agents\nklaussy init --agents claude,cursor   # narrow to a subset\n```\n\nYou can also run individual steps (`klaussy skills`\n\n, `settings`\n\n, `hooks`\n\n, `github`\n\n, 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.\n\nThe skills are authored in Claude Code's syntax. That means they lean on a few Claude-specific constructs: ```\n\n`!`\n\ndynamic-shell blocks that run a command and inline its output, parallel sub-agents invoked through the `Agent`\n\ntool with a `subagent_type`\n\n, and `ExitPlanMode`\n\nfor plan mode. None of those tokens mean anything to Gemini or Codex verbatim.\n\nSo 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:\n\n! ` block that silently runs `\n\ngit 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/...`\n\nis rewritten to the target agent's own skills directory, so cross-skill references don't dangle.These directories are the targets, exactly:\n\n```\n.claude/skills/     # Claude Code\n.gemini/skills/     # Gemini CLI\n.cursor/skills/     # Cursor\n.agents/skills/     # Codex (neutral .agents/ path)\n.github/skills/     # GitHub Copilot\n```\n\nSeveral 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`\n\ntool with a `subagent_type`\n\n.\n\nDifferent 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:\n\n`Agent`\n\n/ `subagent_type`\n\n`Task`\n\n(GA)`spawn_agent`\n\n(GA)`experimental`\n\n)`task`\n\n/ `read_agent`\n\n(plus an experimental `context: fork`\n\n)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`\n\n: the note describes the plan-then-confirm intent rather than naming a tool that only Claude has.\n\n```\n# Illustrative — exact wording is generated per skill, confirm in the emitted SKILL.md\n# Adaptation note (appended when a skill orchestrates sub-agents):\n# This skill runs independent lenses in parallel. Use your own\n# parallel sub-agent tool (e.g. Task / spawn_agent / subagents / task).\n# Only run them sequentially if you have no sub-agent tool.\n```\n\nThis 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`\n\nspec gives you a shared container; it doesn't give you shared tools, so the body has to be written to degrade gracefully.\n\nTo 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.\n\nThat 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.\n\nThe skills step is the headline, but `klaussy init`\n\nalso writes native permission allow-lists per agent (Claude `settings.json`\n\nallow/deny, Gemini `settings.json`\n\n`tools.allowed`\n\n, Cursor `permissions.json`\n\n`terminalAllowlist`\n\n, Codex `config.toml`\n\napproval/sandbox) and tries to keep secrets like `.env`\n\n, `*.pem`\n\n, and `credentials*`\n\nout of each agent's reach using that agent's own mechanism.\n\nIt 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`\n\nplus 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.\n\nPoint it at a repo and run it:\n\n```\npip install klaussy-agents\nklaussy init\n```\n\nIt 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:\n\n```\nklaussy init --agents claude,cursor\n```\n\nAfter 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.\n\nA deep-dive owes you the honest version, so here's what doesn't fully reach:\n\n`preToolUse`\n\nis 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`\n\nthat 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.\n\n(One disambiguation: there's a separate, paid klaussy desktop app. Different product, same developer. This post is only about the open-source `klaussy-agents`\n\nCLI.)\n\nRepo: [github.com/steph-dove/klaussy-agents](https://github.com/steph-dove/klaussy-agents)\n\nInstall: `pip install klaussy-agents`\n\n```\n{% github steph-dove/klaussy-agents %}\n```\n\nIf 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.", "url": "https://wpnews.pro/news/building-repo-conventions-aware-coding-agents", "canonical_source": "https://dev.to/stephanie_dover_b49c2e8d1/building-repo-conventions-aware-coding-agents-1ep8", "published_at": "2026-06-18 01:51:18+00:00", "updated_at": "2026-06-18 02:21:28.620055+00:00", "lang": "en", "topics": ["developer-tools", "large-language-models", "ai-agents", "generative-ai"], "entities": ["klaussy-agents", "Claude Code", "Gemini CLI", "Cursor", "Codex", "GitHub Copilot", "Agent Skills", "steph-dove"], "alternates": {"html": "https://wpnews.pro/news/building-repo-conventions-aware-coding-agents", "markdown": "https://wpnews.pro/news/building-repo-conventions-aware-coding-agents.md", "text": "https://wpnews.pro/news/building-repo-conventions-aware-coding-agents.txt", "jsonld": "https://wpnews.pro/news/building-repo-conventions-aware-coding-agents.jsonld"}}