feat: add OpenCode/Codex outputs and update changelog (#104)
* Add OpenCode converter coverage and specs * Add Codex target support and spec docs * Generate Codex command skills and refresh spec docs * Add global Codex install path * fix: harden plugin path loading and codex descriptions * feat: ensure codex agents block on convert/install * docs: clarify target branch usage for review * chore: prep npm package metadata and release notes * docs: mention opencode and codex in changelog * docs: update CLI usage and remove stale todos * feat: install from GitHub with global outputs
This commit is contained in:
Kieran Klaassen
67
docs/specs/claude-code.md
Normal file
67
docs/specs/claude-code.md
Normal file
@@ -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
|
||||
59
docs/specs/codex.md
Normal file
59
docs/specs/codex.md
Normal file
@@ -0,0 +1,59 @@
|
||||
# Codex Spec (Config, Prompts, Skills, MCP)
|
||||
|
||||
Last verified: 2026-01-21
|
||||
|
||||
## 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/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 `.codex/skills/` or user-scoped in `~/.codex/skills/`. citeturn3view4
|
||||
- Skills can be invoked explicitly using `/skills` or `$skill-name`. citeturn3view3
|
||||
|
||||
## 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
|
||||
57
docs/specs/opencode.md
Normal file
57
docs/specs/opencode.md
Normal file
@@ -0,0 +1,57 @@
|
||||
# OpenCode Spec (Config, Agents, Plugins)
|
||||
|
||||
Last verified: 2026-01-21
|
||||
|
||||
## 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/config.json
|
||||
```
|
||||
|
||||
## Config files and precedence
|
||||
|
||||
- OpenCode supports JSON and JSONC configs. citeturn10view0
|
||||
- Config sources are merged (not replaced), with a defined precedence order from remote → global → custom → project → `.opencode` directories → inline overrides. citeturn10view0
|
||||
- Global config is stored at `~/.config/opencode/opencode.json`, and project config is `opencode.json` in the project root. citeturn10view0
|
||||
- Custom config file and directory can be provided via `OPENCODE_CONFIG` and `OPENCODE_CONFIG_DIR`. citeturn10view0
|
||||
- The `.opencode` and `~/.config/opencode` directories use plural subdirectory names (`agents/`, `commands/`, `modes/`, `plugins/`, `skills/`, `tools/`, `themes/`), but singular names are also supported for backwards compatibility. citeturn10view0
|
||||
|
||||
## Core config keys
|
||||
|
||||
- `model` and `small_model` set the primary and lightweight models; `provider` configures provider options. citeturn10view0
|
||||
- `tools` is still supported but deprecated; permissions are now the canonical control surface. citeturn1search0
|
||||
- `permission` controls tool approvals and can be configured globally or per tool, including pattern-based rules. citeturn1search0
|
||||
- `mcp`, `instructions`, and `disabled_providers` are supported config sections. citeturn1search5
|
||||
- `plugin` can list npm packages to load at startup. citeturn1search2
|
||||
|
||||
## Tools
|
||||
|
||||
- OpenCode ships with built-in tools, and permissions determine whether each tool runs automatically, requires approval, or is denied. citeturn1search3turn1search0
|
||||
- Tools are enabled by default; permissions provide the gating mechanism. citeturn1search3
|
||||
|
||||
## Permissions
|
||||
|
||||
- Permissions resolve to `allow`, `ask`, or `deny` and can be configured globally or per tool, with pattern-based rules. citeturn1search0
|
||||
- Defaults are permissive, with special cases such as `.env` file reads. citeturn1search0
|
||||
- Agent-level permissions override the global permission block. citeturn1search1turn1search0
|
||||
|
||||
## Agents
|
||||
|
||||
- Agents can be configured in `opencode.json` or as markdown files in `~/.config/opencode/agents/` or `.opencode/agents/`. citeturn1search1turn10view0
|
||||
- Agent config supports `mode`, `model`, `temperature`, `tools`, and `permission`, and agent configs override global settings. citeturn1search1
|
||||
- Model IDs use the `provider/model-id` format. citeturn1search1
|
||||
|
||||
## Plugins and events
|
||||
|
||||
- Local plugins are loaded from `.opencode/plugin/` (project) and `~/.config/opencode/plugin/` (global). npm plugins can be listed in `plugin` in `opencode.json`. citeturn1search2
|
||||
- Plugins are loaded in a defined order across config and plugin directories. citeturn1search2
|
||||
- Plugins export a function that returns a map of event handlers; the plugins doc lists supported event categories. citeturn1search2
|
||||
|
||||
## Notes for this repository
|
||||
|
||||
- Config docs describe plural subdirectory names, while the plugins doc uses `.opencode/plugin/`. This implies singular paths remain accepted for backwards compatibility, but plural paths are the canonical structure. citeturn10view0turn1search2
|
||||
Reference in New Issue
Block a user