Spec format

Source paths below are relative to .agnostic-ai/ by default. For example, rules/*.md means .agnostic-ai/rules/*.md. Override directories with sources.

Start with a rule for conventions, a skill for a reusable workflow, or an MCP server for a tool connection. See Getting started for a complete first-rule example.

Discovery is recursive. Every .md under agents/, skills/, rules/, commands/, reviews/, ignore/ is picked up; every .yaml under hooks/, mcps/, settings/, and environments/.

Nested layout: per-directory scope

A spec in a subdirectory of its source dir carries an implicit scope equal to that subpath.

rules/
├── conventional-commits.md      # scope: ""    (root)
├── backend/
│   └── auth.md                  # scope: "backend"
└── backend/api/
    └── limits.md                # scope: "backend/api"

For rules, scope controls native activation or directory discovery. It does not merely organize generated files. A flat rule may set scope: services/payments; source-layout scope takes precedence. Create one with:

agnostic-ai new rule payments-context --scope services/payments

Scoped bodies are excluded from root instruction appendices. Supported targets receive native path conditions or a nested instruction file. Unsupported targets skip the rule with a warning, or fail under on-unsupported: error.

See directory-specific instructions for the complete target matrix, selector rules, runtime limits, and shared-reader compatibility.

Agents

---
name: code-reviewer
description: Reviews diffs for bugs, style, and architectural issues.
tools: [Read, Grep, Bash]
model: sonnet
---

You are a code reviewer. Examine the diff for:
- Logic bugs and edge cases
- Style consistency
- Security issues

Report concise findings with `file:line` references.

Any other frontmatter field passes through to the target CLI unchanged.

Per-target models

model: accepts a string (same model everywhere) or a map keyed by target name with an optional default fallback.

---
name: code-reviewer
model:
  claude: opus
  codex: gpt-5.5
  default: gpt-4o
---

Resolution per target: matching key wins, else default, else no model line is emitted (the CLI uses its own built-in default). An x-<target>.model override beats the map; x-<target>.model: null deletes it.

Skills

Two layouts:

Flat: skills/yaml-validator.md

Nested (for skills with attached resources):

skills/yaml-validator/SKILL.md
skills/yaml-validator/schema.yaml

Only SKILL.md and flat skills/*.md are parsed as skills. Every other file inside a nested skill directory (scripts, templates, fixtures, subdirectories, and extra *.md such as examples.md) is a bundled asset: it copies verbatim to the same relative location under each target's skills dir and is never promoted to its own skill. Ship a check.mjs, templates/*.tpl, or fixtures/*.json the skill body references. Executable bits are preserved both directions through import + sync.

---
name: yaml-validator
description: Validate YAML against a schema.
---

# YAML Validator

Zed skill names must use 1-64 lowercase letters or digits with single hyphens between segments. Zed sync rejects names such as `Deploy`, `my_skill`, and `my--skill` with an actionable error. Other targets retain their own naming rules.

## Steps
1. Read target file
2. Parse YAML
3. Compare against `schema.yaml`
4. Report violations as `path: message`

Emission by target:

• Native, one folder per skill at <dir>/<name>/SKILL.md, carrying bundled assets verbatim. Most targets. Several share one tree at .agents/skills/, so identical bytes dedupe instead of writing another on-disk copy.
• Flattened to a rule file (skill-<name>.md) on the few targets with no skill surface. Bundled assets cannot follow, so those raise a coverage note.
• Also as a slash command, opt-in per target via outputs.<target>.emit-skills-as-commands: true.

Which target does which, and the exact directory each reads, is the Skills row and cross-cutting bullet in targets — that list is kept current per change and this one is deliberately not a second copy of it.

Rules

---
name: conventional-commits
description: Always use Conventional Commits format.
globs: "**/*"
alwaysApply: true
---

Use `feat:`, `fix:`, `docs:`, etc. Subject under 72 chars.

Hooks

Pure YAML, no markdown body.

name: format-on-save
description: Run formatter after Edit/Write tools modify files.
event: PostToolUse
matcher: "Edit|Write"
command: "npx prettier --write \"$CLAUDE_FILE_PATHS\""

