Skip to content

PLATFORM_SPEC.md — Kimi Code CLI (Moonshot AI)

New to gald3r on this platform? Start at Use gald3r with Kimi Code for a short overview before the full breakdown below.

The tool branded kimi for coding is Kimi Code, delivered primarily as the open-source Kimi Code CLI (MoonshotAI/kimi-code, renamed from MoonshotAI/kimi-cli in the same 2026 release that moved the CLI from Python/uv to Node.js) plus a VS Code extension and third-party editor integrations (JetBrains, Zed via ACP). Model id: kimi-for-coding / kimi-k2 family. As of early-July-2026 the Kimi Code CLI natively supports all six gald3r-relevant extension primitives — Agent Skills, rules/memory, subagents, lifecycle hooks, MCP, and user-defined commands (expressed through Skills + Plugins).

Rebrand impact on gald3r (read this first): the repo rename kimi-cli → kimi-code carried a config-directory rename: project-level .kimi/ → .kimi-code/, and the user-level home ~/.kimi/ → ~/.kimi-code/ (overridable via the KIMI_CODE_HOME env var). The skill cross-discovery set also changed — the current docs list .kimi-code/skills/ and .agents/skills/ (project) plus $KIMI_CODE_HOME/skills/ and ~/.agents/skills/ (user); they no longer document .claude/skills/ or .codex/skills/ as discovery paths. Treat the old .claude/skills/-reuse claim as no longer verified — gald3r's SKILL.md tree should be shipped into .kimi-code/skills/ (or .agents/skills/) for Kimi, not assumed to load from .claude/skills/.

Authoring path: UPDATE. Re-verified 2026-07-03 against https://www.kimi.com/code/docs/en (mirror https://moonshotai.github.io/kimi-code/en/ — see Verification Evidence). Overall readiness: full — nearly the complete gald3r primitive set is natively supported.

Instruction-file convention: Kimi's canonical project-instruction file is AGENTS.md (generated by /init, injected into the system prompt via the built-in KIMI_AGENTS_MD template variable) — not CLAUDE.md. This is unchanged by the rebrand. AGENTS.md is also read at $KIMI_CODE_HOME/AGENTS.md (global) and ~/.agents/AGENTS.md (cross-tool).

Maturity caveat: Custom Plugins remain Beta. Hooks are documented as a complete customization surface in the new docs (no explicit Beta marker seen in the rebrand docs), but re-verify on the next scan since the underlying runtime changed (Python/uv → Node.js). User-defined commands are expressed through Skills/Plugins rather than a dedicated standalone slash-command authoring file.

1. Folder Hierarchy

<project-root>/
├── AGENTS.md                            ← instruction file (generated by /init; injected via KIMI_AGENTS_MD)
├── .kimi-code/
│   ├── local.toml                       ← project-local workspace settings (gitignored)
│   └── skills/   <name>/SKILL.md        ← Agent Skills (YAML frontmatter + Markdown body)
└── .agents/skills/ <name>/SKILL.md      ← ALSO discovered by Kimi (cross-tool compatible)

$KIMI_CODE_HOME/            (default ~/.kimi-code/)
├── config.toml                          ← hooks ([[hooks]]) + settings (TOML)
├── tui.toml                             ← UI preferences
├── AGENTS.md                            ← global instruction file
├── skills/   <name>/SKILL.md            ← user-level skills
├── agents/   <name>.yaml                ← built-in / custom agent specs (also --agent-file)
└── plugins/  <name>/plugin.json         ← Custom Plugins (Beta), via `kimi plugin install`

~/.agents/
├── AGENTS.md                            ← cross-tool global instructions
└── skills/   <name>/SKILL.md            ← cross-tool user-level skills

Skill discovery order: Project > User > Extra > Built-in. Extra dirs via --skills-dir or extra_skill_dirs config. As of the kimi-code rebrand, verified cross-tool discovery is limited to .agents/skills/ (project) and ~/.agents/skills/ (user) — .claude/skills/ and .codex/skills/ are no longer listed in the current skills doc (see Verification Evidence). Re-verify before relying on legacy .claude//.codex/ reuse.

