From f2dea0a67759ff073f3a881082a3404f9bb42f52 Mon Sep 17 00:00:00 2001 From: Alex Alecu Date: Tue, 7 Apr 2026 10:49:46 +0300 Subject: [PATCH 1/9] docs(cli): add legacy paths to kilo-config skill The built-in kilo-config skill only documented modern config paths (.kilo/, ~/.config/kilo/), but the CLI still loads legacy directories (.kilocode/, .opencode/) at every session. Users with configs in legacy locations got no guidance from the agent. Expand the Config File Locations section to document all scanned directories, glob patterns with plural variants, legacy config filenames, and environment variable overrides. --- .../src/kilocode/skills/kilo-config.md | 61 +++++++++++++++---- 1 file changed, 50 insertions(+), 11 deletions(-) diff --git a/packages/opencode/src/kilocode/skills/kilo-config.md b/packages/opencode/src/kilocode/skills/kilo-config.md index 70289d08dcd..e34a77f7518 100644 --- a/packages/opencode/src/kilocode/skills/kilo-config.md +++ b/packages/opencode/src/kilocode/skills/kilo-config.md @@ -4,7 +4,7 @@ All config lives in `kilo.json` (or `kilo.jsonc`). Precedence low-to-high: remot ## Commands (`.kilo/command/*.md`) -Markdown files with YAML frontmatter. The filename (minus `.md`) becomes the command name invoked via `/name`. +Markdown files with YAML frontmatter. The filename (minus `.md`) becomes the command name invoked via `/name`. Also loaded from `.kilocode/` and `.opencode/` directories (legacy), and plural `commands/` variants. See Config File Locations for the full search order. ```yaml --- @@ -22,6 +22,8 @@ Template variables: `$1`-`$N` (positional args), `$ARGUMENTS` (full string), `@f ## Agents (`.kilo/agent/*.md`) +Also loaded from `.kilocode/` and `.opencode/` directories (legacy), and plural `agents/` variants. + ```yaml --- description: When to use this agent @@ -127,7 +129,7 @@ Additional skill directories and remote URLs: } ``` -Skills are markdown files at `skills//SKILL.md` with `name` and `description` in frontmatter. +Skills are markdown files at `skills//SKILL.md` (or `skill//SKILL.md`) with `name` and `description` in frontmatter. Discovered inside `.kilo/`, `.kilocode/`, and `.opencode/` directories. ## Other Top-Level Fields @@ -200,12 +202,49 @@ Toggle notifications, Toggle animations, Toggle diff wrapping, Toggle sidebar (` ## Config File Locations -| Scope | Path | -| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Project | `./kilo.json`, `./.kilo/kilo.json` | -| Global | `~/.config/kilo/kilo.json` | -| Managed | Linux: `/etc/kilo/kilo.json`, macOS: `/Library/Application Support/kilo/kilo.json`, Windows: `%ProgramData%\kilo\kilo.json` (enterprise, highest priority) | -| Commands | `.kilo/command/*.md` (project), `~/.config/kilo/command/*.md` (global) | -| Agents | `.kilo/agent/*.md` (project), `~/.config/kilo/agent/*.md` (global) | -| Skills | `.kilo/skill/*/SKILL.md`, `.kilo/skills/*/SKILL.md` | -| Instructions | `AGENTS.md`, `.kilo/instructions.md`, glob patterns from `instructions` | +### Config files (kilo.json) + +| Scope | Path | +| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Project | `./kilo.json`, `./kilo.jsonc`, `./opencode.json` (legacy), `./opencode.jsonc` (legacy) | +| Global | `~/.config/kilo/kilo.json`, `~/.config/kilo/kilo.jsonc`, `~/.config/kilo/opencode.json` (legacy), `~/.config/kilo/config.json` (legacy) | +| Managed | Linux: `/etc/kilo/kilo.json`, macOS: `/Library/Application Support/kilo/kilo.json`, Windows: `%ProgramData%\kilo\kilo.json` (enterprise, highest priority) | + +Each config directory (`.kilo/`, `.kilocode/`, `.opencode/`) can also contain `kilo.json`, `kilo.jsonc`, `opencode.json`, or `opencode.jsonc`. + +### Config directories + +Three directory names are scanned: `.kilo` (modern), `.kilocode` (legacy), `.opencode` (legacy). All three are checked at each level: + +- **Project**: walks up from CWD to the git worktree root, checking for all three at each directory level +- **Home**: `~/.kilo/`, `~/.kilocode/`, `~/.opencode/` +- **XDG global**: `~/.config/kilo/` (always loaded, lowest file-based precedence) + +### Commands, agents, modes, plugins + +Glob patterns run inside every discovered config directory (including legacy): + +| Type | Pattern | +| ------- | ---------------------------- | +| Command | `{command,commands}/**/*.md` | +| Agent | `{agent,agents}/**/*.md` | +| Mode | `{mode,modes}/*.md` | +| Plugin | `{plugin,plugins}/*.{ts,js}` | + +Example: `~/.config/kilo/command/*.md` (modern global), `~/.kilocode/command/*.md` (legacy global), `.opencode/commands/*.md` (legacy project) all load commands. + +### Skills and instructions + +| Scope | Path | +| ------------ | ----------------------------------------------------------------------- | +| Skills | `{skill,skills}//SKILL.md` inside any config directory | +| Instructions | `AGENTS.md`, `.kilo/instructions.md`, glob patterns from `instructions` | + +### Environment variable overrides + +| Variable | Description | +| ----------------------------- | ---------------------------------------------------------------- | +| `KILO_CONFIG` | Path to an additional config file (loaded after global) | +| `KILO_CONFIG_DIR` | Path to an additional config directory (appended to search list) | +| `KILO_CONFIG_CONTENT` | Inline JSON config string (high precedence, after project dirs) | +| `KILO_DISABLE_PROJECT_CONFIG` | Skip project-level `.kilo`/`.kilocode`/`.opencode` directories | From 6a7c296d341291d8a773846df9846cc0ba62d18b Mon Sep 17 00:00:00 2001 From: Alex Alecu Date: Tue, 7 Apr 2026 10:59:54 +0300 Subject: [PATCH 2/9] fix(cli): widen kilo-config skill to cover path location questions The skill description and opening paragraph now explicitly mention locating config/command/agent/skill paths across global, project, and legacy directories (.kilo/, .kilocode/, .opencode/, ~/.config/kilo/). This ensures the agent loads the skill for 'where is this command?' prompts, not just configure/customize prompts. --- packages/opencode/src/kilocode/skills/builtin.ts | 2 +- packages/opencode/src/kilocode/skills/kilo-config.md | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/packages/opencode/src/kilocode/skills/builtin.ts b/packages/opencode/src/kilocode/skills/builtin.ts index 9172a39cf95..96accd8f5ad 100644 --- a/packages/opencode/src/kilocode/skills/builtin.ts +++ b/packages/opencode/src/kilocode/skills/builtin.ts @@ -15,7 +15,7 @@ export const BUILTIN_SKILLS: BuiltinSkill[] = [ { name: "kilo-config", description: - "Guide for configuring Kilo CLI: commands, agents, MCP servers, skills, permissions, instructions, plugins, providers, all kilo.json fields, and TUI settings (themes, appearance, keybinds, ctrl+p commands). Use when the user asks about configuring, customizing, or changing settings in Kilo.", + "Guide for configuring Kilo CLI and locating config, command, agent, and skill paths (global, project, legacy), plus MCP servers, permissions, instructions, plugins, providers, kilo.json fields, and TUI settings (themes, appearance, keybinds, ctrl+p commands). Use when the user asks about configuring Kilo, where it loads things from, or how to change settings.", content: KILO_CONFIG, }, ] diff --git a/packages/opencode/src/kilocode/skills/kilo-config.md b/packages/opencode/src/kilocode/skills/kilo-config.md index e34a77f7518..cc2540678f8 100644 --- a/packages/opencode/src/kilocode/skills/kilo-config.md +++ b/packages/opencode/src/kilocode/skills/kilo-config.md @@ -2,6 +2,8 @@ All config lives in `kilo.json` (or `kilo.jsonc`). Precedence low-to-high: remote well-known, global (`~/.config/kilo/kilo.json`), env `KILO_CONFIG`, project `./kilo.json`, `.kilo/kilo.json`, `KILO_CONFIG_CONTENT`, managed (see Config File Locations). Deep-merged; later wins. +This also covers where Kilo looks for config files, commands, agents, and skills across project, global, and legacy paths such as `.kilo/`, `.kilocode/`, `.opencode/`, and `~/.config/kilo/`. + ## Commands (`.kilo/command/*.md`) Markdown files with YAML frontmatter. The filename (minus `.md`) becomes the command name invoked via `/name`. Also loaded from `.kilocode/` and `.opencode/` directories (legacy), and plural `commands/` variants. See Config File Locations for the full search order. From cafccaf68760f59eb6a4a754fd1b7533b6ba311a Mon Sep 17 00:00:00 2001 From: Alex Alecu Date: Tue, 7 Apr 2026 14:10:10 +0300 Subject: [PATCH 3/9] fix(cli): add named-command lookup guidance to kilo-config skill The skill loaded but the agent still only searched the repo root when asked 'where is /review-pr?'. Add an explicit procedural subsection that tells the agent to search ~/.config/kilo/, ~/.kilo/, ~/.kilocode/, and ~/.opencode/ with explicit path arguments before falling back to project directories. Add a regression test verifying the guidance is present in the builtin skill output. --- .../src/kilocode/skills/kilo-config.md | 19 ++++++++++- packages/opencode/test/tool/skill.test.ts | 32 +++++++++++++++++++ 2 files changed, 50 insertions(+), 1 deletion(-) diff --git a/packages/opencode/src/kilocode/skills/kilo-config.md b/packages/opencode/src/kilocode/skills/kilo-config.md index cc2540678f8..e8e763a2e16 100644 --- a/packages/opencode/src/kilocode/skills/kilo-config.md +++ b/packages/opencode/src/kilocode/skills/kilo-config.md @@ -6,7 +6,7 @@ This also covers where Kilo looks for config files, commands, agents, and skills ## Commands (`.kilo/command/*.md`) -Markdown files with YAML frontmatter. The filename (minus `.md`) becomes the command name invoked via `/name`. Also loaded from `.kilocode/` and `.opencode/` directories (legacy), and plural `commands/` variants. See Config File Locations for the full search order. +Markdown files with YAML frontmatter. The filename (minus `.md`) becomes the command name invoked via `/name`. Commands can live in `.kilo/`, `.kilocode/`, `.opencode/`, and global config roots, with both `command/` and `commands/` directory names supported. See Config File Locations for the full search order. ```yaml --- @@ -22,6 +22,23 @@ Reference files with @file and shell output with !`cmd`. Template variables: `$1`-`$N` (positional args), `$ARGUMENTS` (full string), `@file` (file contents), `` !`cmd` `` (shell output). +### Finding a named command + +When asked where `/name` lives, do not search only the repo root. Search these roots explicitly, and use an explicit search `path` for each one: + +1. `~/.config/kilo/` +2. `~/.kilo/` +3. `~/.kilocode/` +4. `~/.opencode/` +5. project `.kilo/`, `.kilocode/`, and `.opencode/` directories from the current working directory up to the worktree root + +Use exact patterns first: + +- `**/command/.md` +- `**/commands/.md` + +If found, return the full path. If not found in those roots, explain that the command is not present in the loaded config paths. + ## Agents (`.kilo/agent/*.md`) Also loaded from `.kilocode/` and `.opencode/` directories (legacy), and plural `agents/` variants. diff --git a/packages/opencode/test/tool/skill.test.ts b/packages/opencode/test/tool/skill.test.ts index 70649dd9016..0fa1f13d4be 100644 --- a/packages/opencode/test/tool/skill.test.ts +++ b/packages/opencode/test/tool/skill.test.ts @@ -109,4 +109,36 @@ Use this skill. process.env.KILO_TEST_HOME = home } }) + + test("built-in kilo-config includes named command lookup guidance", async () => { + await using tmp = await tmpdir({ git: true }) + + const home = process.env.KILO_TEST_HOME + process.env.KILO_TEST_HOME = tmp.path + + try { + await Instance.provide({ + directory: tmp.path, + fn: async () => { + const tool = await SkillTool.init() + const ctx: Tool.Context = { + ...baseCtx, + ask: async () => {}, + } + + const result = await tool.execute({ name: "kilo-config" }, ctx) + + expect(tool.description).toContain("where it loads things from") + expect(result.metadata.dir).toBe("builtin") + expect(result.output).toContain("### Finding a named command") + expect(result.output).toContain("`~/.config/kilo/`") + expect(result.output).toContain("`~/.kilocode/`") + expect(result.output).toContain("`**/command/.md`") + expect(result.output).toContain("explicit search `path`") + }, + }) + } finally { + process.env.KILO_TEST_HOME = home + } + }) }) From 6a91d2a6aab351a2ff38e87512ae02181a9bc141 Mon Sep 17 00:00:00 2001 From: Alex Alecu Date: Tue, 7 Apr 2026 14:16:06 +0300 Subject: [PATCH 4/9] docs(cli): add missing opencode.jsonc to global paths --- packages/opencode/src/kilocode/skills/kilo-config.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/packages/opencode/src/kilocode/skills/kilo-config.md b/packages/opencode/src/kilocode/skills/kilo-config.md index e8e763a2e16..972542739a5 100644 --- a/packages/opencode/src/kilocode/skills/kilo-config.md +++ b/packages/opencode/src/kilocode/skills/kilo-config.md @@ -223,11 +223,11 @@ Toggle notifications, Toggle animations, Toggle diff wrapping, Toggle sidebar (` ### Config files (kilo.json) -| Scope | Path | -| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Project | `./kilo.json`, `./kilo.jsonc`, `./opencode.json` (legacy), `./opencode.jsonc` (legacy) | -| Global | `~/.config/kilo/kilo.json`, `~/.config/kilo/kilo.jsonc`, `~/.config/kilo/opencode.json` (legacy), `~/.config/kilo/config.json` (legacy) | -| Managed | Linux: `/etc/kilo/kilo.json`, macOS: `/Library/Application Support/kilo/kilo.json`, Windows: `%ProgramData%\kilo\kilo.json` (enterprise, highest priority) | +| Scope | Path | +| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Project | `./kilo.json`, `./kilo.jsonc`, `./opencode.json` (legacy), `./opencode.jsonc` (legacy) | +| Global | `~/.config/kilo/kilo.json`, `~/.config/kilo/kilo.jsonc`, `~/.config/kilo/opencode.json` (legacy), `~/.config/kilo/opencode.jsonc` (legacy), `~/.config/kilo/config.json` (legacy) | +| Managed | Linux: `/etc/kilo/kilo.json`, macOS: `/Library/Application Support/kilo/kilo.json`, Windows: `%ProgramData%\kilo\kilo.json` (enterprise, highest priority) | Each config directory (`.kilo/`, `.kilocode/`, `.opencode/`) can also contain `kilo.json`, `kilo.jsonc`, `opencode.json`, or `opencode.jsonc`. From 2302f7f67acc46b48207059e76cdf2699a10e2e7 Mon Sep 17 00:00:00 2001 From: Alex Alecu Date: Tue, 7 Apr 2026 14:16:40 +0300 Subject: [PATCH 5/9] docs(cli): fix instructions auto-discovery list --- packages/opencode/src/kilocode/skills/kilo-config.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/opencode/src/kilocode/skills/kilo-config.md b/packages/opencode/src/kilocode/skills/kilo-config.md index 972542739a5..7c2d52b9c0d 100644 --- a/packages/opencode/src/kilocode/skills/kilo-config.md +++ b/packages/opencode/src/kilocode/skills/kilo-config.md @@ -254,10 +254,10 @@ Example: `~/.config/kilo/command/*.md` (modern global), `~/.kilocode/command/*.m ### Skills and instructions -| Scope | Path | -| ------------ | ----------------------------------------------------------------------- | -| Skills | `{skill,skills}//SKILL.md` inside any config directory | -| Instructions | `AGENTS.md`, `.kilo/instructions.md`, glob patterns from `instructions` | +| Scope | Path | +| ------------ | ------------------------------------------------------------------------ | +| Skills | `{skill,skills}//SKILL.md` inside any config directory | +| Instructions | `AGENTS.md`, `CLAUDE.md`, glob patterns from `instructions` config field | ### Environment variable overrides From b86265102389ebe6a704744f535d3a0988cec7a1 Mon Sep 17 00:00:00 2001 From: Alex Alecu Date: Tue, 7 Apr 2026 14:17:15 +0300 Subject: [PATCH 6/9] docs(cli): list all managed config files --- packages/opencode/src/kilocode/skills/kilo-config.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/packages/opencode/src/kilocode/skills/kilo-config.md b/packages/opencode/src/kilocode/skills/kilo-config.md index 7c2d52b9c0d..edb460c2eb5 100644 --- a/packages/opencode/src/kilocode/skills/kilo-config.md +++ b/packages/opencode/src/kilocode/skills/kilo-config.md @@ -223,11 +223,11 @@ Toggle notifications, Toggle animations, Toggle diff wrapping, Toggle sidebar (` ### Config files (kilo.json) -| Scope | Path | -| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Project | `./kilo.json`, `./kilo.jsonc`, `./opencode.json` (legacy), `./opencode.jsonc` (legacy) | -| Global | `~/.config/kilo/kilo.json`, `~/.config/kilo/kilo.jsonc`, `~/.config/kilo/opencode.json` (legacy), `~/.config/kilo/opencode.jsonc` (legacy), `~/.config/kilo/config.json` (legacy) | -| Managed | Linux: `/etc/kilo/kilo.json`, macOS: `/Library/Application Support/kilo/kilo.json`, Windows: `%ProgramData%\kilo\kilo.json` (enterprise, highest priority) | +| Scope | Path | +| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Project | `./kilo.json`, `./kilo.jsonc`, `./opencode.json` (legacy), `./opencode.jsonc` (legacy) | +| Global | `~/.config/kilo/kilo.json`, `~/.config/kilo/kilo.jsonc`, `~/.config/kilo/opencode.json` (legacy), `~/.config/kilo/opencode.jsonc` (legacy), `~/.config/kilo/config.json` (legacy) | +| Managed | Linux: `/etc/kilo/`, macOS: `/Library/Application Support/kilo/`, Windows: `%ProgramData%\kilo\` — loads `kilo.json`, `kilo.jsonc`, `opencode.json`, `opencode.jsonc` (enterprise, highest priority) | Each config directory (`.kilo/`, `.kilocode/`, `.opencode/`) can also contain `kilo.json`, `kilo.jsonc`, `opencode.json`, or `opencode.jsonc`. From eb1494f122c963fb27671d01e75c46bc65604a95 Mon Sep 17 00:00:00 2001 From: Alex Alecu Date: Tue, 7 Apr 2026 14:17:52 +0300 Subject: [PATCH 7/9] docs(cli): widen KILO_DISABLE_PROJECT_CONFIG desc --- packages/opencode/src/kilocode/skills/kilo-config.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/opencode/src/kilocode/skills/kilo-config.md b/packages/opencode/src/kilocode/skills/kilo-config.md index edb460c2eb5..df435e5815c 100644 --- a/packages/opencode/src/kilocode/skills/kilo-config.md +++ b/packages/opencode/src/kilocode/skills/kilo-config.md @@ -266,4 +266,4 @@ Example: `~/.config/kilo/command/*.md` (modern global), `~/.kilocode/command/*.m | `KILO_CONFIG` | Path to an additional config file (loaded after global) | | `KILO_CONFIG_DIR` | Path to an additional config directory (appended to search list) | | `KILO_CONFIG_CONTENT` | Inline JSON config string (high precedence, after project dirs) | -| `KILO_DISABLE_PROJECT_CONFIG` | Skip project-level `.kilo`/`.kilocode`/`.opencode` directories | +| `KILO_DISABLE_PROJECT_CONFIG` | Skip all project-level config (files and directories) | From 5a9520d3f0a0e5e757d54a5d53ba2ea3056b0cea Mon Sep 17 00:00:00 2001 From: Alex Alecu Date: Tue, 7 Apr 2026 14:26:46 +0300 Subject: [PATCH 8/9] docs(cli): add KILO_CONFIG_DIR to command lookup --- packages/opencode/src/kilocode/skills/kilo-config.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/opencode/src/kilocode/skills/kilo-config.md b/packages/opencode/src/kilocode/skills/kilo-config.md index df435e5815c..682e5ba747e 100644 --- a/packages/opencode/src/kilocode/skills/kilo-config.md +++ b/packages/opencode/src/kilocode/skills/kilo-config.md @@ -30,7 +30,8 @@ When asked where `/name` lives, do not search only the repo root. Search these r 2. `~/.kilo/` 3. `~/.kilocode/` 4. `~/.opencode/` -5. project `.kilo/`, `.kilocode/`, and `.opencode/` directories from the current working directory up to the worktree root +5. The `KILO_CONFIG_DIR` directory (if the env var is set) +6. project `.kilo/`, `.kilocode/`, and `.opencode/` directories from the current working directory up to the worktree root Use exact patterns first: From 27057648d326e43972d1e76a58537813d071480b Mon Sep 17 00:00:00 2001 From: Alex Alecu Date: Tue, 7 Apr 2026 14:32:15 +0300 Subject: [PATCH 9/9] docs(cli): add CONTEXT.md to instructions list --- packages/opencode/src/kilocode/skills/kilo-config.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/opencode/src/kilocode/skills/kilo-config.md b/packages/opencode/src/kilocode/skills/kilo-config.md index 682e5ba747e..a7ca25d7b53 100644 --- a/packages/opencode/src/kilocode/skills/kilo-config.md +++ b/packages/opencode/src/kilocode/skills/kilo-config.md @@ -255,10 +255,10 @@ Example: `~/.config/kilo/command/*.md` (modern global), `~/.kilocode/command/*.m ### Skills and instructions -| Scope | Path | -| ------------ | ------------------------------------------------------------------------ | -| Skills | `{skill,skills}//SKILL.md` inside any config directory | -| Instructions | `AGENTS.md`, `CLAUDE.md`, glob patterns from `instructions` config field | +| Scope | Path | +| ------------ | -------------------------------------------------------------------------------------- | +| Skills | `{skill,skills}//SKILL.md` inside any config directory | +| Instructions | `AGENTS.md`, `CLAUDE.md`, `CONTEXT.md`, glob patterns from `instructions` config field | ### Environment variable overrides