adeptability

It started at Echo, where we do not standardize on one AI coding agent — I run Claude Code, teammates use Cursor and Codex. The same team conventions kept getting written into each harness’s own format and drifting apart within days. I built adept to have one canonical source and render the rest. (I wrote up the team side of that on my blog.)

The problem

Every AI coding agent invented its own on-disk format for the same idea: a reusable instruction you want the agent to follow. Claude Code wants SKILL.md files under .claude/skills/. Cursor wants .mdc rules with its own frontmatter and activation semantics. Codex reads one aggregated AGENTS.md with a 32 KiB budget. Copilot buckets instructions per glob under .github/instructions/. Fifty other harnesses do fifty other things.

The instruction itself — how to run the tests, what a good migration looks like, the team’s review checklist — is harness-agnostic. But the moment you write it down, it is locked to whichever tool you happened to be using that day. Switch tools, or work on a team where people use different ones, and you either duplicate everything by hand or accept drift.

The approach

adept treats the skill as the source of truth and the harness formats as build targets.

You author one canonical skill: a SKILL.md with YAML frontmatter and a markdown body, plus optional scripts/, references/, and assets/ sidecars. adept sync renders it into every enabled harness’s native path and schema — frontmatter translation, activation rules, aggregation, and size budgets handled per harness. Subagents work the same way: one canonical agent definition rendered to .claude/agents/, .cursor/agents/, .codex/agents/*.toml, and the rest.

Sync is not one-way, because files get edited in place inside harnesses. A content-hash state machine classifies every rendered file as synced, ahead, behind, or diverged; adept status and adept diff read from it, and adept sync-from pulls a harness-side edit back into the canonical skill before republishing it everywhere.

Design decisions

• One static binary. A tool that touches every repo you work in has to install the same way on a laptop, in CI, and in a container, without dragging a runtime along. Go makes that the default.
• Specialized where it matters, generic everywhere else. Five harnesses — Claude Code, Cursor, OpenCode, Codex, and GitHub Copilot — get hand-written renderers, because their formats carry real semantics: activation translation, sidecar handling, size caps. The long tail of 50+ agents goes through a YAML-driven adapter, so supporting a new harness is a config file dropped into the adapter directory, not a recompile.
• No lockfile. Drift state is computed from content hashes at read time. There is no second artifact to keep honest.
• Libraries resolve like packages. A team’s shared skills live in a versioned library. The project commits only a reference — name, remote, ref — and the skills materialize into a per-machine store on demand. Teammates clone the repo, run adept, and get the same skills rendered into their own harnesses, whichever those are.
• The tool teaches itself. adept init seeds bundled skills like using-adept and authoring-adept-skills, so the agent knows how to work with the system from the first session.

Install

# macOS / Linux (Homebrew)
brew install itaywol/tap/adeptability

# Go (any platform)
go install github.com/itaywol/adeptability/cmd/adept@latest

# Nix / NixOS (flake)
nix profile install github:itaywol/adeptability

Pre-built binaries are cosign-signed and published on GitHub releases. The documentation site covers the concepts, the full command reference, and a harness-by-harness comparison of exactly what gets emitted where, and why.