gald3r writes: AGENTS.md; Agent Skills (SKILL.md) into .kimi-code/skills/ (native) and/or .agents/skills/ (cross-tool); subagent YAML specs; hooks in $KIMI_CODE_HOME/config.toml (default ~/.kimi-code/config.toml); MCP servers via kimi mcp / /mcp-config. Kimi owns: the config.toml schema, the KIMI_AGENTS_MD injection mechanism, and the built-in subagents (coder, explore, plan).

2. AI Instruction File

Kimi reads AGENTS.md as the project instruction file. If absent, /init analyzes the project and generates it; it is then injected into the Agent system prompt via the built-in KIMI_AGENTS_MD template variable, so it persists as always-on project context for the session. No CLAUDE.md or KIMI.md is required. Unchanged by the kimi-cli → kimi-code rebrand. The current docs also confirm AGENTS.md at $KIMI_CODE_HOME/AGENTS.md (global) and ~/.agents/AGENTS.md (cross-tool) as additional scopes. gald3r's AGENTS.md is the first-class instruction input on Kimi.

3. Agents Support — ✅ NATIVE

  • Agents & Subagents. Built-in subagents (coder, explore, plan) dispatch in isolated contexts. Users define custom agents/subagents as YAML agent-spec files loaded via kimi --agent-file /path/to/my-agent.yaml (or built-in agents under src/kimi_cli/agents/).
  • Agent specs support extend (inheritance), name, system_prompt_path, tools (module:ClassName), exclude_tools, and a subagents block. Subagents are prohibited from nesting the Agent tool (no recursive nesting).
  • gald3r g-agnt-* definitions map to Kimi YAML agent specs.
  • Source: https://moonshotai.github.io/kimi-code/en/customization/agents.html

4. Skills Support — ✅ NATIVE

  • Agent Skills using SKILL.md (YAML frontmatter + Markdown prompt body). Required frontmatter for directory-form skills: name and description. Optional: type (prompt | inline | flow), whenToUse (auto-invocation triggers), disableModelInvocation, arguments (named params exposed as $<name> placeholders).
  • Discovery tiers (rebrand-current): user $KIMI_CODE_HOME/skills/ (default ~/.kimi-code/skills/) and ~/.agents/skills/; project .kimi-code/skills/ and .agents/skills/; extra via extra_skill_dirs in config.toml; built-in lowest priority. .claude/skills/ and .codex/skills/ are no longer documented as discovery paths post-rebrand — gald3r should ship SKILL.md into .kimi-code/skills/ (native) or .agents/skills/ (cross-tool with other AGENTS.md-native platforms), not rely on .claude/ reuse for Kimi specifically.
  • Manual invocation: /skill:<name> (e.g. /skill:git-commits fix concurrency issue passes arguments). Automatic invocation uses description/whenToUse unless disableModelInvocation or type: flow restricts it.
  • Flow skills (type: flow) embed Mermaid/ Agent Flow diagrams with BEGIN/END nodes for multi-step automated workflows, run via /flow:<name> — an adoptable workflow-automation primitive beyond plain prompt skills.
  • Source: https://moonshotai.github.io/kimi-code/en/customization/skills.html

5. Commands / Workflows — ✅ NATIVE

  • User-authored commands are expressed via Agent Skills invoked as /skill:<name> and Flow skills as /flow:<name> (saved prompt templates), plus Custom Plugins (Beta) that declare executable tools via plugin.json. /skill:<name> "reads the corresponding SKILL.md file content and sends it to the Agent as a prompt."
  • Built-in /-commands (/help, /init, /hooks, /mcp-config, etc.) are not user-extensible. There is no separate top-level slash-command authoring file distinct from Skills — Skills + Plugins are the documented user-defined-command path.
  • gald3r @g-* / /g-* commands map to Kimi Skills (/skill:<name>).
  • Source: https://moonshotai.github.io/kimi-code/en/customization/skills.html

