Author once, run in every agent: how we share AI skills at Echo

At Echo we lean on AI coding agents hard, and we do not standardize on one. I use Claude Code, someone else lives in Cursor, another engineer runs Codex. That is deliberate — the same “engineers as product owners” instinct that shapes how we build also means people pick the tool that fits their head.

The problem is that a coding skill — how we run the tests, what the PR-review checklist is, which boring-stack conventions we hold to — is the same regardless of which agent you opened. But the moment you write it down, every harness wants it in its own format. Claude Code wants SKILL.md files under .claude/skills/. Cursor wants .mdc rules with its own frontmatter. Codex reads one aggregated AGENTS.md with a size budget. Write the convention three times, and within a week the three copies have drifted and nobody trusts any of them.

I built adeptability to kill that drift. This is how it works and how we actually use it.

The idea: skill as source, harness as build target

adept treats one canonical skill as the source of truth and every harness’s format as a build target — the same relationship your source code has to compiled artifacts.

You author once: a SKILL.md with YAML frontmatter and a markdown body, plus optional scripts/ and references/ sidecars. Then:

adept sync     # render the canonical skill into every enabled harness
adept status   # init state, libraries, harnesses, and drift at a glance

adept sync writes .claude/skills/run-tests/SKILL.md, .cursor/rules/run-tests.mdc, the right block in Codex’s AGENTS.md, and so on — each in that harness’s native format, with the frontmatter translation, activation rules, and size budgets handled per harness. Subagents work the same way: one canonical agent definition renders into .claude/agents/, Cursor’s agents, Codex’s, and the rest.

Edits happen inside harnesses, so sync goes both ways

The naive version of this tool is one-directional and breaks the first time someone tweaks a rule inside Cursor. adept handles it: a content-hash state machine classifies every rendered file as synced, ahead, behind, or diverged. Edit a skill inside a harness and adept sync-from pulls that edit back into the canonical source, then adept sync republishes it everywhere. There is no lockfile — drift is computed from hashes at read time, so there is no second artifact to keep honest.

How we share at Echo

Two layers, because we have two kinds of skills.

Org-wide conventions live in a versioned library. The stuff every repo should know — our code-as-liability conventions, the boring-stack choices, a shared PR-reviewer subagent that reviews to our standard — lives in a library with a remote and a ref. A project commits only the reference, not the content; adept materializes the skills into a per-machine store on demand. A teammate clones a repo, runs adept, and gets the same skills and the same reviewer agent rendered into whichever harness they use. Bump the library ref and everyone moves together.

Project-specific skills are committed in the repo. How this service runs its tests, builds, and deploys is not org-wide knowledge — it belongs to the repo. Those canonical skills sit in the project, and adept sync renders them locally. Clone, sync, and your agent already knows how to run the test suite and ship the thing, no matter which agent it is.

The payoff is concrete: a convention is written once and true everywhere. When we change how we review PRs, I edit one skill and bump the library — I am not chasing the same change through three formats and hoping the Cursor copy and the Codex copy agree.

Scheduled work, too

Some of what we want agents to do is not interactive. adept loop add composes a discovery skill, an evaluator agent, and a cron skeleton in one shot — a scheduled loop that goes looking for something and acts on it. It is the same author-once model applied to automation instead of an interactive session.

Why I think this is the right shape

Echo’s whole engineering bet is that code is a liability and the solution is the asset. Skills are the same. The convention — the judgment about how we work — is the asset worth keeping. Which harness’s file format it happens to be trapped in is pure liability, and duplicating it across three of them is liability times three. adept makes the skill the durable thing and the harness format disposable, which is exactly the right way round.

adeptability is a single static Go binary, installable via Homebrew, go install, Nix, or a curl script. The project page has the design decisions, the repo has the code, and the docs cover every command and a harness-by-harness breakdown of exactly what gets emitted where.