Tool-specific fields emit only where that tool's schema defines them; other targets ignore them. Scope non-command hooks with target or targets. Claude's stable handlers preserve timeout, statusMessage, if, and once; args, async, asyncRewake, and shell stay command-only. Cursor prompt hooks preserve matcher, timeout, loop_limit (including null), and failClosed. Kiro accepts x-kiro.action: {type: agent, prompt: ...} or {type: command, command: ...} without a generic command; the explicit action replaces a fallback command list and invalid overrides fail sync.

With none of the scoping fields set, the hook emits to every target that supports hooks. target takes precedence over targets when both appear. Exclude wins: a target in both an include and an exclude list is excluded.

These four scoping fields work on every spec kind (agents, skills, rules, commands, mcps), not only hooks. A target: codex agent emits only into .codex/agents/; a targets-exclude: [gemini] skill emits to every configured target except gemini.

Per-target body fences

When a spec emits to multiple targets but the prose must diverge (codex wants a "Workflow" section claude does not), wrap the divergent prose in ::target fences. Outside-fence content emits everywhere; inside-fence content emits only to the listed targets. Marker lines never reach the output.

---
name: test
description: Run the test suite
---

# Test

Shared intro paragraph.

::target claude
## Scope mapping (Claude)

| Changed | Command |
|---------|---------|
| ... | ... |
::end

::target codex
## Workflow (Codex)

1. Choose scope
2. Run `composer test`
::end

Shared outro.

• ::target <name> and ::targets <a> <b> open a fence pinned to one or more targets.
• ::end closes the most recent fence.
• An unterminated fence runs to end-of-body, so a missing ::end keeps the tail of the file.
• The empty target (the source view used by import round-trips) returns the body with fences intact, so a re-emit stays byte-stable.
• import codex builds these fences automatically when both tools ship the same agent or skill name with diverging bodies: the longest common prefix and suffix stay un-fenced, and each tool's unique middle gets its own ::target block.
• The same fences work in .agnostic-ai/AGNOSTIC_AI.md. A fenced block reaches an entry-point file when any target that reads the file is listed. AGENTS.md is read by the whole AGENTS.md family (codex, amp, warp, cline, ...), so ::target codex lands there and every reader of that file sees it. A shared file is never split. See Entry-point files.

Import auto-scoping

Hooks imported from a tool-native source auto-set target to that tool (codex import → target: codex, claude → target: claude, gemini → target: gemini). Remove the field by hand to let the hook flow everywhere.

event: PostToolUse
matcher: apply_patch|Edit|Write
command: "$(git rev-parse --show-toplevel)/.codex/hooks/format-php.sh"
target: codex   # shell-expanded codex path; do not leak to other tools

import claude and import codex apply the same auto-scoping to agents and skills: when both .claude/ and .codex/ exist but only one carries a given spec, the captured frontmatter gains target: <tool>. A spec present in both tools stays un-scoped (cross-emit). Pure single-tool projects also stay un-scoped, so byte-identical round-trips hold.

Supported events (Claude Code)

Claude Code defines more events (Setup, InstructionsLoaded, TaskCompleted, TeammateIdle, FileChanged, ...); the event: value passes through verbatim, so any documented name works. See the Claude Code hooks reference for the full list. Codex shares the SessionStart/SubagentStart/UserPromptSubmit/PreToolUse/PermissionRequest/PostToolUse/PreCompact/PostCompact/Stop/SubagentStop vocabulary.