6. Hooks System — ✅ NATIVE

  • 13 lifecycle events (rebrand docs list these; some renamed/added vs. the pre-rebrand set): SessionStart, SessionEnd, PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, Stop, SubagentStart, SubagentStop, PermissionRequest, PermissionResult, Notification (+ blockable markers on UserPromptSubmit, PreToolUse, Stop). Re-verify the exact 13-name list on the next scan — PermissionRequest/PermissionResult appear new vs. the pre-rebrand PreCompact/PostCompact/StopFailure naming; both sets are recorded here pending a full diff.
  • Defined in $KIMI_CODE_HOME/config.toml (default ~/.kimi-code/config.toml) using [[hooks]] array syntax with fields event + command (shell command) required, optional matcher (regex) and timeout (1–600s, default 30s). Hooks receive JSON on stdin; exit 0 = allow, exit 2 = block, other = log only. Managed/viewed via /hooks.
  • Use cases: auto-format, security checks blocking dangerous ops, protecting sensitive files, desktop notifications, verifying task completion before session close — so gald3r SessionStart context injection, PreToolUse .gald3r/ guards, and pre-commit gates wire in via shell commands.
  • OS note: hook command is an arbitrary shell command; gald3r g-hk-*.py hooks run by invoking python <path> directly (no PowerShell involved — Kimi Code is cross-platform and shell-agnostic).
  • gald3r wiring status (re-verified 2026-08-30): still not wired in layout_map.yaml — [[hooks]] registration lives only in the USER-GLOBAL $KIMI_CODE_HOME/config.toml; .kimi-code/local.toml is documented as project-local settings, never hooks. A 2026-08-30 live re-fetch surfaced one new, potentially useful detail for a future pass: "the working directory for hook commands is the current session's project directory" — i.e. the OS-level process cwd genuinely tracks the active project, unlike Hermes. That is real signal a relative-path command COULD resolve correctly per-project, but it does not remove the actual blocker (the registration file itself is still global with no project override), and this repo has no live Kimi install to confirm the behavior described. Left unwired; see layout_map.yaml's own kimi comment block for the full citation.
  • Source: https://moonshotai.github.io/kimi-code/en/customization/hooks.html

7. Rules / Memory — ✅ NATIVE

  • AGENTS.md is the always-on project instruction/memory file, injected via KIMI_AGENTS_MD into the Agent system prompt. Generated/refreshed by /init. This is Kimi's rules surface — a single project instruction file rather than a multi-file rules/ directory.
  • gald3r g-rl-* content maps into AGENTS.md sections (Kimi has no documented per-file globs:-scoped rule directory; consolidate rule guidance into AGENTS.md).
  • Source: https://moonshotai.github.io/kimi-code/en/guides/getting-started.html

8. MCP Support — ✅ NATIVE

  • Model Context Protocol (MCP) tools. Managed via the kimi mcp sub-command group and conversationally via /mcp-config (AI-native add/edit/authenticate without hand-editing JSON). Servers add tools the agent can call.
  • Source: https://moonshotai.github.io/kimi-code/en/customization/skills.html

9. Plugins / Distribution — distribution channel (Beta)

  • Custom Plugins (Beta): a plugin is a directory with plugin.json declaring executable tools (Python/TypeScript/shell) the AI can invoke; tools take JSON-Schema parameters, receive stdin, return stdout. Installed via kimi plugin install <dir|zip|git-url>, stored in $KIMI_CODE_HOME/plugins/ (default ~/.kimi-code/plugins/). Distinct from MCP (lightweight local toolkits) and from Skills (knowledge/prompt guidance). Official Plugins also exist. This is a natural distribution channel for gald3r executable tooling on Kimi.
  • API compatibility: exposes OpenAI-compatible and Anthropic-compatible endpoints (kimi-for-coding), plus VS Code extension and ACP/Wire-Protocol integration for third-party editors (JetBrains, Zed, Zsh).
  • Source: https://moonshotai.github.io/kimi-code/en/customization/skills.html

Parity vs. Cursor Reference

