chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
@@ -0,0 +1,144 @@
|
||||
# Antigravity CLI (`agy`) target spec
|
||||
|
||||
Status: spike findings, verified empirically against `agy` v1.0.10 on macOS (2026-06-22). This
|
||||
documents the Antigravity CLI plugin format so a `claude-to-antigravity` converter target can be
|
||||
built. It supersedes `docs/specs/gemini.md` for new work; Gemini CLI is being removed as a target.
|
||||
|
||||
## Background
|
||||
|
||||
Google replaced the consumer Gemini CLI with **Antigravity CLI** (binary `agy`), a Go-based terminal
|
||||
agent that still runs on Gemini models. It is a distinct CLI with its own install model, plugin
|
||||
format, and permission system -- not a rename of `gemini`. Per public reporting, consumer Gemini CLI
|
||||
access (free / AI Pro / Ultra) was cut off ~2026-06-18 while enterprise Gemini Code Assist and paid
|
||||
API-key access continue; this repo's decision is to remove the Gemini target entirely and target
|
||||
Antigravity instead.
|
||||
|
||||
All facts below were verified by building a fixture plugin and running `agy plugin validate` /
|
||||
`agy plugin install` / `agy plugin list` / `agy plugin uninstall`, not from documentation
|
||||
(antigravity.google/docs renders client-side and is not machine-readable).
|
||||
|
||||
## Install model (user-facing)
|
||||
|
||||
`agy` installs a plugin from a **local directory** or a **remote Git repository URL** when the source contains a root `plugin.json`:
|
||||
|
||||
```bash
|
||||
agy plugin install https://github.com/EveryInc/compound-engineering-plugin
|
||||
```
|
||||
|
||||
Local checkout (repository root or bundled `.agy/` entry point):
|
||||
|
||||
```bash
|
||||
git clone https://github.com/EveryInc/compound-engineering-plugin
|
||||
agy plugin install ./compound-engineering-plugin
|
||||
agy plugin install ./compound-engineering-plugin/.agy # equivalent via symlinked manifest
|
||||
```
|
||||
|
||||
- `agy plugin install <target>` requires `<target>` to be a directory containing a `plugin.json` at
|
||||
its root (`agy plugin validate .` fails with "missing plugin.json" otherwise), or a remote Git URL
|
||||
whose root contains `plugin.json`.
|
||||
- `agy plugin install <plugin>@<marketplace>` exists for marketplaces; Antigravity does not yet
|
||||
ship a curated marketplace catalog equivalent to Kimi's `.kimi-plugin/marketplace.json`.
|
||||
- `agy plugin import [gemini|claude]` imports an existing Gemini-CLI / Claude install; on this machine
|
||||
`agy plugin list` showed `compound-engineering` already imported with `source: gemini-cli`.
|
||||
- Other subcommands: `list`, `uninstall <name>`, `enable <name>`, `disable <name>`, `validate [path]`,
|
||||
`link <mp> <target>`.
|
||||
|
||||
Compound Engineering publishes root `plugin.json` plus `skills/` so remote Git install works without
|
||||
a clone step. The committed `.agy/` bundle holds a symlinked manifest (`plugin.json -> ../plugin.json`)
|
||||
and `skills -> ../skills` for explicit local `.agy` installs.
|
||||
|
||||
See `.agy/INSTALL.md` for pinning, validation, and uninstall.
|
||||
|
||||
Installed/imported plugins are tracked in an internal registry surfaced by `agy plugin list --json`
|
||||
(not a readable `plugins/` directory tree). Each entry records `name`, `source`
|
||||
(`antigravity` | `gemini-cli` | `claude`), `importedAt`, and the `components` recognized.
|
||||
|
||||
## Plugin layout (what the converter must emit)
|
||||
|
||||
```
|
||||
<plugin-root>/
|
||||
plugin.json # required manifest, at root
|
||||
skills/<name>/SKILL.md # skills (SKILL.md with YAML frontmatter)
|
||||
agents/<name>.md # subagents (markdown + frontmatter)
|
||||
commands/<name>.{toml,md} # commands -- CONVERTED TO SKILLS on install/import
|
||||
mcp_config.json # MCP servers (root file)
|
||||
hooks.json # hooks (root file)
|
||||
```
|
||||
|
||||
`agy plugin validate` reports each section as `processed` or `skipped (not found)`, so all component
|
||||
dirs/files are optional and discovered by convention.
|
||||
|
||||
### `plugin.json`
|
||||
|
||||
Minimal valid manifest (verified):
|
||||
|
||||
```json
|
||||
{ "name": "compound-engineering", "version": "0.0.0" }
|
||||
```
|
||||
|
||||
- `name` and `version` are sufficient to validate. `description` and other fields are optional and
|
||||
were not required by the validator. (Version is release-owned in this repo -- see release notes.)
|
||||
|
||||
### Skills
|
||||
|
||||
- `skills/<name>/SKILL.md` with standard YAML frontmatter (`name`, `description`). Same SKILL.md
|
||||
contract already used by the Claude/Gemini surfaces -- skills appear to port directly.
|
||||
|
||||
### Agents (subagents)
|
||||
|
||||
- `agents/<name>.md`, markdown with frontmatter (`name`, `description`). One `.md` per agent.
|
||||
|
||||
### Commands -> skills
|
||||
|
||||
- `commands/<name>.toml` and `commands/<name>.md` both validate and are reported as
|
||||
**"converted to skills"**. Antigravity has no separate runtime command primitive; commands become
|
||||
skills on install. Converter implication: we can emit commands as skills directly rather than
|
||||
shipping a command format.
|
||||
|
||||
### MCP servers (`mcp_config.json`)
|
||||
|
||||
Root file shaped `{ "mcpServers": { "<name>": { ... } } }`. Verified field names:
|
||||
|
||||
- **stdio server:** `{ "command": "...", "args": [...] }`
|
||||
- **remote server:** `{ "serverUrl": "https://..." }` -- NOT `url` and NOT `httpUrl`.
|
||||
Validator error for the wrong key: `MCP server "<name>" must have either command or serverUrl`.
|
||||
|
||||
Converter implication: map the Gemini/Claude remote-MCP `url` field to `serverUrl`.
|
||||
|
||||
### Hooks (`hooks.json`)
|
||||
|
||||
Root file shaped `{ "hooks": { ... } }`. A `{ "hooks": { "PreToolUse": [] } }` shape validates
|
||||
(top-level container confirmed). The per-event hook schema (matchers, command shape, event names
|
||||
beyond `PreToolUse`) was NOT exhaustively verified in this spike and must be confirmed before
|
||||
emitting real hooks.
|
||||
|
||||
## Permissions / interactive question tool
|
||||
|
||||
- `agy` gates tool execution via TUI permission prompts (`/permissions` slash command and a
|
||||
`toolPermission` setting: `always-proceed` | `request-review` | `strict` | `proceed-in-sandbox`),
|
||||
plus `permissions` allow/deny/ask rules in settings -- not a Gemini-CLI-style `ask_user` tool.
|
||||
- The interactive blocking-question tool exposed to agents is **`ask_question`** (confirmed in live
|
||||
usage). Plugin skill prose that lists per-harness blocking-question tools should use
|
||||
`ask_question` for Antigravity (this was applied in the Wave 1 skill sweep).
|
||||
|
||||
## Context files
|
||||
|
||||
- `agy` still reads `GEMINI.md` (workspace) and `AGENTS.md` as context. `GEMINI.md` is therefore
|
||||
retained even though the Gemini *converter target* is removed. Google may later consolidate this
|
||||
into `AGENTS.md`; treat that as TBD.
|
||||
|
||||
## Settings (reference)
|
||||
|
||||
Global settings live at `~/.gemini/antigravity-cli/settings.json` (keys observed in the bundled CLI
|
||||
guide include `permissions`, `toolPermission`, `trustedWorkspaces`, model, sandbox, status line).
|
||||
Builtin skills ship under `~/.gemini/antigravity-cli/builtin/skills/`.
|
||||
|
||||
## Open questions for implementation
|
||||
|
||||
- Exact `hooks.json` per-event schema (matcher/command shape, supported event names).
|
||||
- Whether `agy plugin install` supports a monorepo subdirectory or only a root `plugin.json`.
|
||||
- Whether a generated root `plugin.json` (vs `.claude-plugin/plugin.json`) is the right emission
|
||||
target, and how it coexists with the existing Claude/Codex manifests at the repo root.
|
||||
**Resolved for CE:** root `plugin.json` is the Antigravity manifest; `.agy/plugin.json` symlinks to it.
|
||||
- Marketplace (`<plugin>@<marketplace>`, `agy plugin link`) distribution — deferred until Antigravity
|
||||
documents a stable catalog schema (unlike Kimi's `.kimi-plugin/marketplace.json`).
|
||||
@@ -0,0 +1,67 @@
|
||||
# Claude Code Plugin Spec
|
||||
|
||||
Last verified: 2026-01-21
|
||||
|
||||
## Primary sources
|
||||
|
||||
```
|
||||
https://docs.claude.com/en/docs/claude-code/plugins-reference
|
||||
https://docs.claude.com/en/docs/claude-code/hooks
|
||||
https://docs.claude.com/en/docs/claude-code/slash-commands
|
||||
https://docs.claude.com/en/docs/claude-code/skills
|
||||
https://docs.claude.com/en/docs/claude-code/plugin-marketplaces
|
||||
```
|
||||
|
||||
## Plugin layout and file locations
|
||||
|
||||
- A plugin root contains `.claude-plugin/plugin.json` and optional default directories like `commands/`, `agents/`, `skills/`, `hooks/`, plus `.mcp.json` and `.lsp.json` at the plugin root. citeturn2view7
|
||||
- The `.claude-plugin/` directory only holds the manifest; component directories (commands/agents/skills/hooks) must be at the plugin root, not inside `.claude-plugin/`. citeturn2view7
|
||||
- The reference table lists default locations and notes that `commands/` is the legacy home for skills; new skills should live under `skills/<name>/SKILL.md`. citeturn2view7
|
||||
|
||||
## Manifest schema (`.claude-plugin/plugin.json`)
|
||||
|
||||
- `name` is required and must be kebab-case with no spaces. citeturn2view8
|
||||
- Metadata fields include `version`, `description`, `author`, `homepage`, `repository`, `license`, and `keywords`. citeturn2view8
|
||||
- Component path fields include `commands`, `agents`, `skills`, `hooks`, `mcpServers`, `outputStyles`, and `lspServers`. These can be strings or arrays, or inline objects for hooks/MCP/LSP. citeturn2view8turn2view9
|
||||
- Custom paths supplement defaults; they do not replace them, and all paths must be relative to the plugin root and start with `./`. citeturn2view9
|
||||
|
||||
## Commands (slash commands)
|
||||
|
||||
- Command files are Markdown with frontmatter. Supported frontmatter includes `allowed-tools`, `argument-hint`, `description`, `model`, and `disable-model-invocation`, each with documented defaults. citeturn6search0
|
||||
|
||||
## Skills (`skills/<name>/SKILL.md`)
|
||||
|
||||
- Skills are directories containing `SKILL.md` (plus optional support files). Skills and commands are auto-discovered when the plugin is installed. citeturn2view7
|
||||
- Skills can be invoked with `/<skill-name>` and are stored in `~/.claude/skills` or `.claude/skills` (project-level); plugins can also ship skills. citeturn12view0
|
||||
- Skill frontmatter examples include `name`, `description`, and optional `allowed-tools`. citeturn12view0
|
||||
|
||||
## Agents (`agents/*.md`)
|
||||
|
||||
- Agents are markdown files with frontmatter such as `description` and `capabilities`, plus descriptive content for when to invoke the agent. citeturn2view7
|
||||
|
||||
## Hooks (`hooks/hooks.json` or inline)
|
||||
|
||||
- Hooks can be provided in `hooks/hooks.json` or inline via the manifest. Hooks are organized by event → matcher → hook list. citeturn2view7
|
||||
- Plugin hooks are merged with user and project hooks when the plugin is enabled, and matching hooks run in parallel. citeturn1search0
|
||||
- Supported events include `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `UserPromptSubmit`, `Notification`, `Stop`, `SubagentStart`, `SubagentStop`, `Setup`, `SessionStart`, `SessionEnd`, and `PreCompact`. citeturn2view7
|
||||
- Hook types include `command`, `prompt`, and `agent`. citeturn2view7
|
||||
- Hooks can use `${CLAUDE_PLUGIN_ROOT}` to reference plugin files. citeturn1search0
|
||||
|
||||
## MCP servers
|
||||
|
||||
- Plugins can define MCP servers in `.mcp.json` or inline under `mcpServers` in the manifest. Configuration includes `command`, `args`, `env`, and `cwd`. citeturn2view7turn2view10
|
||||
- Plugin MCP servers start automatically when enabled and appear as standard MCP tools. citeturn2view10
|
||||
|
||||
## LSP servers
|
||||
|
||||
- LSP servers can be defined in `.lsp.json` or inline in the manifest. Required fields include `command` and `extensionToLanguage`, with optional settings for transport, args, env, and timeouts. citeturn2view7turn2view10
|
||||
|
||||
## Plugin caching and path limits
|
||||
|
||||
- Claude Code copies plugin files into a cache directory instead of using them in place. Plugins cannot access paths outside the copied root (for example, `../shared-utils`). citeturn2view12
|
||||
- To access external files, use symlinks inside the plugin directory or restructure your marketplace so the plugin root contains shared files. citeturn2view12
|
||||
|
||||
## Marketplace schema (`.claude-plugin/marketplace.json`)
|
||||
|
||||
- A marketplace JSON file lists plugins and includes fields for marketplace metadata and a `plugins` array. citeturn8view2
|
||||
- Each plugin entry includes at least a `name` and `source` and can include additional manifest fields. citeturn8view2
|
||||
@@ -0,0 +1,80 @@
|
||||
# Cline Spec (Skills and CLI Plugins)
|
||||
|
||||
Last verified: 2026-06-30
|
||||
|
||||
## Primary sources
|
||||
|
||||
```
|
||||
https://docs.cline.bot/customization/skills
|
||||
https://docs.cline.bot/customization/plugins
|
||||
https://docs.cline.bot/sdk/plugin-install
|
||||
```
|
||||
|
||||
## Skills (primary CE install surface)
|
||||
|
||||
Cline skills follow the open [Agent Skills](https://agentskills.io) standard. Each skill is a directory containing `SKILL.md` with YAML frontmatter (`name`, `description`). Cline activates skills on demand via its `use_skill` tool when a request matches the skill description.
|
||||
|
||||
Skills is an experimental feature in the VS Code, Cursor, and JetBrains extensions. Enable it in **Settings -> Features -> Enable Skills** before CE skills appear.
|
||||
|
||||
### Discovery paths
|
||||
|
||||
| Scope | Path |
|
||||
| --- | --- |
|
||||
| Project (recommended) | `.cline/skills/<name>/` |
|
||||
| Project (alternate) | `.clinerules/skills/<name>/` |
|
||||
| Global (macOS/Linux) | `~/.cline/skills/<name>/` |
|
||||
| Global (Windows) | `C:\Users\USERNAME\.cline\skills\<name>\` |
|
||||
|
||||
When a global skill and project skill share the same name, the global skill takes precedence.
|
||||
|
||||
CE ships skills at `./skills/<name>/SKILL.md` in this repository. Compound Engineering does **not** copy skills into a generated tree for Cline; users link the repository's invocable skill directories into one of the discovery paths above.
|
||||
|
||||
### Manual-only skills
|
||||
|
||||
Some CE skills set `disable-model-invocation: true` in frontmatter so Claude and Codex do not auto-invoke them (for example `lfg`, `ce-dogfood`, `ce-polish`, `ce-setup`). Cline has no equivalent flag — it auto-activates skills when descriptions match — so `.cline/scripts/install-skills.sh` **skips** manual-only skills by default. Default reruns remove only stale symlinks whose target resolves under this checkout's `skills/` directory. Re-run with `--include-manual` to link them for slash-command use; Cline may still auto-activate those skills when descriptions match.
|
||||
|
||||
## CLI plugins (secondary, not required for CE)
|
||||
|
||||
Cline CLI and SDK support `AgentPlugin` entry points installed with `cline plugin install` from git, npm, or local paths. That surface is for custom tools, hooks, and lifecycle extensions — not for loading `SKILL.md` bundles.
|
||||
|
||||
CE workflows are skills-first. This repo does not ship a Cline CLI plugin entry point because CE's value is the skill orchestration layer, which the skills install path covers for both the extension and the CLI.
|
||||
|
||||
## Instruction files
|
||||
|
||||
Cline reads project context from Cline rules and standard instruction files. This repository's canonical project instruction file is root `AGENTS.md`. CE skills reference "the project's active instructions and conventions already in your context" rather than hardcoding harness-specific filenames.
|
||||
|
||||
Do not add a root `CLINE.md` compatibility shim unless Cline documents support for that filename.
|
||||
|
||||
## Install commands
|
||||
|
||||
Global skills from a checkout:
|
||||
|
||||
```bash
|
||||
/path/to/compound-engineering-plugin/.cline/scripts/install-skills.sh --global
|
||||
```
|
||||
|
||||
Project-scoped skills from a checkout:
|
||||
|
||||
```bash
|
||||
/path/to/compound-engineering-plugin/.cline/scripts/install-skills.sh --project
|
||||
```
|
||||
|
||||
Manual-only skills (for example `lfg`, `ce-polish`) require the opt-in flag:
|
||||
|
||||
```bash
|
||||
/path/to/compound-engineering-plugin/.cline/scripts/install-skills.sh --global --include-manual
|
||||
```
|
||||
|
||||
After installing or updating skills, start a new Cline task so the skill list refreshes.
|
||||
|
||||
## Update and removal
|
||||
|
||||
Re-run the install script after pulling a newer CE release. It creates or replaces only CE-owned symlinks (those resolving under this checkout's `skills/` tree) and leaves an existing `<name>` symlink pointing at a user skill, fork, or other checkout untouched, mirroring the user-managed-symlink preservation the OpenCode/Codex/Pi writers apply.
|
||||
|
||||
To remove CE skills, delete the symlinks (or directories) named after CE skill ids (`ce-brainstorm`, `ce-plan`, etc.) from `~/.cline/skills/` or `.cline/skills/`.
|
||||
|
||||
## Subagent and tool notes
|
||||
|
||||
CE skills dispatch generic subagents with skill-local prompt assets under `references/agents/` and `references/personas/`. Cline's subagent and MCP capabilities vary by host (extension vs CLI). Skills degrade gracefully when a primitive is unavailable — the same cross-harness posture used for OpenCode and Pi.
|
||||
|
||||
Bundled shell scripts in skills use the model-filled `SKILL_DIR` anchor documented in the repository's contributor instructions so paths resolve when the agent's working directory is the user's project, not the skill directory.
|
||||
@@ -0,0 +1,80 @@
|
||||
# Codex Spec (Config, Prompts, Skills, Subagents, MCP)
|
||||
|
||||
Last verified: 2026-04-19
|
||||
|
||||
## Primary sources
|
||||
|
||||
```
|
||||
https://developers.openai.com/codex/config-basic
|
||||
https://developers.openai.com/codex/config-advanced
|
||||
https://developers.openai.com/codex/custom-prompts
|
||||
https://developers.openai.com/codex/skills
|
||||
https://developers.openai.com/codex/skills/create-skill
|
||||
https://developers.openai.com/codex/subagents
|
||||
https://developers.openai.com/codex/guides/agents-md
|
||||
https://developers.openai.com/codex/mcp
|
||||
```
|
||||
|
||||
## Config location and precedence
|
||||
|
||||
- Codex reads local settings from `~/.codex/config.toml`, shared by the CLI and IDE extension. citeturn2view0
|
||||
- Configuration precedence is: CLI flags → profile values → root-level values in `config.toml` → built-in defaults. citeturn2view0
|
||||
- Codex stores local state under `CODEX_HOME` (defaults to `~/.codex`) and includes `config.toml` there. citeturn4view0
|
||||
|
||||
## Profiles and providers
|
||||
|
||||
- Profiles are defined under `[profiles.<name>]` and selected with `codex --profile <name>`. citeturn4view0
|
||||
- A top-level `profile = "<name>"` sets the default profile; CLI flags can override it. citeturn4view0
|
||||
- Profiles are experimental and not supported in the IDE extension. citeturn4view0
|
||||
- Custom model providers can be defined with base URL, wire API, and optional headers, then referenced via `model_provider`. citeturn4view0
|
||||
|
||||
## Custom prompts (slash commands)
|
||||
|
||||
- Custom prompts are Markdown files stored under `~/.codex/prompts/`. citeturn3view0
|
||||
- Custom prompts require explicit invocation and aren’t shared through the repository; use skills to share or auto-invoke. citeturn3view0
|
||||
- Prompts are invoked as `/prompts:<name>` in the slash command UI. citeturn3view0
|
||||
- Prompt front matter supports `description:` and `argument-hint:`. citeturn3view0turn2view3
|
||||
- Prompt arguments support `$1`–`$9`, `$ARGUMENTS`, and named placeholders like `$FILE` provided as `KEY=value`. citeturn2view3
|
||||
- Codex ignores non-Markdown files in the prompts directory. citeturn2view3
|
||||
|
||||
## AGENTS.md instructions
|
||||
|
||||
- Codex reads `AGENTS.md` files before doing any work and builds a combined instruction chain. citeturn3view1
|
||||
- Discovery order: global (`~/.codex`, using `AGENTS.override.md` then `AGENTS.md`) then project directory traversal from repo root to CWD, with override > AGENTS > fallback names. citeturn3view1
|
||||
- Codex concatenates files from root down; files closer to the working directory appear later and override earlier guidance. citeturn3view1
|
||||
|
||||
## Skills (Agent Skills)
|
||||
|
||||
- A skill is a folder containing `SKILL.md` plus optional `scripts/`, `references/`, and `assets/`. citeturn3view3turn3view4
|
||||
- `SKILL.md` uses YAML front matter and requires `name` and `description`. citeturn3view3turn3view4
|
||||
- Required fields are single-line with length limits (name ≤ 100 chars, description ≤ 500 chars). citeturn3view4
|
||||
- At startup, Codex loads only each skill’s name/description; full content is injected when invoked. citeturn3view3turn3view4
|
||||
- Skills can be repo-scoped in `.agents/skills/` and are discovered from the current working directory up to the repository root. User-scoped skills live in `~/.agents/skills/`. citeturn1view1turn1view4
|
||||
- Inference: some existing tooling and user setups still use `.codex/skills/` and `~/.codex/skills/` as compatibility paths, but those locations are not documented in the current OpenAI Codex skills docs linked above.
|
||||
- Compound Engineering should avoid `~/.agents/skills` for managed installs because that shared root can shadow Copilot's native plugin skills. Use the Codex-specific compatibility root `~/.codex/skills/compound-engineering/<skill-name>/SKILL.md` for CE Codex skills, and track generated files with a CE manifest.
|
||||
- Codex also supports admin-scoped skills in `/etc/codex/skills` plus built-in system skills bundled with Codex. citeturn1view4
|
||||
- Skills can be invoked explicitly using `/skills` or `$skill-name`. citeturn3view3
|
||||
|
||||
## Subagents and custom agents
|
||||
|
||||
- Codex subagent workflows are enabled by default in current releases.
|
||||
- Codex only spawns subagents when explicitly asked.
|
||||
- Custom agent files are standalone TOML files under `~/.codex/agents/` for personal agents or `.codex/agents/` for project-scoped agents.
|
||||
- Each TOML file defines one custom agent. Required fields:
|
||||
- `name`
|
||||
- `description`
|
||||
- `developer_instructions`
|
||||
- Optional fields can include `nickname_candidates`, `model`, `model_reasoning_effort`, `sandbox_mode`, `mcp_servers`, and `skills.config`.
|
||||
- The TOML `name` field is the source of truth; matching the filename to the agent name is only a convention.
|
||||
- The generic converter can convert Claude Markdown agents into Codex custom-agent TOML files under `~/.codex/agents/<plugin>/` for plugins that still ship standalone agents.
|
||||
- Generated agents should live under `~/.codex/agents`, not `~/.agents/skills`, because `~/.agents` is shared across harnesses and can shadow native plugin installs.
|
||||
- Generated TOML agent names preserve source naming and may include source category context for nested agent trees.
|
||||
- Empirical test on 2026-04-19 confirmed Codex discovers nested custom-agent TOML files under `~/.codex/agents/<plugin>/` and accepts hyphenated TOML `name` values.
|
||||
- Empirical plugin test on 2026-04-19 found Codex native plugins did not register custom agents bundled under plugin-local `agents/`, plugin-local `.codex/agents/`, or an undocumented plugin manifest `agents` field. Compound Engineering now avoids that gap by shipping specialist behavior as skill-local prompt assets inside native skills; no CE custom-agent installer is required.
|
||||
|
||||
## MCP (Model Context Protocol)
|
||||
|
||||
- MCP configuration lives in `~/.codex/config.toml` and is shared by the CLI and IDE extension. citeturn3view2turn3view5
|
||||
- Each server is configured under `[mcp_servers.<server-name>]`. citeturn3view5
|
||||
- STDIO servers support `command` (required), `args`, `env`, `env_vars`, and `cwd`. citeturn3view5
|
||||
- Streamable HTTP servers support `url` (required), `bearer_token_env_var`, `http_headers`, and `env_http_headers`. citeturn3view5
|
||||
@@ -0,0 +1,170 @@
|
||||
# GitHub Copilot Spec (Agents, Skills, MCP)
|
||||
|
||||
Last verified: 2026-04-18
|
||||
|
||||
## Primary sources
|
||||
|
||||
```
|
||||
https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli
|
||||
https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference
|
||||
https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference
|
||||
https://docs.github.com/en/copilot/concepts/agents/copilot-cli/about-cli-plugins
|
||||
https://docs.github.com/en/copilot/reference/custom-agents-configuration
|
||||
https://docs.github.com/en/copilot/concepts/agents/about-agent-skills
|
||||
https://docs.github.com/en/copilot/concepts/agents/coding-agent/mcp-and-coding-agent
|
||||
```
|
||||
|
||||
## Config locations
|
||||
|
||||
| Scope | Path |
|
||||
|-------|------|
|
||||
| Project agents | `.github/agents/*.agent.md` |
|
||||
| Project agents (Claude-compatible) | `.claude/agents/*.md` |
|
||||
| Personal agents | `~/.copilot/agents/*.agent.md` |
|
||||
| Personal agents (Claude-compatible) | `~/.claude/agents/*.md` |
|
||||
| Plugin agents | `agents/` by default, overridable in plugin manifest |
|
||||
| Project skills | `.github/skills/*/SKILL.md` |
|
||||
| Project skills (auto-discovery) | `.agents/skills/*/SKILL.md` |
|
||||
| Project instructions | `.github/copilot-instructions.md` |
|
||||
| Path-specific instructions | `.github/instructions/*.instructions.md` |
|
||||
| Project prompts | `.github/prompts/*.prompt.md` |
|
||||
| Org/enterprise agents | `.github-private/agents/*.agent.md` |
|
||||
| Personal skills | `~/.copilot/skills/*/SKILL.md` |
|
||||
| Personal skills (auto-discovery) | `~/.agents/skills/*/SKILL.md` |
|
||||
| Directory instructions | `AGENTS.md` (nearest ancestor wins) |
|
||||
|
||||
## Agents (.agent.md files)
|
||||
|
||||
- Custom agents are Markdown files with YAML frontmatter stored in `.github/agents/`.
|
||||
- File extension is `.agent.md` (or `.md`). Filenames may only contain: `.`, `-`, `_`, `a-z`, `A-Z`, `0-9`.
|
||||
- The documented custom-agent extension is singular `.agent.md`, not `.agents.md`.
|
||||
- `description` is the only required frontmatter field.
|
||||
- Current Copilot CLI docs do not list `.agents/agents` or `~/.agents/agents` as custom-agent discovery paths. The `.agents/*` convention is documented for skills (`.agents/skills`, `~/.agents/skills`), not agents.
|
||||
- Copilot CLI also loads Claude-compatible agent directories (`.claude/agents`, `~/.claude/agents`) after native Copilot agent directories and before plugin agents.
|
||||
- `AGENTS.md` files are supported as custom instruction/context files, not as custom-agent profile files.
|
||||
|
||||
## Plugins
|
||||
|
||||
- Copilot CLI plugins bundle reusable agents, skills, hooks, MCP servers, and related configuration.
|
||||
- Install from a registered marketplace with:
|
||||
|
||||
```text
|
||||
/plugin marketplace add EveryInc/compound-engineering-plugin
|
||||
/plugin install compound-engineering@compound-engineering-plugin
|
||||
```
|
||||
|
||||
- The terminal equivalents are:
|
||||
|
||||
```bash
|
||||
copilot plugin marketplace add EveryInc/compound-engineering-plugin
|
||||
copilot plugin install compound-engineering@compound-engineering-plugin
|
||||
```
|
||||
|
||||
- Copilot CLI looks for plugin manifests at `.plugin/plugin.json`, `plugin.json`, `.github/plugin/plugin.json`, or `.claude-plugin/plugin.json`.
|
||||
- Copilot CLI looks for marketplace manifests at `marketplace.json`, `.plugin/marketplace.json`, `.github/plugin/marketplace.json`, or `.claude-plugin/marketplace.json`.
|
||||
- Therefore the existing repository-level `.claude-plugin/marketplace.json` and plugin-level `plugins/compound-engineering/.claude-plugin/plugin.json` are expected to be sufficient for Copilot native plugin install. Do not add a parallel `.github/plugin` surface unless Copilot requires a Copilot-only manifest field in the future.
|
||||
|
||||
### Frontmatter fields
|
||||
|
||||
| Field | Required | Default | Description |
|
||||
|-------|----------|---------|-------------|
|
||||
| `name` | No | Derived from filename | Display name |
|
||||
| `description` | **Yes** | — | What the agent does |
|
||||
| `tools` | No | `["*"]` | Tool access list. `[]` disables all tools. |
|
||||
| `target` | No | both | `vscode`, `github-copilot`, or omit for both |
|
||||
| `infer` | No | `true` | Auto-select based on task context |
|
||||
| `model` | No | Platform default | AI model (works in IDE, may be ignored on github.com) |
|
||||
| `mcp-servers` | No | — | MCP config (org/enterprise agents only) |
|
||||
| `metadata` | No | — | Arbitrary key-value annotations |
|
||||
|
||||
### Character limit
|
||||
|
||||
Agent body content is limited to **30,000 characters**.
|
||||
|
||||
### Tool names
|
||||
|
||||
| Name | Aliases | Purpose |
|
||||
|------|---------|---------|
|
||||
| `execute` | `shell`, `Bash` | Run shell commands |
|
||||
| `read` | `Read` | Read files |
|
||||
| `edit` | `Edit`, `Write` | Modify files |
|
||||
| `search` | `Grep`, `Glob` | Search files |
|
||||
| `agent` | `Task` | Invoke other agents |
|
||||
| `web` | `WebSearch`, `WebFetch` | Web access |
|
||||
|
||||
## Skills (SKILL.md)
|
||||
|
||||
- Skills follow the open SKILL.md standard (same format as Claude Code and Cursor).
|
||||
- A skill is a directory containing `SKILL.md` plus optional `scripts/`, `references/`, and `assets/`.
|
||||
- YAML frontmatter requires `name` and `description` fields.
|
||||
- Skills are loaded on-demand when Copilot determines relevance.
|
||||
|
||||
### Discovery locations
|
||||
|
||||
| Scope | Path |
|
||||
|-------|------|
|
||||
| Project | `.github/skills/*/SKILL.md` |
|
||||
| Project (Claude-compatible) | `.claude/skills/*/SKILL.md` |
|
||||
| Project (auto-discovery) | `.agents/skills/*/SKILL.md` |
|
||||
| Personal | `~/.copilot/skills/*/SKILL.md` |
|
||||
| Personal (auto-discovery) | `~/.agents/skills/*/SKILL.md` |
|
||||
|
||||
## MCP (Model Context Protocol)
|
||||
|
||||
- MCP configuration is set via **Repository Settings > Copilot > Coding agent > MCP configuration** on GitHub.
|
||||
- Repository-level agents **cannot** define MCP servers inline; use repository settings instead.
|
||||
- Org/enterprise agents can embed MCP server definitions in frontmatter.
|
||||
- All env var names must use the `COPILOT_MCP_` prefix.
|
||||
- Only MCP tools are supported (not resources or prompts).
|
||||
|
||||
### Config structure
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"server-name": {
|
||||
"type": "local",
|
||||
"command": "npx",
|
||||
"args": ["package"],
|
||||
"tools": ["*"],
|
||||
"env": {
|
||||
"API_KEY": "COPILOT_MCP_API_KEY"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Server types
|
||||
|
||||
| Type | Fields |
|
||||
|------|--------|
|
||||
| Local/stdio | `type: "local"`, `command`, `args`, `tools`, `env` |
|
||||
| Remote/SSE | `type: "sse"`, `url`, `tools`, `headers` |
|
||||
|
||||
## Prompts (.prompt.md)
|
||||
|
||||
- Reusable prompt files stored in `.github/prompts/`.
|
||||
- Available in VS Code, Visual Studio, and JetBrains IDEs only (not on github.com).
|
||||
- Invoked via `/promptname` in chat.
|
||||
- Support variable syntax: `${input:name}`, `${file}`, `${selection}`.
|
||||
|
||||
## Precedence
|
||||
|
||||
1. Built-in agents
|
||||
2. `~/.copilot/agents`
|
||||
3. `<project>/.github/agents`
|
||||
4. `<parents>/.github/agents`
|
||||
5. `~/.claude/agents`
|
||||
6. `<project>/.claude/agents`
|
||||
7. `<parents>/.claude/agents`
|
||||
8. Plugin `agents/` directories
|
||||
9. Remote organization/enterprise agents
|
||||
|
||||
Within a repo, `AGENTS.md` files in directories provide nearest-ancestor-wins instructions.
|
||||
|
||||
Skills use separate first-found-wins precedence. Current docs list project `.github/skills`, `.agents/skills`, `.claude/skills`, inherited project skills, personal `~/.copilot/skills`, personal `~/.agents/skills`, personal `~/.claude/skills`, then plugin skill directories.
|
||||
|
||||
Skills are deduplicated by the `name` field inside `SKILL.md`, not by directory name. If a personal or project skill has the same `name` as a plugin skill, Copilot uses the first-loaded personal/project skill and silently ignores the plugin skill. For example, a stale `~/.agents/skills/ce-plan/SKILL.md` with `name: ce-plan` would shadow the native plugin's `ce-plan`; it should not show as two separate skills in Copilot CLI. Use `/skills info ce-plan` to confirm which location won.
|
||||
|
||||
This makes Copilot cleanup different from Codex duplicate cleanup: stale CE skills in `~/.agents/skills`, `~/.copilot/skills`, `.agents/skills`, or `.github/skills` may not create visible duplicates, but they can silently override newer plugin-provided CE skills.
|
||||
@@ -0,0 +1,106 @@
|
||||
# Cursor Spec (Plugin Marketplace, Rules, Commands, Skills, MCP)
|
||||
|
||||
Last verified: 2026-02-12
|
||||
|
||||
## Primary sources
|
||||
|
||||
```
|
||||
https://docs.cursor.com/context/rules
|
||||
https://docs.cursor.com/context/rules-for-ai
|
||||
https://docs.cursor.com/customize/model-context-protocol
|
||||
```
|
||||
|
||||
## Plugin Marketplace
|
||||
|
||||
Compound Engineering is published through the Cursor Plugin Marketplace.
|
||||
|
||||
In Cursor Agent chat, install with:
|
||||
|
||||
```text
|
||||
/add-plugin compound-engineering
|
||||
```
|
||||
|
||||
Users can also search for "compound engineering" in the plugin marketplace.
|
||||
|
||||
The repo-owned marketplace files are:
|
||||
|
||||
```text
|
||||
.cursor-plugin/marketplace.json
|
||||
.cursor-plugin/plugin.json
|
||||
```
|
||||
|
||||
Do not use the old custom Bun converter/install path for Cursor.
|
||||
|
||||
## Config locations
|
||||
|
||||
| Scope | Path |
|
||||
|-------|------|
|
||||
| Project rules | `.cursor/rules/*.mdc` |
|
||||
| Project commands | `.cursor/commands/*.md` |
|
||||
| Project skills | `.cursor/skills/*/SKILL.md` |
|
||||
| Project MCP | `.cursor/mcp.json` |
|
||||
| Project CLI permissions | `.cursor/cli.json` |
|
||||
| Global MCP | `~/.cursor/mcp.json` |
|
||||
| Global CLI config | `~/.cursor/cli-config.json` |
|
||||
| Legacy rules | `.cursorrules` (deprecated) |
|
||||
|
||||
## Rules (.mdc files)
|
||||
|
||||
- Rules are Markdown files with the `.mdc` extension stored in `.cursor/rules/`.
|
||||
- Each rule has YAML frontmatter with three fields: `description`, `globs`, `alwaysApply`.
|
||||
- Rules have four activation types based on frontmatter configuration:
|
||||
|
||||
| Type | `alwaysApply` | `globs` | `description` | Behavior |
|
||||
|------|:---:|:---:|:---:|---|
|
||||
| Always | `true` | ignored | optional | Included in every conversation |
|
||||
| Auto Attached | `false` | set | optional | Included when matching files are in context |
|
||||
| Agent Requested | `false` | empty | set | AI decides based on description relevance |
|
||||
| Manual | `false` | empty | empty | Only included via `@rule-name` mention |
|
||||
|
||||
- Precedence: Team Rules > Project Rules > User Rules > Legacy `.cursorrules` > `AGENTS.md`.
|
||||
|
||||
## Commands (slash commands)
|
||||
|
||||
- Custom commands are Markdown files stored in `.cursor/commands/`.
|
||||
- Commands are plain markdown with no YAML frontmatter support.
|
||||
- The filename (without `.md`) becomes the command name.
|
||||
- Commands are invoked by typing `/` in the chat UI.
|
||||
- Commands support parameterized arguments via `$1`, `$2`, etc.
|
||||
|
||||
## Skills (Agent Skills)
|
||||
|
||||
- Skills follow the open SKILL.md standard, identical to Claude Code and Codex.
|
||||
- A skill is a folder containing `SKILL.md` plus optional `scripts/`, `references/`, and `assets/`.
|
||||
- `SKILL.md` uses YAML frontmatter with required `name` and `description` fields.
|
||||
- Skills can be repo-scoped in `.cursor/skills/` or user-scoped in `~/.cursor/skills/`.
|
||||
- At startup, only each skill's name/description is loaded; full content is injected on invocation.
|
||||
|
||||
## MCP (Model Context Protocol)
|
||||
|
||||
- MCP configuration lives in `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global).
|
||||
- Each server is configured under the `mcpServers` key.
|
||||
- STDIO servers support `command` (required), `args`, and `env`.
|
||||
- Remote servers support `url` (required) and optional `headers`.
|
||||
- Cursor infers transport type from whether `command` or `url` is present.
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"server-name": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "package-name"],
|
||||
"env": { "KEY": "value" }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## CLI (cursor-agent)
|
||||
|
||||
- Cursor CLI launched August 2025 as `cursor-agent`.
|
||||
- Supports interactive mode, headless mode (`-p`), and cloud agents.
|
||||
- Reads `.cursor/rules/`, `.cursorrules`, and `AGENTS.md` for instructions.
|
||||
- CLI permissions controlled via `.cursor/cli.json` with allow/deny lists.
|
||||
- Permission tokens: `Shell(command)`, `Read(path)`, `Write(path)`, `Delete(path)`, `Grep(path)`, `LS(path)`.
|
||||
@@ -0,0 +1,89 @@
|
||||
# Devin CLI Spec (Plugins and Skills)
|
||||
|
||||
Last verified: 2026-07-05, empirically against Devin CLI 3000.1.23 on macOS (binary inspection plus a live local install of this repo), following the convention in `docs/solutions/conventions/antigravity-target-empirical-format-verification.md`. Facts below come from the CLI's own behavior unless marked as documentation-sourced.
|
||||
|
||||
## Primary sources
|
||||
|
||||
Devin CLI ships its documentation on disk with the install (Homebrew cask layout):
|
||||
|
||||
```text
|
||||
<devin-install>/share/devin/docs/extensibility/plugins/overview.mdx
|
||||
<devin-install>/share/devin/docs/extensibility/skills/overview.mdx
|
||||
<devin-install>/share/devin/docs/extensibility/skills/creating-skills.mdx
|
||||
```
|
||||
|
||||
## Plugin manifest
|
||||
|
||||
A Devin plugin is a directory (GitHub repo, git URL, or local path) with a manifest at exactly:
|
||||
|
||||
```text
|
||||
<plugin_root>/.devin-plugin/plugin.json
|
||||
```
|
||||
|
||||
There is no root-level manifest alternative — install fails with "could not read manifest at .../.devin-plugin/plugin.json" when the file is absent (verified). The manifest is parsed as a fixed field set (an 11-field `RawManifest` observed in the binary); tolerance of unknown fields is unverified, so CE ships documented fields only.
|
||||
|
||||
| Field | CE usage |
|
||||
| --- | --- |
|
||||
| `name` | Required plugin id, set to `compound-engineering`; also the slash-command namespace (`/compound-engineering:<skill>`) and must be unique among installed plugins |
|
||||
| `version` | Root plugin version, bumped by release-please |
|
||||
| `description`, `author`, `homepage`, `repository`, `license`, `keywords` | Shared display metadata (`author` is an object: `{ "name": ..., "email": ... }`) |
|
||||
| `requiredPlugins`, `optionalPlugins`, `forbiddenPlugins` | Dependency/governance lists — not used by CE |
|
||||
|
||||
There is **no `skills` path field** (unlike Kimi and Codex manifests): Devin loads skills from the root `skills/` directory by convention. The release metadata sync therefore performs no declared-skills-path validation for Devin.
|
||||
|
||||
## Skills
|
||||
|
||||
- `skills/<name>/SKILL.md` at the plugin root, standard YAML frontmatter — the layout this repo already ships. All CE skills registered without transformation (verified: full live install).
|
||||
- Installed skills surface as `/compound-engineering:<skill>` slash commands.
|
||||
- Plugins load at **session start**. A mid-session install does not register skills in the running session (verified); users must start a new Devin session after install or update.
|
||||
- Local-path installs are linked to the source directory, not copied — edits apply on the next session without reinstalling. GitHub installs are fetched copies updated via `devin plugins update`.
|
||||
|
||||
## Skill frontmatter compatibility
|
||||
|
||||
Devin parses Claude-style skill frontmatter natively. Observed in the binary's `SkillFrontmatter` schema and probed live:
|
||||
|
||||
- `name`, `description`, `argument-hint`, `model` — supported directly.
|
||||
- `disable-model-invocation` and `user-invocable` — parsed natively, so CE's user-only skills (e.g. `ce-promote`, `ce-polish`, `ce-sweep`, `ce-product-pulse`) keep their invocation semantics.
|
||||
- `allowed-tools` — parsed, with **partial name mapping** (verified by live probe):
|
||||
|
||||
| Claude tool name | Devin handling |
|
||||
| --- | --- |
|
||||
| `Read`, `Grep`, `Glob`, `Edit` | Mapped (case-insensitive) to `read`, `grep`, `glob`, `edit` |
|
||||
| `Bash`, `Write`, `Task`, `WebFetch`, `WebSearch`, `AskUserQuestion`, patterned forms like `Bash(git *)` | Dropped silently |
|
||||
|
||||
Degradation is graceful: in Devin, `allowed-tools` is an **auto-approval list, not a hard restriction** — tools with dropped names remain available but prompt for user permission ("Other tools can still be used but will require user permission", verified). CE skills that declare `Bash`/`Write` (e.g. `ce-sweep`, `ce-product-pulse`) work, with extra permission prompts.
|
||||
|
||||
- Dynamic content (`$ARGUMENTS`/`$1`, `@file` inclusion, `` !`command` `` output) is supported per the CLI docs.
|
||||
|
||||
## Install commands
|
||||
|
||||
Direct install from GitHub (also accepts any git URL or a local path):
|
||||
|
||||
```bash
|
||||
devin plugins install EveryInc/compound-engineering-plugin
|
||||
```
|
||||
|
||||
Management:
|
||||
|
||||
```bash
|
||||
devin plugins list
|
||||
devin plugins info compound-engineering
|
||||
devin plugins update compound-engineering
|
||||
devin plugins remove compound-engineering
|
||||
```
|
||||
|
||||
`install`, `list`, and `info` verified live; `update`/`remove` semantics are documentation-sourced. Pass `-y`/`--yes` to skip the pre-install summary prompt.
|
||||
|
||||
## No marketplace catalog
|
||||
|
||||
Devin has no marketplace concept — plugins install straight from a repo/URL/path, and dependency distribution runs through the manifest's `requiredPlugins`/`optionalPlugins` lists instead of a catalog file. There is no `.devin-plugin/marketplace.json` to ship, and `release:validate` performs no marketplace parity checks for Devin. Revisit if Devin ships a catalog schema.
|
||||
|
||||
## Instruction files
|
||||
|
||||
Devin reads `AGENTS.md` (and `CLAUDE.md` as a compatibility shim) for project instructions, plus `.claude/` project directories for commands/agents/hooks compatibility. No `DEVIN.md` file exists or is needed — the existing root `AGENTS.md` already serves Devin sessions in this repo.
|
||||
|
||||
## Open questions
|
||||
|
||||
- Whether the manifest parser tolerates unknown fields (CE avoids the question by shipping documented fields only).
|
||||
- Whether Devin will map `Bash` -> `exec` (and `Write` -> `edit`) in `allowed-tools` compatibility handling; if so, the README note about permission prompts can be dropped.
|
||||
- Whether plugin skills participate in Devin's model-invocable skill discovery identically to project skills (CE skills carry `description` frontmatter either way).
|
||||
@@ -0,0 +1,86 @@
|
||||
# Kimi Code CLI Spec (Plugins and Skills)
|
||||
|
||||
Last verified: 2026-06-24
|
||||
|
||||
## Primary sources
|
||||
|
||||
```
|
||||
https://www.kimi.com/code/docs/en/kimi-code-cli/customization/plugins.html
|
||||
https://www.kimi.com/code/docs/en/kimi-code-cli/customization/agents.html
|
||||
```
|
||||
|
||||
## Plugin manifests
|
||||
|
||||
Kimi Code CLI plugins are directories or zip files with a manifest at one of:
|
||||
|
||||
```text
|
||||
<plugin_root>/kimi.plugin.json
|
||||
<plugin_root>/.kimi-plugin/plugin.json
|
||||
```
|
||||
|
||||
When both exist, `kimi.plugin.json` takes precedence. Compound Engineering uses `.kimi-plugin/plugin.json` to match the repo's other platform-specific manifest directories.
|
||||
|
||||
Supported fields include:
|
||||
|
||||
| Field | CE usage |
|
||||
| --- | --- |
|
||||
| `name` | Required plugin id, set to `compound-engineering` |
|
||||
| `version` | Root plugin version, bumped by release-please |
|
||||
| `description`, `keywords`, `author`, `homepage`, `license` | Shared display metadata |
|
||||
| `interface.displayName` | Marketplace/plugin manager display name |
|
||||
| `interface.shortDescription` | Short plugin-manager copy |
|
||||
| `interface.longDescription` | Longer plugin-manager copy |
|
||||
| `interface.developerName` | Human-readable developer name |
|
||||
| `interface.websiteURL` | Repository URL |
|
||||
| `skills` | `./skills/`, resolved inside the plugin root |
|
||||
|
||||
CE does not currently declare `sessionStart.skill`, `skillInstructions`, or `mcpServers` for Kimi. Unsupported runtime fields such as `tools`, `commands`, `hooks`, `apps`, `inject`, and `configFile` are diagnostics-only in Kimi and should not be used for CE behavior.
|
||||
|
||||
## Marketplace catalog
|
||||
|
||||
Kimi also supports a custom marketplace JSON source. The catalog schema uses:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "2",
|
||||
"plugins": [
|
||||
{
|
||||
"id": "compound-engineering",
|
||||
"displayName": "Compound Engineering",
|
||||
"source": "https://github.com/EveryInc/compound-engineering-plugin"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
The marketplace catalog has no release-owned `metadata.version` equivalent. Treat `.kimi-plugin/marketplace.json` as static parity data, not a separate release component. `release:validate` checks that its plugin ids match the Claude marketplace plugin names and that entries use installable sources.
|
||||
|
||||
## Install commands
|
||||
|
||||
Direct install from GitHub:
|
||||
|
||||
```text
|
||||
/plugins install https://github.com/EveryInc/compound-engineering-plugin
|
||||
```
|
||||
|
||||
Marketplace browsing:
|
||||
|
||||
```text
|
||||
/plugins marketplace https://raw.githubusercontent.com/EveryInc/compound-engineering-plugin/main/.kimi-plugin/marketplace.json
|
||||
```
|
||||
|
||||
After installing, enabling, disabling, or removing a plugin, Kimi requires `/reload` or a new session for changes to apply.
|
||||
|
||||
## Instruction files
|
||||
|
||||
Kimi uses `AGENTS.md` for global and project instructions, not a `KIMI.md` file.
|
||||
|
||||
Documented locations include:
|
||||
|
||||
| Scope | Location |
|
||||
| --- | --- |
|
||||
| Global Kimi-specific | `$KIMI_CODE_HOME/AGENTS.md`, defaulting to `~/.kimi-code/AGENTS.md` |
|
||||
| Generic cross-tool | `~/.agents/AGENTS.md` |
|
||||
| Project | `.kimi-code/AGENTS.md` or `AGENTS.md` under the project tree |
|
||||
|
||||
This repo should not add a root `KIMI.md` compatibility shim unless Kimi documents support for that filename. The existing root `AGENTS.md` is already the canonical project instruction file for Kimi-compatible project context.
|
||||
@@ -0,0 +1,171 @@
|
||||
# Kiro CLI Spec (Custom Agents, Skills, Steering, MCP, Settings)
|
||||
|
||||
Last verified: 2026-02-17
|
||||
|
||||
## Primary sources
|
||||
|
||||
```
|
||||
https://kiro.dev/docs/cli/
|
||||
https://kiro.dev/docs/cli/custom-agents/configuration-reference/
|
||||
https://kiro.dev/docs/cli/skills/
|
||||
https://kiro.dev/docs/cli/steering/
|
||||
https://kiro.dev/docs/cli/mcp/
|
||||
https://kiro.dev/docs/cli/hooks/
|
||||
https://agentskills.io
|
||||
```
|
||||
|
||||
## Config locations
|
||||
|
||||
- Project-level config: `.kiro/` directory at project root.
|
||||
- No global/user-level config directory — all config is project-scoped.
|
||||
|
||||
## Directory structure
|
||||
|
||||
```
|
||||
.kiro/
|
||||
├── agents/
|
||||
│ ├── <name>.json # Agent configuration
|
||||
│ └── prompts/
|
||||
│ └── <name>.md # Agent prompt files
|
||||
├── skills/
|
||||
│ └── <name>/
|
||||
│ └── SKILL.md # Skill definition
|
||||
├── steering/
|
||||
│ └── <name>.md # Always-on context files
|
||||
└── settings/
|
||||
└── mcp.json # MCP server configuration
|
||||
```
|
||||
|
||||
## Custom agents (JSON config + prompt files)
|
||||
|
||||
- Custom agents are JSON files in `.kiro/agents/`.
|
||||
- Each agent has a corresponding prompt `.md` file, referenced via `file://` URI.
|
||||
- Agent config has 14 possible fields (see below).
|
||||
- Agents are activated by user selection (no auto-activation).
|
||||
- The converter outputs a subset of fields relevant to converted plugins.
|
||||
|
||||
### Agent config fields
|
||||
|
||||
| Field | Type | Used in conversion | Notes |
|
||||
|---|---|---|---|
|
||||
| `name` | string | Yes | Agent display name |
|
||||
| `description` | string | Yes | Human-readable description |
|
||||
| `prompt` | string or `file://` URI | Yes | System prompt or file reference |
|
||||
| `tools` | string[] | Yes (`["*"]`) | Available tools |
|
||||
| `resources` | string[] | Yes | `file://`, `skill://`, `knowledgeBase` URIs |
|
||||
| `includeMcpJson` | boolean | Yes (`true`) | Inherit project MCP servers |
|
||||
| `welcomeMessage` | string | Yes | Agent switch greeting |
|
||||
| `mcpServers` | object | No | Per-agent MCP config (use includeMcpJson instead) |
|
||||
| `toolAliases` | Record | No | Tool name remapping |
|
||||
| `allowedTools` | string[] | No | Auto-approve patterns |
|
||||
| `toolsSettings` | object | No | Per-tool configuration |
|
||||
| `hooks` | object | No (future work) | 5 trigger types |
|
||||
| `model` | string | No | Model selection |
|
||||
| `keyboardShortcut` | string | No | Quick-switch shortcut |
|
||||
|
||||
### Example agent config
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "security-reviewer",
|
||||
"description": "Reviews code for security vulnerabilities",
|
||||
"prompt": "file://./prompts/security-reviewer.md",
|
||||
"tools": ["*"],
|
||||
"resources": [
|
||||
"file://.kiro/steering/**/*.md",
|
||||
"skill://.kiro/skills/**/SKILL.md"
|
||||
],
|
||||
"includeMcpJson": true,
|
||||
"welcomeMessage": "Switching to security-reviewer. Reviews code for security vulnerabilities"
|
||||
}
|
||||
```
|
||||
|
||||
## Skills (SKILL.md standard)
|
||||
|
||||
- Skills follow the open [Agent Skills](https://agentskills.io) standard.
|
||||
- A skill is a folder containing `SKILL.md` plus optional supporting files.
|
||||
- Skills live in `.kiro/skills/`.
|
||||
- `SKILL.md` uses YAML frontmatter with `name` and `description` fields.
|
||||
- Kiro activates skills on demand based on description matching.
|
||||
- The `description` field is critical — Kiro uses it to decide when to activate the skill.
|
||||
|
||||
### Constraints
|
||||
|
||||
- Skill name: max 64 characters, pattern `^[a-z][a-z0-9-]*$`, no consecutive hyphens (`--`).
|
||||
- Skill description: max 1024 characters.
|
||||
- Skill name must match parent directory name.
|
||||
|
||||
### Example
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: workflows-plan
|
||||
description: Plan work by analyzing requirements and creating actionable steps
|
||||
---
|
||||
|
||||
# Planning Workflow
|
||||
|
||||
Detailed instructions...
|
||||
```
|
||||
|
||||
## Steering files
|
||||
|
||||
- Markdown files in `.kiro/steering/`.
|
||||
- Always loaded into every agent session's context.
|
||||
- Equivalent to the repo instruction file used by Claude-oriented workflows; in this repo `AGENTS.md` is canonical and `CLAUDE.md` may exist only as a compatibility shim.
|
||||
- Used for project-wide instructions, coding standards, and conventions.
|
||||
|
||||
## MCP server configuration
|
||||
|
||||
- MCP servers are configured in `.kiro/settings/mcp.json`.
|
||||
- **Only stdio transport is supported** — `command` + `args` + `env`.
|
||||
- HTTP/SSE transport (`url`, `headers`) is NOT supported by Kiro CLI.
|
||||
- The converter skips HTTP-only MCP servers with a warning.
|
||||
|
||||
### Example
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"playwright": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@anthropic/mcp-playwright"]
|
||||
},
|
||||
"context7": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@context7/mcp-server"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Hooks
|
||||
|
||||
- Kiro supports 5 hook trigger types: `agentSpawn`, `userPromptSubmit`, `preToolUse`, `postToolUse`, `stop`.
|
||||
- Hooks are configured inside agent JSON configs (not separate files).
|
||||
- 3 of 5 triggers map to Claude Code hooks (`preToolUse`, `postToolUse`, `stop`).
|
||||
- Not converted by the plugin converter for MVP — a warning is emitted.
|
||||
|
||||
## Conversion lossy mappings
|
||||
|
||||
| Claude Code Feature | Kiro Status | Notes |
|
||||
|---|---|---|
|
||||
| `Edit` tool (surgical replacement) | Degraded -> `write` (full-file) | Kiro write overwrites entire files |
|
||||
| `context: fork` | Lost | No execution isolation control |
|
||||
| `!`command`` dynamic injection | Lost | No pre-processing of markdown |
|
||||
| `disable-model-invocation` | Lost | No invocation control |
|
||||
| `allowed-tools` per skill | Lost | No tool permission scoping per skill |
|
||||
| `$ARGUMENTS` interpolation | Lost | No structured argument passing |
|
||||
| Claude hooks | Skipped | Future follow-up (near-1:1 for 3/5 triggers) |
|
||||
| HTTP MCP servers | Skipped | Kiro only supports stdio transport |
|
||||
|
||||
## Overwrite behavior during conversion
|
||||
|
||||
| Content Type | Strategy | Rationale |
|
||||
|---|---|---|
|
||||
| Generated agents (JSON + prompt) | Overwrite | Generated, not user-authored |
|
||||
| Generated skills (from commands) | Overwrite | Generated, not user-authored |
|
||||
| Copied skills (pass-through) | Overwrite | Plugin is source of truth |
|
||||
| Steering files | Overwrite | Generated from `AGENTS.md` when present, otherwise `CLAUDE.md` |
|
||||
| `mcp.json` | Merge with backup | User may have added their own servers |
|
||||
| User-created agents/skills | Preserved | Don't delete orphans |
|
||||
@@ -0,0 +1,92 @@
|
||||
# OpenCode Spec (Config, Agents, Plugins)
|
||||
|
||||
Last verified: 2026-04-19
|
||||
|
||||
## Primary sources
|
||||
|
||||
```
|
||||
https://opencode.ai/docs/config/
|
||||
https://opencode.ai/docs/tools
|
||||
https://opencode.ai/docs/permissions
|
||||
https://opencode.ai/docs/plugins/
|
||||
https://opencode.ai/docs/agents/
|
||||
https://opencode.ai/docs/commands/
|
||||
https://opencode.ai/docs/skills
|
||||
https://opencode.ai/config.json
|
||||
```
|
||||
|
||||
## Config files and precedence
|
||||
|
||||
- OpenCode supports JSON and JSONC configs.
|
||||
- Config sources are merged rather than replaced, with global and project config both participating in the final config.
|
||||
- Global config is stored at `~/.config/opencode/opencode.json`, and project config is `opencode.json` in the project root.
|
||||
- Custom config file and directory can be provided via `OPENCODE_CONFIG` and `OPENCODE_CONFIG_DIR`.
|
||||
- The `.opencode` and `~/.config/opencode` directories use plural subdirectory names (`agents/`, `commands/`, `modes/`, `plugins/`, `skills/`, `tools/`, `themes/`).
|
||||
|
||||
## Core config keys
|
||||
|
||||
- `model` and `small_model` set the primary and lightweight models; `provider` configures provider options.
|
||||
- `tools` is still supported but deprecated as of OpenCode v1.1.1; permissions are now the canonical control surface.
|
||||
- `permission` controls tool approvals and can be configured globally or per tool, including pattern-based rules.
|
||||
- `mcp`, `instructions`, `disabled_providers`, `enabled_providers`, and `plugin` are supported config sections.
|
||||
- `plugin` can list npm packages to load at startup.
|
||||
- `skills.paths` and `skills.urls` can add extra skill discovery locations, but CE should not depend on them until the layout is smoke-tested locally with OpenCode.
|
||||
|
||||
## Tools
|
||||
|
||||
- OpenCode ships with built-in tools, and permissions determine whether each tool runs automatically, requires approval, or is denied.
|
||||
- Tools are enabled by default; permissions provide the gating mechanism.
|
||||
|
||||
## Permissions
|
||||
|
||||
- Permissions resolve to `allow`, `ask`, or `deny` and can be configured globally or per tool, with pattern-based rules.
|
||||
- Defaults are permissive, with special cases such as `.env` file reads.
|
||||
- Agent-level permissions override the global permission block.
|
||||
|
||||
## Agents
|
||||
|
||||
- Agents can be configured in `opencode.json` or as markdown files in `~/.config/opencode/agents/` or `.opencode/agents/`.
|
||||
- Agent config supports `mode`, `model`, `variant`, `temperature`, `top_p`, `hidden`, `steps`, `options`, `permission`, and other schema fields. `tools` still exists but is deprecated.
|
||||
- `mode` can be `primary`, `subagent`, or `all`; omitted mode defaults to `all`.
|
||||
- `hidden: true` hides subagents from the `@` autocomplete menu.
|
||||
- `permission.task` controls which subagents an agent may invoke.
|
||||
- Model IDs use the `provider/model-id` format.
|
||||
|
||||
## Skills
|
||||
|
||||
- Skills are reusable `SKILL.md` definitions loaded on demand through OpenCode's native `skill` tool.
|
||||
- OpenCode searches direct child skill directories in its built-in roots:
|
||||
- `.opencode/skills/<name>/SKILL.md`
|
||||
- `~/.config/opencode/skills/<name>/SKILL.md`
|
||||
- `.claude/skills/<name>/SKILL.md`
|
||||
- `~/.claude/skills/<name>/SKILL.md`
|
||||
- `.agents/skills/<name>/SKILL.md`
|
||||
- `~/.agents/skills/<name>/SKILL.md`
|
||||
- The config schema also exposes `skills.paths` and `skills.urls` for extra skill sources. Do not switch CE to those until tested against a local OpenCode install; direct `~/.config/opencode/skills/<name>/SKILL.md` remains the stable writer shape.
|
||||
- Skill frontmatter recognizes `name`, `description`, `license`, `compatibility`, and `metadata`; unknown fields are ignored.
|
||||
- Skill names must be lowercase alphanumeric with single hyphen separators and must match the directory name.
|
||||
|
||||
## Commands
|
||||
|
||||
- Commands can be configured in `opencode.json` or as Markdown files in `~/.config/opencode/commands/` or `.opencode/commands/`.
|
||||
- Markdown command frontmatter can include fields such as `description`, `agent`, `model`, and `subtask`; the body becomes the prompt template.
|
||||
- If a command targets an agent whose mode is `subagent`, OpenCode invokes it as a subagent by default. `subtask: true` can force subagent invocation.
|
||||
|
||||
## Plugins and events
|
||||
|
||||
- Local plugins are loaded from `.opencode/plugins/` and `~/.config/opencode/plugins/`. npm plugins can be listed in `plugin` in `opencode.json`.
|
||||
- Plugins are JavaScript/TypeScript modules. Each exported plugin function receives OpenCode context and returns hooks/event handlers.
|
||||
- Local plugins and custom tools can use npm dependencies declared in a `package.json` in the OpenCode config directory; OpenCode runs `bun install` at startup.
|
||||
|
||||
## Notes for this repository
|
||||
|
||||
- The current documented global CE install root should stay `~/.config/opencode`, not `~/.agents`, to avoid conflicts with harnesses that also read `~/.agents`.
|
||||
- The current CE writer shape is still appropriate in April 2026:
|
||||
- `~/.config/opencode/opencode.json`
|
||||
- `~/.config/opencode/agents/*.md`
|
||||
- `~/.config/opencode/commands/*.md` only when a source plugin ships commands
|
||||
- `~/.config/opencode/plugins/*.ts`
|
||||
- `~/.config/opencode/skills/*/SKILL.md`
|
||||
- OpenCode's plugin system is useful for JS/TS hooks and custom tools, but current docs do not describe a native marketplace command that consumes CE's `.claude-plugin/marketplace.json` and installs the full skills/agents/commands payload.
|
||||
- Keep the custom Bun writer until OpenCode documents a native distribution path for packaged skills and agents.
|
||||
- The `compound-engineering` plugin currently emits skills and subagent Markdown files for OpenCode. It should not emit deprecated `tools` config; permission config is enough for non-default permission modes.
|
||||
Reference in New Issue
Block a user