Native emission: Claude Code (.claude/settings.json), Codex (.codex/hooks.json, per-event arrays), Gemini (.gemini/settings.json hooks), Cursor (.cursor/hooks.json, version + per-event arrays), Windsurf / Devin CLI (.devin/hooks.v1.json, no wrapper key, type accepting prompt as well as command), Factory (.factory/hooks.json, also no wrapper key, nine events, type always "command"), Kiro (.kiro/hooks/<name>.json, a {"version": "v1", "hooks": [...]} array), Qoder (.qoder/settings.json hooks, merged alongside mcpServers in the same file), OpenHands (.openhands/hooks.json, six events), Augment (.augment/settings.json hooks, merged alongside mcpServers in one write; five events; timeout in milliseconds, converted from this field's seconds; command must be a path ending in .sh/.ps1/.cmd/.bat, or it never runs), Crush (crush.json hooks, PreToolUse only, merged alongside mcp in the same file), Trae (.trae/hooks.json, the same integer {"version": 1, "hooks": {...}} wrapper around Claude-shaped {matcher, hooks: [...]} groups, six events, plus a loop_limit on Stop), Goose (.agents/plugins/agnostic-ai/hooks/hooks.json, with the required Open Plugins manifest beside it), and Copilot (.github/hooks/agnostic-ai.json, an integer {"version": 1, "hooks": {...}} wrapper, 14 events, command, HTTP, and sessionStart prompt handlers, timeoutSec; both PreToolUse and Copilot's own camelCase preToolUse are independently valid event-key spellings in that same file, so this one also passes event: through verbatim rather than picking one). Zed is opt-in: ordinary hooks become manual tasks, while WorktreeCreate maps to a task with hooks: ["create_worktree"]. Without outputs.zed.tasks-file, Zed raises a coverage note. Other targets log a warning and skip. Event names pass through verbatim, so a Cursor hook sets event: to a Cursor name (beforeShellExecution, afterFileEdit, beforeSubmitPrompt, sessionStart, stop, ...). See each tool's docs for its full event list and matcher semantics.

agnostic-ai emits the event: value verbatim into each target's schema; it does not translate event names between tools. Claude and Codex share the PreToolUse / PostToolUse / UserPromptSubmit vocabulary, so one hook spec feeds both. Gemini uses its own names (BeforeTool, AfterTool, BeforeAgent, AfterAgent, Notification, SessionStart, SessionEnd, PreCompress, BeforeModel, AfterModel, BeforeToolSelection), so a Gemini hook must set event: to one of those. agnostic-ai validate flags any event a target does not recognize.

Per-target rendering

This spec:

event: PostToolUse
matcher: Bash(git commit*)
command: echo "tests please"

Renders to .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash(git commit*)",
        "hooks": [
          {"type": "command", "command": "echo \"tests please\""}
        ]
      }
    ]
  }
}

Renders to .codex/hooks.json (same nested shape as Claude, routed into per-event arrays):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash(git commit*)",
        "hooks": [
          {"type": "command", "command": "echo \"tests please\""}
        ]
      }
    ]
  }
}

Gemini uses different event names, so a Gemini hook sets event: to one of its own. This spec:

event: AfterTool
matcher: run_shell_command
command: echo "tests please"

Renders to .gemini/settings.json (nested command handlers, event name passed through unchanged):

{
  "hooks": {
    "AfterTool": [
      {"matcher": "run_shell_command", "hooks": [{"type": "command", "command": "echo \"tests please\""}]}
    ]
  }
}

When command is a list, each entry becomes a separate handler (Claude, Codex, Gemini). Gemini keeps the handlers in one definition. Set x-gemini.sequential: true to run them in order. description reaches each handler; x-gemini.name sets its native display name, and x-gemini.env supplies per-handler environment variables.

Gemini hook imports preserve nested definitions and accept old flat files. A single handler imports with a timeout in seconds when exactly representable as a whole second; otherwise x-gemini.timeout retains the native milliseconds. A group with multiple handlers uses x-gemini.hooks, a native handler array that preserves each command, name, description, environment map, and millisecond timeout. This array replaces command emission for Gemini.

MCP servers

Pure YAML, no markdown body. One file per server.

name: filesystem
description: Local filesystem access for the model.
type: stdio
command: npx
args:
  - -y
  - "@modelcontextprotocol/server-filesystem"
env:
  ROOT: /tmp

The name is the server identifier, not the source filename. It can use package-style forward slashes, such as npm:@modelcontextprotocol/server-sequential.thinking. agnostic-ai percent-encodes slash-bearing names when it needs one YAML file per server, while the YAML name and every generated target config keep the original value. Other spec kinds still require one safe path segment because their names become output paths.

Factory HTTP/SSE servers accept oauth: false or an object containing scopes, resource, authorizationServerIssuer, clientId, clientSecret, clientMetadataUrl, tokenEndpointAuthMethod, and callbackPort. Kilo remote servers accept oauth: false; OAuth objects are not emitted there. Factory and Kilo preserve explicit zero timeouts. Use x-factory, x-kilo, or x-continue to override the corresponding top-level options for that target.

