Skip to content

COMPATIBILITY.md

Latest commit

 

History

History
358 lines (273 loc) · 14.5 KB

COMPATIBILITY.md

File metadata and controls

358 lines (273 loc) · 14.5 KB
Raw

ACF — Multi-Agent Compatibility

This document explains how ACF (Agent Context Forge) is compatible with all major AI coding agents, how it complies with the Agent Skills specification, and how to install it into any supported agent's project.

Supported Agents

ACF is designed to be agent-agnostic. The skills are written as plain Markdown files with YAML frontmatter, following the Agent Skills specification. Any agent that loads skills from a local directory can consume ACF.

The following agents are explicitly supported:

Agent Vendor / Project Skill directory
Claude Code Anthropic .claude/skills/
Cursor Cursor .cursor/skills/
Codex CLI OpenAI .codex/skills/
OpenCode OpenCode (OSS) .opencode/skills/
OpenClaw OpenClaw (OSS) .agents/skills/
Devin Cognition .devin/skills/

Note on OpenClaw: OpenClaw uses a generic .agents/skills/ directory that is shared across agent runtimes that follow the common-agents convention. ACF installs into it the same way as the others.

MCP-Compatible Agents

For agents that do not support the SKILL.md skill format, ACF ships an MCP server that exposes the same pipeline as standard MCP tools over stdio (JSON-RPC 2.0). Any agent that speaks the Model Context Protocol can consume ACF this way — no skill loader required.

Agent MCP support ACF via MCP
Claude Desktop / Claude Code Yes (native) acf-mcp in mcpServers config
Continue Yes acf-mcp in Continue's MCP config
Zed Yes acf-mcp in Zed's MCP settings
GitHub Copilot (Copilot Chat) Yes (MCP support added 2025) acf-mcp in Copilot MCP config
Aider Yes (via MCP) acf-mcp in Aider's MCP config
Cursor Yes (also supports skills) acf-mcp as an alternative to skills
Codex CLI Yes (also supports skills) acf-mcp as an alternative to skills
OpenCode Yes (also supports skills) acf-mcp as an alternative to skills
Devin Yes (also supports skills) acf-mcp as an alternative to skills

The MCP server has zero Python dependencies (standard library only) and uses the gh CLI for GitHub operations. See mcp-server/README.md for installation and configuration.

MCP tools exposed

Tool ACF phase
acf_graph_scope 0 — dependency graph + blast radius
acf_context_load 1 — compressed context snapshot
acf_stack_audit 2 — orphan PRs, stale issues, close gaps
acf_issue_craft 3 — craft a contextualized issue
acf_pr_context 4 — build a PR body with issue context
acf_compact 7 — Kimi-inspired context compaction
acf_caveman 8 — extreme compression (<500 tokens)

The Agent Skills Specification (agentskills.io)

The Agent Skills specification defines a portable format for AI agent skills. A skill is a directory containing a SKILL.md file with:

  1. YAML frontmatter delimited by --- lines, containing:
    • name — a unique identifier, lowercase letters and hyphens only, maximum 64 characters.
    • description — a human-readable summary of what the skill does and when to use it, maximum 1024 characters.
  2. A Markdown body describing the skill's instructions, kept under 500 lines so it fits comfortably in an agent's context window.

How ACF Complies

Every ACF skill file follows this format:

  • Frontmatter present — every SKILL.md starts with a ----delimited YAML block containing name and description.
  • name convention — names are lowercase with hyphens (acf, context-load, stack-audit, issue-craft, pr-context, frontend-preview, label-metadata, compaction, caveman). The directory name uses a numeric prefix (01-context-load/) for ordering, while the name field inside the frontmatter is the bare skill name.
  • description length — descriptions are kept well under 1024 characters and include trigger phrases so the agent knows when to invoke the skill.
  • Body length — every skill body is under 500 lines.
  • Portable structure — each skill is a self-contained directory with a single SKILL.md, so it can be copied into any agent's skill folder.

You can verify compliance at any time by running:

./scripts/validate-skills.sh

This checks every SKILL.md in the repository against the rules above.

Installation Paths

Each agent loads skills from a specific directory inside the target project. ACF ships an orchestrator (acf/) plus 9 sub-skills (01-context-load/ through 09-graph-scope/). The installer copies all of them into the chosen agent's skill directory.

