Skip to content

AGENTS.md

Latest commit

 

History

History
84 lines (62 loc) · 6.87 KB

AGENTS.md

File metadata and controls

84 lines (62 loc) · 6.87 KB
Raw

Agents, skills, and commands for seven coding tools

The repository provides 94 plugins (92 local + 2 external), 202 agents, 185 skills, and 105 commands for seven coding tools: Claude Code, OpenAI Codex CLI, Cursor, OpenCode, Google Antigravity CLI (agy), GitHub Copilot, and Pi. Shared source files use the Claude Code format, and adapters provide the formats used by other tools. External entries have their own tool support.

AGENTS.md is the canonical context file. Codex, Cursor, OpenCode, Antigravity CLI, GitHub Copilot, and Pi read it directly. Claude Code reads it via CLAUDE.md, a symlink to this file.

Read this file like a table of contents. Detail lives in docs/. Authoring conventions live in docs/authoring.md. Per-harness setup and capability deltas live in docs/harnesses.md. This file should never grow beyond ~150 lines (per OpenAI's harness-engineering practice).

Map

Working in this repo

  • Python tooling: uv (package manager), ruff (lint/format), ty (type check). Do not use pip / mypy / black.
  • Plugins live under plugins/<name>/ with auto-discovery — see docs/authoring.md for frontmatter shapes.
  • Plugin names: lowercase, hyphen-separated. Never use __ (it's the adapter namespace separator).
  • Never commit secrets. Never run destructive git (force-push, reset --hard, branch -D) without explicit ask.

Quality gates (run these before pushing)

make validate STRICT=1     # structural validation across all harness outputs
make garden                # drift detection (dead links, stale artifacts, oversize skills)
make test                  # full pytest suite (plugin-eval + tools/tests/)
make smoke-test            # real-CLI subprocess tests against generated artifacts

CI (.github/workflows/validate.yml) runs all four on every PR plus installs OpenCode + Antigravity CLI + Pi for live verification.

Regenerating per-harness artifacts

make generate HARNESS=codex        # .codex/skills, .codex/agents, .codex/plugins/<p>/, .agents/plugins/marketplace.json
make generate HARNESS=cursor       # .cursor-plugin/{marketplace,plugin}.json, .cursor/rules/
make generate HARNESS=opencode     # .opencode/{skills,agents,commands,plugins}/, opencode.json
make generate HARNESS=antigravity  # .antigravity/plugins/<p>/
make generate HARNESS=copilot      # .copilot/{skills,agents,commands}/
make generate HARNESS=pi           # .pi/{skills,prompts,agents}/
make generate-all                  # every harness

Small native-install registries are committed for tools that support that route. See the installation commands in docs/harnesses.md. The transformed skill and agent trees under .codex/, .opencode/, .copilot/, .antigravity/ and .pi/ stay gitignored and are rebuilt locally. Under .pi/ the generator owns only skills/, prompts/ and agents/, because Pi reads its own project config from the same directory. Run make generate-all before committing source changes. It also prunes artifacts whose source was removed, and CI fails on drift. Source files live only under plugins/. Never hand-edit generated files.

Skills (cross-harness)

185 skills under plugins/*/skills/<n>/SKILL.md — discoverable by every harness:

  • Claude Code: auto-discovery via Anthropic's SKILL.md spec
  • Codex CLI: mirrored to .codex/skills/<plugin>__<skill>/ (8 KB body cap; detail in references/details.md)
  • OpenCode: mirrored to .opencode/skills/<plugin>-<skill>/ using hyphenated names for global install
  • Cursor: reads .claude/skills/ directly (no re-emit)
  • Antigravity CLI: native plugins at .antigravity/plugins/<p>/ — bare skills/<skill>/SKILL.md (no <plugin>__ namespacing; the plugin dir already scopes it)
  • GitHub Copilot: mirrored to .copilot/skills/<plugin>__<skill>/. Commands also become user-invocable skills.
  • Pi: mirrored to .pi/skills/<plugin>/<skill>/; discovery is recursive so names stay bare
  • Skills-only installers: gh skill install wshobson/agents and npx skills add wshobson/agents read plugins/*/skills/ from GitHub directly (see docs/harnesses.md); make smoke-test runs both plus the agentskills.io spec check

Subagents (cross-harness)

202 subagents under plugins/*/agents/<name>.md. Per-harness transpilation:

  • Codex: .codex/agents/<plugin>__<agent>.toml (drop tools:, map model alias to the GPT-5.x family, infer sandbox_mode)
  • OpenCode: .opencode/agents/<plugin>__<agent>.md with mode: subagent + permission: block (locked agents — those with source tools: [] — get deny-everything except base skill/task)
  • Antigravity CLI: .antigravity/plugins/<p>/agents/<agent>.md (Markdown + YAML frontmatter, model: is a tier alias — inherit/flash/pro); TOML commands at commands/<p>/<cmd>.toml (agy reports these as "converted to skills"); global install via make install-antigravity symlinks each plugin into ~/.gemini/config/plugins/
  • GitHub Copilot: .copilot/agents/<plugin>__<agent>.agent.md profiles with translated tool names and Claude model IDs.
  • Pi: .pi/agents/<plugin>__<agent>.md in the reference subagent extension's format (name, description, tools, model); commands become prompt templates at .pi/prompts/<plugin>__<cmd>.md
  • Cursor: reads .claude/agents/ directly

Why this file is short

Per OpenAI's harness-engineering practice: this file is a map, not an encyclopedia. Procedural detail lives in skills (loaded on demand by agents). Reference material lives in docs/ (loaded when an agent navigates). A single bloated AGENTS.md crowds out the task, rots quickly, and is hard to verify mechanically. Keep it lean; push detail elsewhere.