Kimi reaches near-full parity with the Cursor reference (g-skl-platform-cursor): native commands (via Skills/Plugins), rules (AGENTS.md), agents, skills, hooks, and MCP. Caveats: the full surface is CLI-centric; Custom Plugins are Beta; rules are a single AGENTS.md file rather than a scoped rules/ directory; and user-defined commands are expressed through Skills/Plugins (no standalone slash-command authoring file). Flow skills (Mermaid/ workflow automation) are a Kimi-native bonus with no direct Cursor analog.

Reuse note (rebrand-updated): the current docs list .agents/skills/ (project + user) as the cross-tool discovery path, not .claude/skills//.codex/skills/ — that legacy claim is unverified post-rebrand. The highest-confidence Kimi install ships gald3r's SKILL.md tree into .kimi-code/skills/ (native) or .agents/skills/ (cross-tool with other AGENTS.md-native platforms), plus an AGENTS.md, with hooks wired in $KIMI_CODE_HOME/config.toml (default ~/.kimi-code/config.toml).

Hook System

  • Type: native — $KIMI_CODE_HOME/config.toml (default ~/.kimi-code/config.toml) [[hooks]] array
  • Config file: ~/.kimi-code/config.toml (TOML; relocatable via KIMI_CODE_HOME)
  • Events available (rebrand docs): SessionStart, SessionEnd, PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, Stop, SubagentStart, SubagentStop, PermissionRequest, PermissionResult, Notification (partial list confirmed; full 13-event enumeration pending a dedicated re-scan — see rebrand_note in frontmatter)
  • Event payload format: JSON via stdin; result via exit codes (0 allow / 2 block / other = log only); optional matcher regex + timeout (1-600s, default 30s)
  • Command extensions: arbitrary shell command; g-hk-*.py wire via python <path> (no PowerShell involved — cross-platform agent)
  • Maturity: documented as a complete customization surface post-rebrand; re-verify stability given the Python/uv → Node.js runtime change

Atypical Handling

  • Instruction file is AGENTS.md, not CLAUDE.md — inject gald3r guidance there (Kimi uses the KIMI_AGENTS_MD template variable). Post-rebrand, skills load from .kimi-code/skills/ / .agents/skills/ — do not assume .claude/skills//.codex/skills/ reuse without re-checking.
  • Config directory renamed: .kimi/ → .kimi-code/ (project), ~/.kimi/ → ~/.kimi-code/ (user, overridable via KIMI_CODE_HOME). Config is TOML (config.toml) for hooks/settings; agent specs are YAML; skills are SKILL.md (YAML frontmatter + Markdown). Three different formats across surfaces.
  • User-defined commands = Skills/Plugins — there is no dedicated standalone slash-command file; map gald3r commands to /skill:<name>.
  • Custom Plugins remain Beta — do not assume long-term config stability for plugin.json; re-verify on each scan.

gald3r Integration Notes

  • Ship gald3r's SKILL.md tree into .kimi-code/skills/ (native) or .agents/skills/ (cross-tool) + an AGENTS.md instruction file (or run /init).
  • Wire hooks in $KIMI_CODE_HOME/config.toml (default ~/.kimi-code/config.toml) via [[hooks]]; invoke g-hk-*.py through python <path> (no PowerShell involved).
  • Map gald3r commands to Kimi /skill:<name>; consider Flow skills (type: flow) for multi-step gald3r workflows and Custom Plugins for executable tooling.
  • Re-verify on the next @g-platform-scan-docs kimi (crawl_max_age_days: 14) — confirm the full 13-event hook list and Plugin maturity post rebrand; the old .claude/skills/ cross-discovery claim should be treated as retired unless a future scan reinstates it.

Capability Summary

Hooks Rules Skills Commands MCP Docs Fresh
✅ ✅ ✅ ✅ ✅ ✅

Legend: ✅ verified working · ⚠️ partial / Cursor-generic · ❌ not supported · ❓ untested.

Verification Evidence

Rebrand re-scan (2026-07-03) — https://www.kimi.com/code/docs/en — mirror https://moonshotai.github.io/kimi-code/en/