Agent Skill directory (relative to project root)
Devin .devin/skills/
Claude Code .claude/skills/
Cursor .cursor/skills/
Codex CLI .codex/skills/
OpenCode .opencode/skills/
OpenClaw .agents/skills/

After installation, the target project contains, for example:

.claude/skills/
├── acf/                  # Orchestrator
│   ├── SKILL.md
│   └── references/       # Progressive disclosure (loaded on demand)
│       ├── phase-details.md
│       ├── installation.md
│       └── compaction-tiers.md
├── 01-context-load/      # Phase 1
│   └── SKILL.md
├── 02-stack-audit/       # Phase 2
│   └── SKILL.md
├── 03-issue-craft/       # Phase 3
│   └── SKILL.md
├── 04-pr-context/        # Phase 4
│   └── SKILL.md
├── 05-frontend-preview/  # Phase 5
│   └── SKILL.md
├── 06-label-metadata/    # Phase 6
│   └── SKILL.md
├── 07-compaction/        # Phase 7
│   └── SKILL.md
├── 08-caveman/           # Phase 8
│   └── SKILL.md
└── 09-graph-scope/       # Phase 0
    └── SKILL.md

Using the Installer

The install.sh script at the repository root installs ACF into one or more agent directories in a target project.

Auto-detect (default)

Installs into every agent directory that already exists in the target project:

./install.sh /path/to/target-project

Install to all supported agents

Creates every supported agent directory if it does not exist and installs into all of them:

./install.sh /path/to/target-project --all

Install to a specific agent

Installs only into the named agent's directory (creating it if needed). Valid names: devin, claude, cursor, codex, agents, opencode.

./install.sh /path/to/target-project --agent claude

Properties

  • Idempotent — safe to re-run; existing files are overwritten in place.
  • Validates input — the target path must exist before anything is copied.
  • Exit codes — 0 on success, 1 on error.
  • Safe — uses set -euo pipefail and never touches repositories other than the target you specify.

Manual installation

If you prefer not to use the installer, you can copy the files directly:

# Orchestrator + all 9 sub-skills (skills/ is the source of truth)
cp -r skills/* /target-project/.claude/skills/

Repeat for each agent directory you want to populate.

The "Caveman" Naming: ACF vs OpenCode

Both ACF and OpenCode ship a skill called "caveman", and both share the spirit of extreme compression — reducing verbosity to the bare minimum. However, they operate on different sides of the agent's context window and do not collide with each other.

Aspect ACF caveman (phase 8) OpenCode caveman
Directory 08-caveman/ caveman/
What it compresses The input context snapshot The output model communication
Purpose Shrink the accumulated project context (architecture, stack, tests, CI) to under 500 tokens so the agent can keep working inside a small context budget. Shrink the agent's responses to a terse, telegraphic style to save output tokens and reduce noise.
When it triggers After context-load, when compaction (phase 7) is not enough and the token budget is critical. When the user or runtime requests maximally compressed output.
Direction Context → Agent (inbound) Agent → User/Runtime (outbound)

Because ACF uses the numeric-prefixed directory 08-caveman/ while OpenCode uses the bare caveman/ directory, no directory collision occurs when both are installed into the same project. An agent can load both skills simultaneously: ACF's caveman compresses what the agent reads, and OpenCode's caveman compresses what the agent writes.

See docs/COMPACTION.md for the full design notes on ACF's compaction (phase 7) and caveman (phase 8) modes.

Quick Reference: Agent → Path Table

Agent Skill directory Installer --agent name
Devin .devin/skills/ devin
Claude Code .claude/skills/ claude
Cursor .cursor/skills/ cursor
Codex CLI .codex/skills/ codex
OpenClaw .agents/skills/ agents
OpenCode .opencode/skills/ opencode

Compatibility Test Matrix

The following matrix tracks the verification status of ACF across all 6 supported agents. There are two dimensions:

  1. Skills discovered — can the agent find and load all 10 SKILL.md files after installation? This is automated and verified by scripts/test-compatibility.sh.
  2. Triggers correctly — does the agent actually invoke the orchestrator and sub-skills at the right moments based on the trigger phrases in each description field? This requires a live agent session and cannot be automated from the repository.
Agent Version Install path Skills discovered Triggers correctly Notes
Devin 0.3.0 .devin/skills/ PASS (automated) NEEDS HUMAN VERIFICATION Native agent; .devin/skills/ is the canonical mirror source
Claude Code 0.3.0 .claude/skills/ PASS (automated) NEEDS HUMAN VERIFICATION Claude.ai uploads limit descriptions to ~200 chars; orchestrator desc is 190 chars, compatible
Cursor 0.3.0 .cursor/skills/ PASS (automated) NEEDS HUMAN VERIFICATION Loads skills from .cursor/skills/; no known description length limit beyond the 1024-char spec
Codex CLI 0.3.0 .codex/skills/ PASS (automated) NEEDS HUMAN VERIFICATION OpenAI Codex CLI follows the agentskills.io spec; no known quirks
OpenClaw 0.3.0 .agents/skills/ PASS (automated) NEEDS HUMAN VERIFICATION Uses generic .agents/skills/ shared directory (common-agents convention)
OpenCode 0.3.0 .opencode/skills/ PASS (automated) NEEDS HUMAN VERIFICATION Ships its own caveman skill in caveman/ (bare dir); ACF uses 08-caveman/ — no collision

How to run the automated compatibility test

# Test all 6 agents (installs to a temp dir, verifies each):
bash scripts/test-compatibility.sh

# Test a single agent in a specific project:
bash scripts/test-compatibility.sh devin /path/to/project

# Run internal consistency checks (no install needed):
bash scripts/test-compatibility.sh --self-test

The automated tester verifies, for each agent:

  • The skill directory exists after installation
  • All 10 SKILL.md files are present (1 orchestrator + 9 sub-skills)
  • Every SKILL.md has parseable YAML frontmatter with name, description, and metadata.version fields
  • The references/ directory (progressive disclosure files) is installed alongside the orchestrator
  • All metadata.version fields match the repo's VERSION file

Per-agent notes

Devin (.devin/skills/)

Devin is the canonical development agent for ACF. The .devin/skills/ directory in the repository is the source mirror — install.sh copies from .devin/skills/acf/ (orchestrator) and skills/ (sub-skills) into the target. No known compatibility issues. All 10 skills install and validate cleanly.

Claude Code (.claude/skills/)

Claude Code loads skills from .claude/skills/ in the project root. When uploading skills to Claude.ai (the web interface), description fields are limited to approximately 200 characters. ACF's orchestrator description is 190 characters (measured after block-scalar folding), which is within the limit. All sub-skill descriptions are shorter. No truncation risk.

Cursor (.cursor/skills/)

Cursor follows the agentskills.io spec and loads skills from .cursor/skills/. No known description length restrictions beyond the 1024-character spec maximum. All 10 skills install and validate cleanly.

Codex CLI (.codex/skills/)

OpenAI's Codex CLI uses .codex/skills/ and follows the agentskills.io spec. No known quirks. All 10 skills install and validate cleanly.

OpenClaw (.agents/skills/)

OpenClaw uses the generic .agents/skills/ directory, following the common-agents convention. This directory may be shared across multiple agent runtimes. ACF installs into it identically to the other agents. No known compatibility issues.

OpenCode (.opencode/skills/)

OpenCode ships its own caveman skill in a bare caveman/ directory. ACF's caveman skill lives in 08-caveman/ (numeric-prefixed), so no directory collision occurs when both are installed in the same project. The two caveman skills serve different purposes (see The "Caveman" Naming section above). All 10 ACF skills install and validate cleanly alongside OpenCode's native skills.

Trigger verification protocol (for humans)

To complete the "triggers correctly" column for an agent, follow this protocol in a live session:

  1. Install ACF into a test project: ./install.sh /test-project --agent <name>
  2. Open the agent in the test project
  3. Issue a trigger phrase from the orchestrator description (e.g., "create an issue for...", "audit the stack", "scope this change")
  4. Verify the agent discovers and invokes the acf orchestrator skill
  5. Verify the orchestrator delegates to the appropriate sub-skill (e.g., context-load for context gathering)
  6. Record the result (PASS/FAIL) and any quirks in the matrix above

Trigger phrases are embedded in each skill's description frontmatter field. See the individual SKILL.md files for the exact phrases each skill responds to.