From 4db8e02859bf47232d6537bb6bc9826f4b767dfa Mon Sep 17 00:00:00 2001 From: CrazyBoyM Date: Sat, 24 Jan 2026 04:17:31 +0800 Subject: [PATCH] docs: add Agent Skills and add-skill CLI integration - Add docs/skills.md with Agent Skills specification reference - Add add-skill CLI quick install section to README - Link to agentskills.io specification - Document npx add-skill usage for Kode agent - Enable users to install skills from any git repository --- README.md | 350 ++++++++++++++++++++++++++++++++++++++++++------- docs/skills.md | 147 +++++++++++++++++++++ 2 files changed, 451 insertions(+), 46 deletions(-) create mode 100644 docs/skills.md diff --git a/README.md b/README.md index dbdfaacd..8abf7373 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![AGENTS.md](https://img.shields.io/badge/AGENTS.md-Compatible-brightgreen)](https://agents.md) -[中文文档](README.zh-CN.md) | [Contributing](CONTRIBUTING.md) | [Documentation](docs/) +[中文文档](README.zh-CN.md) | [Contributing](CONTRIBUTING.md) | [Documentation](docs/README.md) image @@ -18,32 +18,46 @@ ## 📢 Update Log -**2025-08-29**: We've added Windows support! All Windows users can now run Kode using Git Bash, Unix subsystems, or WSL (Windows Subsystem for Linux) on their computers. - -**2025-12-30**: Windows now works out of the box with native cmd.exe support. Git Bash and WSL are optional but recommended for the best experience. +**2025-12-22**: Native-first distribution (Windows OOTB). Kode prefers a cached native binary and falls back to the Node.js runtime when needed. See `docs/binary-distribution.md`. ## 🤝 AGENTS.md Standard Support -**Kode proudly supports the [AGENTS.md standard protocol](https://agents.md) initiated by OpenAI** - a simple, open format for guiding programming agents that's used by 20k+ open source projects. +Kode supports the [AGENTS.md standard](https://agents.md): a simple, open format for guiding coding agents, used by 60k+ open-source projects. ### Full Compatibility with Multiple Standards - ✅ **AGENTS.md** - Native support for the OpenAI-initiated standard format -- ✅ **CLAUDE.md** - Full backward compatibility with Claude Code `.claude` configurations +- ✅ **Legacy `.claude` compatibility** - Reads `.claude` directories and `CLAUDE.md` when present (see `docs/compatibility.md`) - ✅ **Subagent System** - Advanced agent delegation and task orchestration - ✅ **Cross-platform** - Works with 20+ AI models and providers Use `# Your documentation request` to generate and maintain your AGENTS.md file automatically, while preserving compatibility with existing `.claude` workflows. +### Instruction Discovery (Codex-compatible) + +- Kode reads project instructions by walking from the Git repo root → current working directory. +- In each directory, it prefers `AGENTS.override.md` over `AGENTS.md` (at most one file per directory). +- Discovered files are concatenated root → leaf (combined size capped at 32 KiB by default; override with `KODE_PROJECT_DOC_MAX_BYTES`). +- If `CLAUDE.md` exists in the current directory, Kode also reads it as a legacy instruction file. + ## Overview Kode is a powerful AI assistant that lives in your terminal. It can understand your codebase, edit files, run commands, and handle entire workflows for you. -> **⚠️ Security Notice**: Kode runs in YOLO mode by default (equivalent to Claude Code's `--dangerously-skip-permissions` flag), bypassing all permission checks for maximum productivity. YOLO mode is recommended only for trusted, secure environments when working on non-critical projects. If you're working with important files or using models of questionable capability, we strongly recommend using `kode --safe` to enable permission checks and manual approval for all operations. +> **⚠️ Security Notice**: Kode runs in YOLO mode by default (equivalent to the `--dangerously-skip-permissions` flag), bypassing all permission checks for maximum productivity. YOLO mode is recommended only for trusted, secure environments when working on non-critical projects. If you're working with important files or using models of questionable capability, we strongly recommend using `kode --safe` to enable permission checks and manual approval for all operations. > > **📊 Model Performance**: For optimal performance, we recommend using newer, more capable models designed for autonomous task completion. Avoid older Q&A-focused models like GPT-4o or Gemini 2.5 Pro, which are optimized for answering questions rather than sustained independent task execution. Choose models specifically trained for agentic workflows and extended reasoning capabilities. +## Network & Privacy + +- Kode does not send product telemetry/analytics by default. +- Network requests happen only when you explicitly use networked features: + - Model provider requests (Anthropic/OpenAI-compatible endpoints you configure) + - Web tools (`WebFetch`, `WebSearch`) + - Plugin marketplace downloads (GitHub/URL sources) and OAuth flows (when used) + - Optional update checks (opt-in via `autoUpdaterStatus: enabled`) + image ## Features @@ -59,8 +73,8 @@ Kode is a powerful AI assistant that lives in your terminal. It can understand y - 🛠️ **Workflow Automation** - Handle complex development tasks with simple prompts ### Authoring Comfort -- `Ctrl+G` opens your message in your preferred editor (respects `$EDITOR`/`$VISUAL`; falls back to code/nano/vim/notepad) and returns the text to the prompt when you close it. -- `Shift+Enter` inserts a newline inside the prompt without sending; plain Enter submits. `Ctrl+M` switches the active model. +- `Option+G` (Alt+G) opens your message in your preferred editor (respects `$EDITOR`/`$VISUAL`; falls back to code/nano/vim/notepad) and returns the text to the prompt when you close it. +- `Option+Enter` inserts a newline inside the prompt without sending; plain Enter submits. `Option+M` cycles the active model. ### 🎯 Advanced Intelligent Completion System Our state-of-the-art completion system provides unparalleled coding assistance: @@ -95,22 +109,40 @@ Our state-of-the-art completion system provides unparalleled coding assistance: npm install -g @shareai-lab/kode ``` +> **🇨🇳 For users in China**: If you encounter network issues, use a mirror registry: +> ```bash +> npm install -g @shareai-lab/kode --registry=https://registry.npmmirror.com +> ``` + +Dev channel (latest features): + +```bash +npm install -g @shareai-lab/kode@dev +``` + After installation, you can use any of these commands: - `kode` - Primary command - `kwa` - Kode With Agent (alternative) - `kd` - Ultra-short alias -### Windows Notes +### Native binaries (Windows OOTB) + +- No WSL/Git Bash required. +- On `postinstall`, Kode will best-effort download a native binary from GitHub Releases into `${KODE_BIN_DIR:-~/.kode/bin}//-/kode(.exe)`. +- The wrapper (`cli.js`) prefers the native binary and falls back to the Node.js runtime (`node dist/index.js`) when needed. + +Overrides: +- Mirror downloads: `KODE_BINARY_BASE_URL` +- Disable download: `KODE_SKIP_BINARY_DOWNLOAD=1` +- Cache directory: `KODE_BIN_DIR` + +See `docs/binary-distribution.md`. -- **Git Bash is optional**: Kode now works natively with Windows cmd.exe and PowerShell. - - Kode automatically prefers Git Bash/MSYS or WSL Bash when available for better Unix compatibility. - - If neither is available, it uses cmd.exe which works out of the box. -- For best experience, consider using VS Code's integrated terminal: - - Better font rendering and icon support. - - Fewer path and encoding quirks compared to legacy Command Prompt. -- Optional: Install Git for Windows for enhanced Unix-like functionality: https://git-scm.com/download/win -- If you install globally via npm, avoid spaces in the global prefix path to prevent shim issues. - - Example: `npm config set prefix "C:\\npm"` and reinstall global packages. +### Configuration / API keys + +- Global config (models, pointers, theme, etc): `~/.kode.json` (or `/config.json` when `KODE_CONFIG_DIR`/`CLAUDE_CONFIG_DIR` is set). +- Project/local settings (output style, etc): `./.kode/settings.json` and `./.kode/settings.local.json` (legacy `.claude` is supported for some features). +- Configure models via `/model` (UI) or `kode models import/export` (YAML). Details: `docs/develop/configuration.md`. ## Usage @@ -132,6 +164,24 @@ kode -p "explain this function" path/to/file.js kwa -p "explain this function" path/to/file.js ``` +### ACP (Agent Client Protocol) + +Run Kode as an ACP agent server (stdio JSON-RPC), for clients like Toad/Zed: + +```bash +kode-acp +# or +kode --acp +``` + +Toad example: + +```bash +toad acp "kode-acp" +``` + +More: `docs/acp.md`. + ### Using the @ Mention System Kode supports a powerful @ mention system for intelligent completions: @@ -155,13 +205,61 @@ Kode supports a powerful @ mention system for intelligent completions: #### 📁 Smart File References ```bash # Reference files and directories with auto-completion -@src/components/Button.tsx -@docs/api-reference.md +@packages/core/src/query/index.ts +@docs/README.md @.env.example ``` The @ mention system provides intelligent completions as you type, showing available models, agents, and files. +### MCP Servers (Extensions) + +Kode can connect to MCP servers to extend tools and context. + +- Config files: `.mcp.json` (recommended) or `.mcprc` in your project root. See `docs/mcp.md`. +- CLI: + +```bash +kode mcp add +kode mcp list +kode mcp get +kode mcp remove +``` + +Example `.mcprc`: + +```json +{ + "my-sse-server": { "type": "sse", "url": "http://127.0.0.1:3333/sse" } +} +``` + +### Permissions & Approvals + +- Default mode skips most prompts for speed. +- Safe mode: `kode --safe` requires approval for Bash commands and file writes/edits. +- Plan mode: the assistant may ask to enter plan mode to draft a plan file; while in plan mode, only read-only/planning tools (and the plan file) are allowed until you approve exiting plan mode. + +### Paste & Images + +- Multi-line/large paste is inserted as a placeholder and expanded on submit. +- Pasting multiple existing file paths inserts `@path` mentions automatically (quoted when needed). +- Image paste (macOS): press `Ctrl+V` to attach clipboard images; you can paste multiple images before sending. + +### System Sandbox (Linux) + +- In safe mode (or with `KODE_SYSTEM_SANDBOX=1`), agent-triggered Bash tool calls try to run inside a `bwrap` sandbox when available. +- Network is disabled by default; set `KODE_SYSTEM_SANDBOX_NETWORK=inherit` to allow network. +- Set `KODE_SYSTEM_SANDBOX=required` to fail closed if sandbox cannot be started. +- See `docs/system-sandbox.md` for details and platform notes. + +### Troubleshooting + +- Models: use `/model`, or `kode models import kode-models.yaml`, and ensure required API key env vars exist. +- Windows: if the native binary download is blocked/offline, set `KODE_BINARY_BASE_URL` (mirror) or `KODE_SKIP_BINARY_DOWNLOAD=1` (skip download); the wrapper will fall back to the Node.js runtime (`dist/index.js`). +- MCP: use `kode mcp list` to check server status; tune `MCP_CONNECTION_TIMEOUT_MS`, `MCP_SERVER_CONNECTION_BATCH_SIZE`, and `MCP_TOOL_TIMEOUT` if servers are slow. +- Sandbox: install `bwrap` (bubblewrap) on Linux, or set `KODE_SYSTEM_SANDBOX=0` to disable. + ### AGENTS.md Documentation Mode Use the `#` prefix to generate and maintain your AGENTS.md documentation: @@ -229,21 +327,145 @@ As long as you have an openai-like endpoint, it should work. - `/help` - Show available commands - `/model` - Change AI model settings - `/config` - Open configuration panel +- `/agents` - Manage subagents +- `/output-style` - Set the output style +- `/statusline` - Configure a custom status line command - `/cost` - Show token usage and costs - `/clear` - Clear conversation history -- `/compact-threshold` - View or set auto-compact threshold ratio (e.g. `/compact-threshold 0.85` or `/compact-threshold 85%`) +- `/init` - Initialize project context +- `/plugin` - Manage plugins/marketplaces (skills, commands) - | Value | Effect | Use Case | - |-------|--------|----------| - | 0.80 | Compress earlier, more conservative | Small context models (e.g. deepseek 131k) | - | 0.85 | Balanced | Medium context models | - | 0.90 | Default | Large context models (e.g. Claude 200k) | +## Agents / Subagents -- `/init` - Initialize project context +Kode supports subagents (agent templates) for delegation and task orchestration. + +- Agents are loaded from `.kode/agents` and `.claude/agents` (user + project), plus plugins/policy and `--agents`. +- Manage in the UI: `/agents` (creates new agents under `./.claude/agents` / `~/.claude/agents` by default). +- Run via mentions: `@run-agent- ...` +- Run via tooling: `Task(subagent_type: "", ...)` +- CLI flags: `--agents ` (inject agents for this run), `--setting-sources user,project,local` (control which sources are loaded) + +Minimal agent file example (`./.kode/agents/reviewer.md`): + +```md +--- +name: reviewer +description: "Review diffs for correctness, security, and simplicity" +tools: ["Read", "Grep"] +model: inherit +--- + +Be strict. Point out bugs and risky changes. Prefer small, targeted fixes. +``` + +Model field notes: +- Compatibility aliases: `inherit`, `opus`, `sonnet`, `haiku` (mapped to model pointers) +- Kode selectors (via `/model`): pointers (`main|task|compact|quick`), profile name, modelName, or `provider:modelName` (e.g. `openai:o3`) + +Validate agent templates: + +```bash +kode agents validate +``` + +See `docs/agents-system.md`. + +## Skills & Plugins + +Kode supports the [Agent Skills](https://agentskills.io) open format for extending agent capabilities: +- **Agent Skills** format (`SKILL.md`) - see [specification](https://agentskills.io/specification) +- **Marketplace compatibility** (`.kode-plugin/marketplace.json`, legacy `.claude-plugin/marketplace.json`) +- **Install from any repository** using [`add-skill` CLI](https://github.com/vercel-labs/add-skill) + +### Quick install with add-skill + +Install skills from any git repository: + +```bash +# Install from GitHub +npx add-skill vercel-labs/agent-skills -a kode + +# Install to global directory +npx add-skill vercel-labs/agent-skills -a kode -g + +# Install specific skills +npx add-skill vercel-labs/agent-skills -a kode -s pdf -s xlsx +``` + +### Install skills from a marketplace + +```bash +# Add a marketplace (local path, GitHub owner/repo, or URL) +kode plugin marketplace add ./path/to/marketplace-repo +kode plugin marketplace add owner/repo +kode plugin marketplace list + +# Install a plugin pack (installs skills/commands) +kode plugin install document-skills@anthropic-agent-skills --scope user + +# Project-scoped install (writes to ./.kode/...) +kode plugin install document-skills@anthropic-agent-skills --scope project + +# Disable/enable an installed plugin +kode plugin disable document-skills@anthropic-agent-skills --scope user +kode plugin enable document-skills@anthropic-agent-skills --scope user +``` + +Interactive equivalents: + +```text +/plugin marketplace add owner/repo +/plugin install document-skills@anthropic-agent-skills --scope user +``` + +### Use skills + +- In interactive mode, run a skill as a slash command: `/pdf`, `/xlsx`, etc. +- Kode can also invoke skills automatically via the `Skill` tool when relevant. + +### Create a skill (Agent Skills) + +Create `./.kode/skills//SKILL.md` (project) or `~/.kode/skills//SKILL.md` (user): + +```md +--- +name: my-skill +description: Describe what this skill does and when to use it. +allowed-tools: Read Bash(git:*) Bash(jq:*) +--- + +# Skill instructions +``` + +Naming rules: +- `name` must match the folder name +- Lowercase letters/numbers/hyphens only, 1–64 chars + +Compatibility: +- Kode also discovers `.claude/skills` and `.claude/commands` for legacy compatibility. + +### Distribute skills + +- Marketplace repo: publish a repo containing `.kode-plugin/marketplace.json` listing plugin packs and their `skills` directories (legacy `.claude-plugin/marketplace.json` is also supported). +- Plugin repo: for full plugins (beyond skills), include `.kode-plugin/plugin.json` at the plugin root and keep all paths relative (`./...`). + +See `docs/skills.md` for a compact reference and examples. + +### Output styles + +Use output styles to switch system-prompt behavior. + +- Select: `/output-style` (menu) or `/output-style