using-adept

name	using-adept
description	Use the `adept` CLI to author AI skills once and render them into Claude Code, Cursor, Codex, Copilot, and OpenCode. Apply when installing/syncing skills, editing skill.yaml/SKILL.md, or touching .adeptability/.
allowed-tools	["Bash","Read","Edit","Write"]

Using the adept CLI

adept makes one AI skill portable across every coding harness. You author once in a canonical format; adept renders accurately into each harness's native layout and keeps both sides in sync.

Mental model

canonical skill  ──render──▶  .claude/skills/…   (per-skill)
(.adeptability/  ──render──▶  .cursor/rules/….mdc (single-file)
 skills/<id>/    ──render──▶  AGENTS.md            (Codex aggregate)
 SKILL.md)       ──render──▶  .github/instructions (Copilot aggregate)
                 ◀─sync-from─  (adopt edits made directly in a harness file)

• Identity is (id, content-hash) — there are no version numbers. The hash decides whether something changed.
• A skill is a directory <root>/skills/<id>/ with one SKILL.md (YAML frontmatter + markdown body) and optional sidecars (scripts/, references/, assets/).
• The filesystem is the source of truth. config.json only records which harnesses are enabled, the materialization mode, and library remotes.

Canonical SKILL.md format

---
id: pr-review                 # ^[a-z0-9](?:[a-z0-9-]{0,48}[a-z0-9])?$ — matches the directory name
description: Use before opening a PR. Tests, security, performance.   # <= 280 chars
activation: agent             # always | globs | agent | manual
globs: []                     # REQUIRED when activation: globs
allowed-tools: [Read, Grep]   # carried into Claude Code
targets: []                   # empty = all enabled harnesses
tags: [review, quality]
---
# PR Review Checklist
- [ ] Tests added or updated
- [ ] No secrets in the diff

The commands you'll use most

adept init                       # scaffold .adeptability/ in the current project
adept init --from <git-url>      # …and clone a remote skill library to pull skills from
adept harness add <id>           # enable a harness (claude-code | cursor | codex | copilot | opencode)
adept sync                       # render canonical skills → every enabled harness
adept status                     # init state, libraries, harnesses, and drift at a glance
adept diff                       # show exactly what differs between canonical and rendered
adept sync-from                  # adopt edits made directly in a harness file back to canonical
adept skill add <id> --edit      # scaffold a new skill and open $EDITOR
adept skill install <owner>/<repo>/<skill>   # install one skill from GitHub/skills.sh (pinned to a SHA)

adept --help is the source of truth for the command surface — it's always current, so prefer it over memory. adept --help lists every verb; adept <command> --help (e.g. adept skill --help, adept sync --help) shows that command's subcommands and flags. Global flags on every command: --json, --log-level debug|info|warn|error, --project <path>, --library <path>.

Typical tasks

Start fresh, author your own skills

adept init
adept skill add lint-style --edit
adept harness add claude-code
adept harness add cursor
adept sync

Adopt a project that already has harness files (.claude/, .cursor/, AGENTS.md, …)

adept init        # auto-detects and adopts existing harness skills into canonical
adept status      # confirm what got adopted
adept diff        # confirm the round-trip is clean

Pull skills from a shared library

adept init --from [e-mail]:my-org/skills.git
adept harness add claude-code
adept sync

Install one vetted skill from the ecosystem

adept skill search find-skills
adept skill info  vercel-labs/skills/find-skills    # repo, stars, license, SHA, installs
adept skill install vercel-labs/skills/find-skills  # preview + safety scan + y/N

Rules of thumb (so you don't surprise the user)

• Edit canonical, then adept sync. Don't hand-edit rendered files like .cursor/rules/*.mdc — they're regenerated. If you must edit a harness file directly, run adept sync-from to pull the change back into canonical.
• Run adept status / adept diff before and after a sync so you can report what changed.
• Installs are gated. adept skill install runs a safety scan and shows a preview; a critical finding blocks the install unless the user passes --allow-unsafe. Never pass --allow-unsafe or --yes on the user's behalf without explicit confirmation.
• Exit codes are meaningful: 0 clean, 1 error, 2 drift/dirty or merge conflict. Scan severities map the same way (high → 1, critical → 2).
• Secrets stay in the environment. Provider API keys are read from the environment at call time; adept never writes them to config.json.
• Aggregator harnesses (Codex/Copilot) have a byte budget — if skills overflow it, the lowest-priority ones are dropped and a truncation note is written. Check adept status.