command and url are the two fields a server cannot work without, and agnostic-ai lint reports a missing one as an error (LINT008). Neither validate nor sync catches it: some targets drop the entry, the rest write a server object with no way to start or reach anything, and both do it silently. See lint.

Targets with native MCP propagation:

Aider, Cline, Jules, and Goose have no project-scoped MCP file and skip with a warning.

disabled support by target

Confirmed per target, never generalized: a target not listed here has not been checked.

tools support by target

Confirmed per target, never generalized: a target not listed here has not been checked. One tools: [Read, Bash] spec produces five different outcomes, so read this before assuming an allowlist restricts anything.

Every target that cannot honor the field says so at sync time. A silently dropped restriction is the failure this table and those notes exist to prevent: an author who writes tools: [Read] and gets an unrestricted agent has no way to notice.

color support by target

Confirmed per target, never generalized: a target not listed here has not been checked. color is a shared top-level key on three targets, and each documents its own value space, so a value valid on one may go unrecognized on another.

agnostic-ai writes color verbatim to whichever of these three targets an agent spec reaches; it does not validate the value against any target's vocabulary. color: blue is a valid ANSI name for Augment and one of Qoder's eight named values, but is neither hex nor a listed Kilo Code theme token, so it may not render there as intended (Kilo Code's "etc." leaves other tokens possible, not confirmed). An unrecognized value is cosmetic: the agent still runs, only the badge may not show the intended color.

Commands

Markdown with optional YAML frontmatter. Each spec becomes one native slash command on supported targets.

---
name: deploy
description: Deploy the app to staging.
argument-hint: <env>
---

Deploy the app to {{env}}.

1. Run tests.
2. Build artifacts.
3. Push to the {{env}} environment.

Any other frontmatter passes through unchanged. Use the x-<target> namespace for target-specific keys (e.g. x-claude.allowed-tools).

Native emission: Claude Code (.claude/commands/<name>.md), Cursor (.cursor/commands/<name>.md), Gemini (.gemini/commands/<name>.toml), OpenCode (.opencode/commands/<name>.md), Trae (.trae/commands/<name>.md), Junie (.junie/commands/<name>.md), Qoder (.qoder/commands/<name>.md), Kilo Code (.kilo/commands/<name>.md), Augment (.augment/commands/<scope>/<name>.md), and Factory (.factory/commands/<name>.md). Codex deprecated project prompts, so its commands emit only when outputs.codex.commands-dir is set; otherwise sync prints a coverage note. Amp has no file-based command surface at all (commands register programmatically via amp.registerCommand(...)), so, like other targets outside this list, it logs a warning and skips.

Settings

Pure YAML, one file per settings group under settings/. A tool-neutral place to single-source agent permissions and the default model instead of hand-editing each tool's settings file.

permissions:
  allow:
    - Bash(go test:*)
  deny:
    - Bash(rm:*)
  ask:
    - Bash(git push:*)
model: claude-opus-4-8

Multiple settings files merge: permission lists concatenate (de-duped, source order preserved); the last non-empty model wins.

Native emission: Claude Code (.claude/settings.json, permissions + model), Codex (.codex/config.toml, model), Copilot (.github/copilot/settings.json, model), Qoder (.qoder/settings.json, permissions + nested model.name), OpenCode (opencode.json, model), Junie (.junie/config.json, model), and Kilo Code (kilo.jsonc, model). Unrepresentable settings fields produce the normal coverage summary while supported fields still emit. Import for Copilot, OpenCode, Junie, Qoder, and Kilo creates settings/imported.yaml from portable fields and leaves target-only native keys in place.

When the Claude-specific outputs.claude.settings config in agnostic-ai.yaml also sets these fields, scalars like model take the config value (it is the more specific source), while permissions lists are unioned across the captured overlay, the settings spec, and the config so no layer silently drops another's allow/deny/ask rules.

import claude keeps permissions and model in the Claude-only overlay (.agnostic-ai/overlays/claude.settings.json), since a Claude model id does not necessarily port to other tools. Codex does the same through its config overlay. Imports from Copilot, OpenCode, Junie, Qoder, and Kilo write their portable fields to settings/imported.yaml, ready for cross-target sync. Review imported model identifiers before enabling more targets because vendors use different naming schemes. A settings spec's permissions still union with the imported Claude overlay on sync.

Reviews

Markdown with optional YAML frontmatter, one file per guidance group under reviews/. A single source for code-review-bot guidance that maps to each ecosystem's native review-rule file.

---
scope: backend
---

Flag any handler that talks to the database directly instead of going through a repository.

Review specs honor scope (and the source-directory layout) exactly like rules, so per-directory guidance is supported. Specs that share a scope concatenate into that scope's single review file.

Native emission: Cursor Bugbot uses .cursor/BUGBOT.md at the root and <scope>/.cursor/BUGBOT.md for scoped specs; outputs.cursor.review-file overrides the basename. Goose uses .agents/REVIEW.md and <scope>/.agents/REVIEW.md; outputs.goose.review-file overrides that scope-relative path. goose review combines instructions from changed-file directories and their ancestors. Both emit plain bodies without spec frontmatter. Other adapters report reviews as unsupported.

Environments

Pure YAML, one file per environment group under environments/. A single source for how a coding agent boots its dev env (install dependencies, start services, forward ports, open terminals).

install: go mod download
terminals:
  - name: dev
    command: go run ./cmd/agnostic-ai

Native emission: Cursor background-agent environment.json. The spec body is the .cursor/environment.json content: every key except the agnostic-ai routing fields (name, scope, target(s), target(s)-exclude, description) passes through verbatim, so you author Cursor's schema while agnostic-ai single-sources it. Multiple environment specs merge by top-level key (last wins). Override the path with outputs.cursor.environment-file.

Also native on OpenHands: the install field writes .openhands/setup.sh, the vendor's documented repository bootstrap script that "will run every time OpenHands begins working with your repository". The script body is install verbatim under a #!/bin/bash shebang. terminals has no OpenHands equivalent (the script runs once, synchronously; there is no long-running process surface) and surfaces a coverage note instead. Multiple environment specs merge the same way as Cursor's (last install wins). Override the path with outputs.openhands.setup-file.

Also native on Amp orbs: install writes an executable .agents/setup script, while each named terminal becomes a supervised service in .amp/services.yaml. Terminal fields after name pass through to the service, including Amp-specific fields supplied through x-amp.terminals. Service names must match Amp's lowercase, number, and hyphen rules, and each service requires command. Multiple environment specs merge by top-level key, last value wins. Override the paths with outputs.amp.setup-file and outputs.amp.environment-file. Amp's .agents/resume is not emitted: it runs after activation and every wake with thread credentials, which is distinct from dependency installation and supervised services.

Other targets (devcontainers, Codex setup scripts) have no emitter yet and report the spec as unsupported.

Ignore

Markdown with optional YAML frontmatter, one file per group under ignore/. The body is gitignore-syntax patterns naming what an agent must not read or index. One source fans out to each tool's native ignore file.

# Secrets and build artifacts the agent should never read
*.env
secrets/
dist/

Native emission (gitignore syntax, under a # provenance header): Cursor .cursorignore, Gemini .geminiignore, Aider .aiderignore, Windsurf .devinignore, Kiro .kiroignore, Trae .trae/.ignore, Junie .aiignore, Crush .crushignore, and Kilo .kilocodeignore (a compatibility input migrated into read/edit permission denials). Each spec keeps its pattern order and whitespace. Outer line breaks are trimmed, CRLF becomes LF, and the specs are concatenated with a blank line between them. Each path is overridable via outputs.<target>.ignore-file. Targets without an ignore-file convention report the spec as unsupported.

Overwrite behaviour

Sync replaces an ignore file without an agnostic-ai provenance header only when it can establish that existing exclusions survive. Every pattern must remain unchanged and in the same order. Extra exclusion patterns are allowed. Missing or reordered patterns, added negations (!pattern), and changed whitespace fail with AAI-103 and leave the file untouched. The comparison is conservative: equivalent spellings or harmless reorderings can still fail.

.kiroignore: hand-authored ignore file cannot be safely overwritten: existing
patterns are missing or reordered: "my-secrets/", "*.key". Run
`agnostic-ai import kiro` to copy its patterns into an ignore spec, then keep
their order and review any added negations before syncing again.

agnostic-ai import <target> reads the file into ignore/<target>.md, preserving comments, pattern order, and whitespace. Import removes a leading UTF-8 byte-order mark so the generated header does not turn it into a pattern character. Syncing unchanged imported patterns needs no manual cleanup. If other specs add negations or repeat the imported patterns in a different order, review the combined order before syncing. Already-generated files still regenerate from their specs, including intentional pattern removals.

Comment and blank lines exclude nothing, so a file holding only those never blocks a sync. A hash is a comment prefix only at the start of a line; leading spaces and tabs can be part of a pattern. outputs.<target>.provenance-header: false removes the marker used to recognize generated output and disables this check. Dry-run skips it because no file is written; sync --check still reports unsafe overwrites.

Frontmatter rules

• YAML between two --- lines at the top of the file.
• Empty (---\n---\n) is allowed and treated as no metadata.
• Files without frontmatter still load; name defaults to the filename.
• Malformed frontmatter is treated as no metadata; the entire content becomes the body.
• Any field not listed above passes through on emit. Useful for target-specific extensions.

Path variables: {{$NAME}}

A spec body can name a directory without hardcoding one target's layout. {{$SKILLS_DIR}} expands to .claude/skills for claude, .agents/skills for codex, and .github/skills for copilot, from one source file.

Put new skills in {{$SKILLS_DIR}} and agent profiles in {{$AGENTS_DIR}}.

Five variables are available:

Rules:

• Bodies only. Every spec kind that carries a body is expanded; frontmatter values are not.
• An outputs.<target>.<field> override wins. Set outputs.claude.skills-dir: custom/skills and {{$SKILLS_DIR}} follows it, so a body never names a directory the emitted tree does not use.
• A variable the target has no surface for stays verbatim and raises a coverage note. It is not blanked, because turning "see {{$COMMANDS_DIR}}" into "see " loses the sentence silently. Targets that carry every kind in one entry-point document (aider, jules) resolve no variables at all.
• A variable is declared only where the target has a dedicated surface for that kind. Several targets flatten agents into their rules directory with a filename prefix (continue, trae, windsurf) or render them as commands (gemini); those declare no {{$AGENTS_DIR}} rather than point at a directory that is not an agents directory. Antigravity, Goose, and OpenHands resolve it to .agents/agents.
• The $ sigil is required. Plain {{placeholder}} is left alone, so Warp workflow arguments and any Handlebars or Jinja quoted in prose survive untouched. Lowercase names ({{$skills_dir}}) do not resolve.

Target-specific extensions: x-<target> namespace

Use x-<target>: blocks to attach fields only one adapter consumes. Other adapters strip the block on emit, so the spec stays portable.

---
name: code-reviewer
description: Reviews diffs.
model: sonnet
x-claude:
  allowed-tools: [Read, Grep, Bash]
x-cursor:
  globs: "src/**"
  alwaysApply: false
---

Resolution per target:

• All x-* keys are dropped first.
• The matching x-<target> block is flattened into top-level meta.
• Flattened keys override top-level keys with the same name.

For Codex agents, x-codex fields (model, model_reasoning_effort, sandbox_mode, nickname_candidates) pass through to the generated .codex/agents/<name>.toml. For Codex skills, x-codex.interface, x-codex.policy, and x-codex.dependencies trigger an additional .agents/skills/<name>/agents/openai.yaml for UI customization, policy, and tool dependencies.

Arbitrary custom keys

Any other key under x-<target> emits verbatim into that target's output surface. Declaring it under x-<target> is the opt-in: shared top-level keys stay stripped, so plain specs keep emitting valid files. Keys emit in sorted order and never leak across targets. Validate them against the target's schema yourself.

Per surface:

Targets that emit no surface for a spec kind drop arbitrary custom keys (kiro rule steering files carry no passthrough; kiro agents, skills, and hooks do, see above). Gemini TOML accepts scalars and string arrays only; nested tables are skipped.