# AGENTS.md — AI Agent Contract **Purpose**: This file is the primary contract for any AI agent contributing to or working inside this repository. Read it before touching any file. --- ## What This Toolkit Does `agent-toolkit` is a modular library of AI capabilities — skills, agent personas, loop templates, MCP configs, and per-tool profiles — designed to work across every major AI coding assistant (Claude Code, Cursor, OpenCode, GitHub Copilot, Windsurf, Pi Coding Agent, Muse Code). The goal is a single source of truth: author a skill once, deploy it to any tool via its profile. When you add, modify, or remove anything here, you are affecting every downstream consumer who installs this toolkit. **Operate accordingly: be precise, cite sources, and validate before finalizing.** ## Desktop product work Before Desktop changes, read [the product vision](docs/desktop/PRODUCT_VISION.md), [UX architecture](docs/desktop/UX_ARCHITECTURE.md), [user journeys](docs/desktop/USER_JOURNEYS.md), [workflow coverage](docs/desktop/WORKFLOW_COVERAGE.md) and [visual QA](docs/desktop/VISUAL_QA.md). These distinguish the product contract from verified implementation. Preserve native V/gg/sokol, shared typed domain authority, workspace containment and real operational truth. Never invent production data or claim installation from state-only bookkeeping. Major UX changes require running the production application and opening captured screenshots before approval. Historical World View and ADR-032 requirements need reconciliation with this contract; do not implement old issue text without checking current code and tasks. --- ## Repository Structure ``` agent-toolkit/ ├── skills/ │ ├── core/ # Session bootstrap, handshake, workspace, project │ ├── delivery/ # PRD, ADR, work items, delivery workflows │ ├── design/ # UI/UX, Figma, frontend │ ├── forge/ # GitHub/GitLab CLI, CI, PRs, worktrees │ ├── integrations/ # Slack, Linear, ClickUp, MCP │ ├── data/ # dbt, Snowflake │ ├── tooling/ # Playwright, Jupyter, Herdr, inventory │ ├── ops/ # Triage, swarm, docs, cost │ ├── loops/ # loop-runner │ ├── agentic-security/ │ ├── architecture/ │ ├── cloud/ │ ├── accessibility/ │ └── quality/ ├── agents/ # Tool-agnostic agent persona definitions ├── profiles/ │ ├── claude-code/ # .claude/settings.json overlay + CLAUDE.md │ ├── cursor/ # .mdc rule files for Cursor │ ├── opencode/ # System prompt overlays for OpenCode │ ├── copilot/ # copilot-instructions.md for GitHub Copilot │ ├── windsurf/ # rules.md + memory files for Windsurf │ ├── pi/ # Skill files for Pi Coding Agent │ └── muse-code/ # Muse Code Agent Skills ├── mcp/ │ └── templates/ # MCP server config templates (JSON) ├── loops/ # Loop engineering templates (loop.yaml per docs/HOW_TO_CREATE_LOOP.md) │ └── / │ ├── loop.yaml # Required: loop definition (tier, cadence, goal, request, budget, allow/deny) │ ├── STATE.md # Runtime: checkpoint state (written by runner, not committed) │ └── report.md # Runtime: output report (written by agent, not committed) ├── packs/ # Docs-only solution packs (ADR-006) — workflow templates, not loaded by compiler ├── plugins/ # Compiler-generated target manifests (do not hand-edit; ADR-003/004) ├── distributions/ # Product specification for compiler input (products.yaml) ├── integrations/ # Swarm UI integrations (e.g., Herdr plugin; ADR-008) ├── catalogs/ │ ├── skill-catalog.yaml │ └── agent-catalog.yaml ├── schemas/ # JSON schemas for validation │ ├── skill-md-frontmatter.schema.json │ └── loop.schema.json ├── docs/ # Human-facing documentation │ ├── CONCEPTS.md # Public concept model — see "Three kinds of packs" │ └── adrs/ # Architecture Decision Records └── scripts/ # validate-skills.vsh, validate-agents.vsh, validate-loops.vsh, generate-catalogs.vsh (provenance.py kept) ``` --- ## Operating Rules **Always:** - Check `catalogs/skill-catalog.yaml` before adding a new skill — avoid duplicates - Validate with `./scripts/validate-skills.vsh` before marking any skill work complete - Cite which file a convention comes from when referencing repo standards - Use English for all file content, commit messages, and PR descriptions - Check `SKILL.md` frontmatter (`tools`, `requires`) before claiming a skill works with a tool - Keep secrets out of the repository — MCP templates use placeholder values only - When adding or modifying skills, follow [docs/SKILL_INTEGRATION_CHECKLIST.md](docs/SKILL_INTEGRATION_CHECKLIST.md) — orchestration, agents, products, and build verification are mandatory - When evaluating third-party skills, follow [docs/UPSTREAM_VS_FIRST_PARTY.md](docs/UPSTREAM_VS_FIRST_PARTY.md) — prefer first-party enhancement over duplicate upstream vendors **Never:** - Commit credentials, API keys, or tokens to any file - Claim a skill is compatible with a tool without testing or explicit authorship confirmation - Skip required `SKILL.md` frontmatter when adding a skill - Hand-edit generated catalogs (`skill-catalog.yaml`, `agent-catalog.yaml`, `loop-catalog.yaml`, `skills-layout.json`) — regenerate with `./scripts/generate-catalogs.vsh` only (see Catalog Generation) - Add content specific to any private organization — this is a public, vendor-neutral toolkit - Add third-party npm / github / url packs to `distributions/products.yaml` or `plugins/` — they belong in `agentic-workstation` via `chezmoiexternal` + `skills-external/` (see `docs/CONCEPTS.md` “Third-party boundary”) --- ## How to Add a Skill Each skill lives in its own directory under the appropriate domain: ``` skills/// └── SKILL.md # Human-readable description and usage guide (YAML frontmatter) ``` Skills use `SKILL.md` frontmatter only — no `skill.json` required. See `docs/MIGRATION.md` for historical notes on the v1.0.4 removal of `skill.json`. ### SKILL.md Frontmatter Spec Every `SKILL.md` must begin with a YAML frontmatter block: ```markdown --- name: my-skill-name description: One-sentence description of what this skill does. metadata: author: github-username version: "1.0.0" tags: - tag1 - tag2 domain: delivery # one of: accessibility, agentic-security, architecture, cloud, core, data, delivery, design, forge, integrations, loops, ops, quality, tooling --- # My Skill Name [Human-readable usage guide follows] ``` Required frontmatter fields: | Field | Type | Description | |---|---|---| | `name` | string | Kebab-case skill identifier, unique within the domain | | `description` | string | One sentence, present tense ("Reviews pull requests for…") | | `metadata.author` | string | GitHub username of the primary author | | `metadata.version` | string | Semver string, start at `"1.0.0"` | | `metadata.tags` | list | Searchable tags, lowercase kebab-case | | `metadata.domain` | string | Parent domain directory name | Optional frontmatter fields for tool compatibility and discovery: | Field | Type | Description | |---|---|---| | `tools` | list | AI tools this skill is verified to work with | | `requires` | list | CLI tools or env vars the skill needs | | `triggers` | list | Natural-language phrases that should invoke this skill | Run `./scripts/validate-skills.vsh` to validate frontmatter against `schemas/skill-md-frontmatter.schema.json`. ### Upstream vs first-party Before vendoring a third-party skill, read [docs/UPSTREAM_VS_FIRST_PARTY.md](docs/UPSTREAM_VS_FIRST_PARTY.md). If a first-party skill already covers the domain, **enhance it** and record `metadata.inspired_by[]` instead of adding a duplicate upstream copy. After any skill change, complete [docs/SKILL_INTEGRATION_CHECKLIST.md](docs/SKILL_INTEGRATION_CHECKLIST.md) (orchestration in `skills/core/assistant/references/ORCHESTRATION.md`, agent delegates, products, `build --check`). --- ## How to Add a Loop Template Loop templates are defined by `loops//loop.yaml` per `docs/HOW_TO_CREATE_LOOP.md` and `schemas/loop.schema.json`. The legacy `request.md`/`report.md`/`runbook.md` triple is historical — all loop definition now lives in `loop.yaml`; `STATE.md` and `report.md` are runtime artifacts, not committed. ### loop.yaml — Loop Definition ```yaml name: my-loop-name description: "Daily L1 read-only report (no mutations)" tier: L1 # L1 read-only, L2 PR-gated writes, L3 allowlisted merge/close cadence: 1d # \d+[mhd] e.g. 15m, 1d — see schemas/loop.schema.json goal: | One sentence describing the loop objective. The loop stops when this is achieved. allowlist: [] # permitted mutation actions (empty = read-only) deny: - merge - close - push - approve - force-push exit_conditions: - goal_met - budget_exhausted - human_escalation budget: max_tokens: 50000 # max tokens per run max_runs_per_day: 1 # max runs per 24h max_wall_seconds: 600 # hard timeout in seconds verifier: null # post-run quality gate agent, or null resumable: true # whether STATE.md checkpoints are written request: | [Full prompt body — self-contained, step-by-step instructions. Use {{variables}} for substitution.] ``` Required field: `name`, `goal`, `request` (per `schemas/loop.schema.json`). Common optional fields: `tier` (`L1`|`L2`|`L3`), `cadence` (`^\d+[mhd]$`), `allowlist`/`deny`, `exit_conditions` (`goal_met`, `budget_exhausted`, `human_escalation`, `max_iterations`, `no_work_found`, `error`), `budget` (`max_tokens`, `max_runs_per_day`, `max_wall_seconds`, `max_iterations`), `verifier`, `resumable`. See `docs/HOW_TO_CREATE_LOOP.md` for tier/budget guidance and resumability pattern. Validate before committing (same as CI `validate-loops` job): ```bash ./scripts/validate-loops.vsh ``` --- ## How to Add a Profile Profiles adapt toolkit skills for a specific tool. Each profile lives in `profiles//`. ### Claude Code (`profiles/claude-code/`) - `CLAUDE.md` — system prompt overlay referencing skills by path - `settings.json` — skill loading configuration ### Cursor (`profiles/cursor/`) - `rules/.mdc` — one rule file per domain, using Cursor's MDC format - Keep each rule file focused on one domain; avoid catch-all files ### OpenCode (`profiles/opencode/`) - `opencode.json` — system prompt that opencode loads on startup - `skills.yaml` — list of skill paths to inject ### GitHub Copilot (`profiles/copilot/`) - `copilot-instructions.md` — the file that gets copied to `.github/copilot-instructions.md` in projects - Must be self-contained (Copilot cannot reference external files at runtime) ### Windsurf (`profiles/windsurf/`) - `rules.md` — rules file that Windsurf loads from `~/.codeium/windsurf/` - `memories/` — optional pre-seeded memory files ### Pi Coding Agent (`profiles/pi/`) - `skills/.md` — individual skill files in Pi's expected format - Pi skills are standalone; each file must be self-contained --- ## Agent Persona Format Agent personas in `agents/` are a single `AGENT.md` with YAML frontmatter (no `persona.json` / `README.md` pair): ``` agents// └── AGENT.md # Frontmatter + persona body (optional references/) ``` `AGENT.md` frontmatter (match real `agents/*/AGENT.md`; validated by `scripts/validate-agents.vsh`): ```markdown --- name: persona-name description: >- What this persona does and when to use it. Use when: trigger keywords for agent selection. tools: Read, Grep, Glob, Bash --- # Persona title [Role description, operating rules, output format…] ``` | Field | Type | Description | |---|---|---| | `name` | string | Kebab-case; must match the directory name | | `description` | string | Selection text for the AI tool's agent picker | | `tools` | string | Comma-separated allowlist of tools the persona may use | Optional: `references/` beside `AGENT.md` for domain checklists. See [`docs/HOW_TO_ADD_AGENT.md`](docs/HOW_TO_ADD_AGENT.md). --- ## Catalog Generation `catalogs/skill-catalog.yaml`, `catalogs/agent-catalog.yaml`, `catalogs/loop-catalog.yaml`, and `catalogs/skills-layout.json` are **generated files**. Do not edit them by hand — regenerate with `generate-catalogs.vsh` only. `catalogs/skills-layout.json` is the domain → skill grouping derived from `skills///SKILL.md` and used by `agent-toolkit skills list` (`modules/agent_toolkit_core/skills.v`). To regenerate YAML catalogs after adding or modifying skills or agents: ```bash ./scripts/generate-catalogs.vsh # regenerate catalogs/*-catalog.yaml ./scripts/generate-catalogs.vsh --check # fail if committed catalogs drifted ``` The CI pipeline runs this automatically and will fail if the YAML catalogs are out of sync with the source files. --- ## Validation Before marking any contribution complete (see `.github/workflows/validate.yml` for CI parity): ```bash ./scripts/validate-skills.vsh # Validates SKILL.md frontmatter (no skill.json) ./scripts/validate-agents.vsh # Validates AGENT.md frontmatter ./scripts/validate-loops.vsh # Validates loops/**/loop.yaml against loop.schema.json ./scripts/generate-catalogs.vsh # Regenerates YAML catalogs (never hand-edit) ./make.vsh test && ./make.vsh build-cli AGENT_TOOLKIT_ROOT=$PWD ./build/agent-toolkit build --check # Adapter-only (optional unless changing PyPI/npm trampolines): AGENT_TOOLKIT_ROOT=$PWD uv run --project packages/pypi/agent-toolkit-cli --directory . pytest -c tests/pytest.ini tests/ -v npm test --prefix packages/npm/agent-toolkit-cli ``` All primary checks must exit 0. There is no `gen-surfaces` script — plugin digests are enforced by `build --check` only. V is the product CLI (pin `.v-version` / 0.5.2, `import json` not json2 — [`docs/HOW_TO_DEVELOP_V.md`](docs/HOW_TO_DEVELOP_V.md)). Run `uv sync --project packages/pypi/agent-toolkit-cli --all-extras` first for pytest only (the repo is not a uv workspace). --- ## Ecosystem — Where This Fits `agent-toolkit` is the **capability distribution layer (L1.5)** in a three-tier personal DX stack: ``` L1 │ agentic-workstation │ Machine provisioning (chezmoi, shell, packages, LLM policy) │ │ https://github.com/ulises-jeremias/agentic-workstation ────┼──────────────────────┼───────────────────────────────────────────────────────────── L1.5│ agent-toolkit │ THIS REPO — Capability distribution (skills, loops, profiles) │ (this repo) │ V binary: brew / AUR agent-toolkit-bin / GitHub / uv launcher / npm ────┼──────────────────────┼───────────────────────────────────────────────────────────── L3 │ agentic-harness │ AI workspace scaffold for multi-repo orchestration │ │ https://github.com/ulises-jeremias/agentic-harness ``` **Integration flow:** 1. `agentic-workstation` installs the V CLI during `chezmoi apply` (brew / AUR `agent-toolkit-bin` / GitHub / `uv tool install 'agent-toolkit-cli>=1.11.0'`) 2. `agent-toolkit install` deploys profiles to detected AI tools (Claude Code, Cursor, etc.) 3. `agentic-harness` workspaces call `agent-toolkit loop`, `agent-toolkit memory`, etc. --- ## CLI Reference for Agents When working in a workspace that has `agent-toolkit` installed, use these commands: ```bash # Installation (V binary — pick one channel; see docs/INSTALLATION.md) # brew tap ulises-jeremias/homebrew-tap && brew install agent-toolkit # yay -S agent-toolkit-bin # GitHub Release: agent-toolkit-- from /releases/latest uv tool install 'agent-toolkit-cli>=1.11.0' # PyPI launcher over bundled V agent-toolkit install [--force] # deploy profiles to detected AI tools agent-toolkit doctor # verify installation health # Skills and inventory agent-toolkit inventory # list all 116+ skills agent-toolkit skills list # list with domain breakdown agent-toolkit skills validate # check SKILL.md compliance # Knowledge base (from any workspace with knowledge/) agent-toolkit memory search "topic" # find existing knowledge agent-toolkit memory add --type learning "..." # save a pattern or discovery agent-toolkit memory add --type todo "..." # track a follow-up agent-toolkit memory inject # output knowledge for context agent-toolkit memory todo # review pending items # Loop engineering (from workspace with loops/ or templates/loops/) agent-toolkit loop init # scaffold from template agent-toolkit loop run # execute one iteration agent-toolkit loop status # show all loop instances agent-toolkit loop audit # review past runs agent-toolkit loop schedule # install systemd/launchd timer agent-toolkit loop templates # list available templates # Workspace management agent-toolkit workspace context # session state snapshot agent-toolkit workspace use-persona # activate a work mode agent-toolkit workspace load packs/.yaml # load client context bundle agent-toolkit workspace validate # validate workspace schemas # Project / repo management agent-toolkit project init # create repos/ + projects/ dirs agent-toolkit project clone owner/repo [--ssh] # clone + symlink agent-toolkit project list # list indexed projects # Background jobs agent-toolkit devcompanion queue --request "..." # queue async job agent-toolkit devcompanion run-once # process next job agent-toolkit devcompanion status # show queue state # MCP providers agent-toolkit mcp list # available providers agent-toolkit mcp setup # interactive MCP setup agent-toolkit mcp doctor # check provider health # Build and deploy agent-toolkit build --check # dry-run compilation agent-toolkit build --target claude-code # compile one target agent-toolkit diff # show changes vs installed bundles ``` --- ## Cross-Repo Links - **agentic-workstation** → [`AGENTS.md`](https://github.com/ulises-jeremias/agentic-workstation/blob/main/AGENTS.md) | [`docs/AGENT_TOOLKIT.md`](https://github.com/ulises-jeremias/agentic-workstation/blob/main/docs/AGENT_TOOLKIT.md) - **agentic-harness** → [`AGENTS.md`](https://github.com/ulises-jeremias/agentic-harness/blob/main/AGENTS.md) | [`docs/ARCHITECTURE.md`](https://github.com/ulises-jeremias/agentic-harness/blob/main/docs/ARCHITECTURE.md)