"Agent integration" can mean two different workflows. Choose the smallest one that fits: teach a local coding agent to call Crabbox, or run a repo-owned one-shot harness through normal execution.
crabbox init writes an Agent Skills-format document alongside repository
configuration and the optional Actions hydration workflow:
.agents/skills/crabbox/SKILL.md
crabbox init --detectThe skill uses the open Agent Skills specification,
including required name and description frontmatter. It tells a coding
agent when to warm and reuse a lease, run a command or detected job, inspect a
failure, and stop the lease.
Skill content is portable, but discovery directories are owned by each agent
client. The default .agents/skills path is the broad shared location, not a
universal one. When a repository must support a client with another project
path, repeat --skill and include both destinations during initialization; for
example, Claude Code uses .claude/skills:
crabbox init --detect \
--skill .agents/skills/crabbox/SKILL.md \
--skill .claude/skills/crabbox/SKILL.mdWhen at least one --skill is supplied, it replaces the implicit default, so
include .agents/skills/crabbox/SKILL.md explicitly when you want to retain
the shared copy. Crabbox requires every destination to be repository-relative
and end in crabbox/SKILL.md: the format requires the declared name to match
the directory containing SKILL.md.
The Agent Skills standard defines
SKILL.md, not a mandatory search path. Official client documentation was
audited on 2026-07-18 (pi on 2026-07-20); host behavior can change
independently of Crabbox.
| Client | Discovers the default .agents/skills path |
Notes |
|---|---|---|
| Codex CLI and IDE | Yes | Scans from the working directory through the repository root; use /skills or mention $crabbox. |
| Cursor | Yes | Also scans Cursor-, Claude-, and Codex-specific skill roots. |
| GitHub Copilot and VS Code | Yes | Also support .github/skills and .claude/skills. |
| Windsurf/Cascade | Yes | Also supports .windsurf/skills. |
| Devin | Yes | Discovers project skills from the repository root. |
| Zed Agent | Yes | The worktree must be trusted; use the slash command, @skill, or AI → Skills to verify discovery. |
| Gemini CLI | Yes, from the workspace root | Launch Gemini from the repository root, trust the workspace, then use /skills list or /skills reload. |
| Google Antigravity | Yes | .agent/skills is a legacy alternative. |
| OpenCode | Yes | Walks from the current directory to the worktree root; opencode debug skill shows the resolved inventory. |
| pi | Yes, from cwd through the git-repo root | Also scans the native .pi/skills project path and the global ~/.pi/agent/skills and ~/.agents/skills roots. Trust the workspace, then invoke with /skill:crabbox; slash-command invocation is gated by the enableSkillCommands setting, and --no-skills disables discovery. |
The same shared path is also documented by Roo Code, Amp, Warp, OpenHands, Letta, and Mistral Vibe. Goose supports it through its Summon extension.
These clients document a different native project path, so generate an additional copy when the repository needs one:
| Client | Documented project path |
|---|---|
| Claude Code | .claude/skills/crabbox/SKILL.md |
| Junie | .junie/skills/crabbox/SKILL.md |
| Kiro IDE and Kiro CLI | .kiro/skills/crabbox/SKILL.md; Kiro CLI custom agents must add the skill as an explicit skill:// resource |
| Qwen Code | .qwen/skills/crabbox/SKILL.md |
| Factory Droid | .factory/skills/crabbox/SKILL.md |
| Cline | .cline/skills/crabbox/SKILL.md (Cline's documented native path) |
Do not assume that every Agent Skills client scans .agents. Do not generate
every vendor path speculatively either: clients that scan multiple roots may
surface duplicate names, and their precedence rules are host-owned. Generate
only the paths the repository's contributors use, keep the copies identical,
and verify discovery in each host.
Review generated skills like any other repository automation. They provide
instructions; they do not grant credentials or bypass the agent host's command
approval and sandbox policy. See crabbox init and
Repository Onboarding.
The standards-compliant generated metadata is scheduled for Crabbox 0.40.0.
Released 0.39.0 binaries still emit a body-only skill; until upgrading, add the
required name and description frontmatter manually.
Crabbox also publishes its generic Skill at the non-hidden
skills/crabbox/SKILL.md ecosystem installer convention. This makes the
authoritative generic Skill visible to installers instead of requiring them to
search Crabbox's repo-local .agents projection.
GitHub CLI 2.90 or newer maps Agent Skills into many host-specific locations:
gh skill install openclaw/crabbox skills/crabbox \
--pin refs/heads/main --agent codex --scope projectReplace codex with the target reported by gh skill install --help. The
cross-client Skills CLI can install the same source and prompt for a target:
npx skills add https://github.com/openclaw/crabbox --skill crabboxThe generic source has an official-repository skills.sh
listing.
The checked-in skills/crabbox source and .agents/skills/crabbox projection
are byte-identical and CI rejects drift. Use crabbox init when the repository
also needs Crabbox configuration, Actions hydration, and detected project-job
instructions; use a skill manager when only agent discovery is missing.
--pin refs/heads/main selects this unreleased branch explicitly; after 0.40.0
is tagged, omit it to follow GitHub CLI's latest-release resolution.
The docs build publishes the same Skill with a content digest through Cloudflare's draft Agent Skills discovery protocol:
https://crabbox.sh/.well-known/agent-skills/index.jsonhttps://crabbox.sh/.well-known/agent-skills/crabbox/SKILL.md
The index declares the draft 0.2.0 schema and a SHA-256 digest of the exact
published SKILL.md. Clients that implement domain discovery can therefore
find and verify Crabbox without a GitHub-specific registry. After the next docs
deployment, the Skills CLI can consume the same endpoint directly:
npx skills add https://crabbox.sh --skill crabboxDomain discovery is an emerging transport, not part of the core Agent Skills format, so the checked-in installer source and host-native discovery paths remain the compatibility baseline.
For broader task-time discovery, the docs build also publishes a
specVersion: 1.0 AI Catalog
manifest at:
https://crabbox.sh/.well-known/ai-catalog.json
The catalog follows the draft Agentic Resource Discovery
specification, identifies the
artifact as application/agent-skills+md, and points to the same published
SKILL.md. It includes representative queries for remote testing,
cross-platform validation, and auditable evidence so ARD-compatible discovery
services can match Crabbox at task time. The site also advertises the catalog
through an HTML ai-catalog link and an Agentmap directive in robots.txt.
The ARD draft's examples and bundled conformance helper currently disagree on
older Skill media-type names. Crabbox follows the current AI Catalog integrated
ecosystem type, application/agent-skills+md.
AI Catalog and ARD add discovery metadata; they do not install, trust, or run the Skill. A client still decides whether to fetch and install the artifact, can verify its bytes against the adjacent Agent Skills index, applies its configured user or administrator approval, and executes Crabbox through its normal host policy.
The static site currently serves these files with GitHub Pages' conventional JSON and Markdown media types. That matches the ARD publisher quickstart, but a strict client that requires the AI Catalog vendor media types may skip the entry until crabbox.sh uses a header-capable serving layer.
For shell-capable coding agents, a concise skill preserves the complete CLI
instead of duplicating a changing subset of flags in one plugin per harness.
Repo-local jobs keep project commands and proof requirements reviewable in
.crabbox.yaml.
An MCP adapter may be useful later for clients without a shell or for a small typed workflow such as lease discovery, status, logs, and artifact retrieval. It should be local, use structured safety annotations, preserve the active repository as its working context, and avoid becoming a second unversioned CLI.
If a repository already owns a credential-free harness or evaluator script, run it like any other project command:
crabbox run -- ./scripts/agent-check.shFor a repeatable flow, declare a named job. On SSH-backed Linux providers, or a delegated adapter that advertises bounded artifact support, the job can also require and download proof artifacts. Crabbox owns remote execution and proof plumbing; the repository owns the harness protocol, prompts, role separation, and result interpretation.
Crabbox does not broker or deliver model credentials for this pattern. The
calling harness owns that security boundary; do not put model or tool secrets
in repository YAML, command arguments, or env.allow.
See Hermetic Agent Evidence for the implemented run-evidence pattern.