Capability How verified
Rebrand Repo MoonshotAI/kimi-cli renamed MoonshotAI/kimi-code (v0.22.2, 2026-07-03); www.kimi.com/code/docs confirms "major version upgrade — moving from Python/uv to Node.js", legacy Python docs frozen/no-longer-maintained. "Kcode" is not a separate product — no independent product of that name is verifiable in English or Chinese sources; every signal (repo, docs, GitHub Copilot GA note) resolves to this same Kimi Code / Kimi K2.7 Code rebrand.
Config home /configuration/config-files — ~/.kimi-code/config.toml (default), ~/.kimi-code/tui.toml; override via KIMI_CODE_HOME env var; project-local <project-root>/.kimi-code/local.toml (gitignored)
Skills /customization/skills — SKILL.md (name+description required; optional type/whenToUse/disableModelInvocation/arguments); discovery = $KIMI_CODE_HOME/skills/ + ~/.agents/skills/ (user), .kimi-code/skills/ + .agents/skills/ (project), extra_skill_dirs (extra), built-in (lowest) — .claude/skills//.codex/skills/ not listed
Commands /customization/skills — /skill:<name> (manual, supports arguments) + /flow:<name>; automatic invocation via description/whenToUse unless disableModelInvocation/type: flow
Hooks /customization/hooks — ~/.kimi-code/config.toml [[hooks]]; fields event/command required, matcher/timeout (1-600s, default 30) optional; JSON stdin; exit 0 allow / 2 block / other log-only; events include SessionStart, SessionEnd, PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, Stop, SubagentStart, SubagentStop, PermissionRequest, PermissionResult, Notification (blockable: UserPromptSubmit/PreToolUse/Stop)
Agents /customization/agents — global $KIMI_CODE_HOME/AGENTS.md (default ~/.kimi-code/AGENTS.md), cross-tool ~/.agents/AGENTS.md, project .kimi-code/AGENTS.md or AGENTS.md; single AGENTS.md convention confirmed, no KIMI.md/CLAUDE.md alternative
Rules/Instructions /guides/getting-started — confirms ~/.kimi-code/ as the default local-data directory, KIMI_CODE_HOME override
Cross-compat (changed) Rebrand docs list .agents/skills/ for cross-tool discovery; .claude/skills//.codex/skills/ reuse claim from the pre-rebrand spec is not reproduced in current docs — downgraded to unverified until a future scan confirms either way

Sources cited by the task brief and cross-checked here: https://github.com/MoonshotAI/kimi-code ; https://www.techtimes.com/articles/319556/20260702/open-weight-ai-enters-github-copilot-kimi-k27-code-costs-less-audits-differently.htm

Prior scan (2026-06-02) — https://moonshotai.github.io/kimi-cli/en/ (pre-rebrand mirror, now superseded)

Capability How verified
Commands /customization/skills — user commands via /skill:<name> + /flow:<name> (Skills) and Custom Plugins (Beta); built-in /-commands not user-extensible
Rules /guides/getting-started — AGENTS.md generated by /init, injected via KIMI_AGENTS_MD system-prompt variable (always-on context)
Agents /customization/agents — built-in coder/explore/plan subagents; custom YAML specs via --agent-file (extend/tools/exclude_tools/subagents)
Skills /customization/skills — SKILL.md (YAML frontmatter + Markdown); discovered .kimi/.claude/.codex/.agents skills dirs (pre-rebrand); Flow skills type: flow
Hooks /customization/hooks — ~/.kimi/config.toml [[hooks]]; 13 events; JSON stdin; exit 0 allow / 2 block; Beta
MCP /customization/skills — kimi mcp sub-command group + /mcp-config (AI-native, no JSON hand-editing)
Plugins /customization (Custom Plugins, Beta) — plugin.json executable tools; kimi plugin install; stored ~/.kimi/plugins/
Cross-compat Pre-rebrand docs claimed .claude/skills/ + .codex/skills/ discovery — superseded, see rebrand re-scan above

Reference page — canonical source: g-skl-platform-kimi/PLATFORM_SPEC.md in the engine repo, generated by scripts/generate_platform_support_docs.py. Pages marked curated are hand-assessed and not yet live-verified.