feat(skills): unify skills discovery

.agents/skills/gen-changelog/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: gen-changelog
+description: Generate changelog entries for code changes. Use when user wants to add changelog entries, update CHANGELOG.md, or document changes made in the current branch compared to main.
+---
+
+# Generate Changelog
+
+根据当前分支相对于 main 分支的修改，在根目录 CHANGELOG.md 或相应 package/sdk 等目录的 CHANGELOG.md 文件中添加更新日志条目，遵循现有的格式和风格。

.agents/skills/gen-docs/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: gen-docs
+description: Update Kimi CLI user documentation. Use when user wants to update docs, sync documentation with code changes, or ensure docs reflect recent commits and changelog updates.
+---
+
+# Generate/Update Documentation
+
+现在我们正在为当前项目 Kimi CLI 编写和维护用户文档，文档内容在 docs 目录下，docs/AGENTS.md 中有对文档的说明。
+
+我们现在对代码库有了一些修改，请你参考最近的 git commit、staged changes、changelog.md 等的内容，根据 AGENTS.md 中的信息，必要时找到实际的代码全文，确保理解了所有变更对产品用户体验的真实改变，然后逐页、逐段地检查和更新文档内容。
+
+你应该首先确保英文 changelog 使用 `node docs/scripts/sync-changelog.mjs` 进行了同步，然后确保中文文档符合最新代码的行为，最后，使用 translate-docs skill 进行双语同步。

.agents/skills/pr/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: pr
+description: Create and submit a Pull Request. Use when user wants to submit a PR, push changes and open a pull request, or create a PR from the current branch to main.
+---
+
+# Submit Pull Request
+
+1. 如果当前分支有 dirty change，什么都不要做，直接停止。
+2. 如果是干净的，确保当前分支是一个不同于 main 的独立分支。
+3. 根据当前分支相对于 main 分支的修改，push 并提交一个 PR（利用 gh 命令），用英文编写 PR 标题和 description，描述所做的更改。
+4. PR title 要符合先前的 commit message 规范（PR title 就是 squash merge 之后的 commit message）。

.agents/skills/release/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: release
+description: Execute the release workflow for Kimi CLI packages. Use when user wants to release a new version, bump version numbers, create release PRs, or prepare packages for publishing.
+---
+
+# Release Workflow
+
+1. 首先从 AGENTS.md 和 .github/workflows/release*.yml 中理解本项目的发版自动化流程。
+2. 检查每个 packages、sdks 和根目录的包是否在上次发版（根据 tag 确认）后有变更。
+3. 如果有变更，对于每个变更的包，跟我确认新的版本号（遵循语义化版本规范），并更新相应的：
+   - pyproject.toml
+   - CHANGELOG.md（要保留 Unreleased 标题）
+   - 中英文档的 breaking-changes.md 文件中的版本号
+4. 运行 `uv sync`。
+5. 运行 gen-docs skill 中的指示以确保文档是最新的。
+6. 开一个新的分支叫 `bump-<package>-<new-version>`，提交所有更改并推送到远程仓库。
+   - 如果一次有多个包需要发版，可以合并在一个分支升级版本号，分支名适当编写即可。
+7. 用 gh 命令开一个 Pull Request，描述所做的更改。
+8. 持续检查这个 PR 的状态，直到被合并。
+9. 合并后，切到 main 分支，拉取最新的更改。
+10. 提示我最终发布 tag 所需的 git tag 命令，我会自行 tag + push tags。

.agents/skills/translate-docs/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: translate-docs
+description: Translate and sync bilingual documentation. Use when user wants to translate docs between Chinese and English, sync translations, or ensure bilingual documentation consistency.
+---
+
+# Translate Documentation
+
+现在我们正在为当前项目 Kimi CLI 编写和维护用户文档，文档内容在 docs 目录下，docs/AGENTS.md 中有对文档的说明。
+
+中文文档和英文 changelog 已经确保是正确符合预期的，现在请你逐页、逐段地翻译文档内容，确保中英双语保持同步。
+
+## 翻译方向
+
+- **Changelog**: 以英文为准，翻译到中文
+- **其他所有页面**: 以中文为准，翻译到英文
+
+## 注意事项
+
+- 必要时可以参考代码文件以确保翻译的准确性
+- 要保证不同语言的表达风格、结构标记等保持一致
+- 但需要遵守两者可能不同的用词和排版偏好（主要是 sentence case、翻译对照之类的）

CHANGELOG.md

@@ -11,6 +11,9 @@ Only write entries that are worth mentioning to users.
 
 ## Unreleased
 
+- Skills: Add project-level skills support, discovered from `.agents/skills/` (or `.kimi/skills/`, `.claude/skills/`)
+- Skills: Unified skills discovery with layered loading (builtin → user → project); user-level skills now prefer `~/.config/agents/skills/`
+- Shell: Support fuzzy matching for slash command autocomplete
 - Shell: Enhanced approval request preview with shell command and diff content display, use `Ctrl-E` to expand full content
 - Wire: Add `ShellDisplayBlock` type for shell command display in approval requests
 - Shell: Reorder `/help` to show keyboard shortcuts before slash commands

Makefile

@@ -110,9 +110,9 @@ ai-test: ## Run the test suite with Kimi CLI.
 .PHONY: gen-changelog gen-docs
 gen-changelog: ## Generate changelog with Kimi CLI.
 	@echo "==> Generating changelog"
-	@uv run kimi -c "$$(cat .kimi/prompts/gen-changelog.md)" --yolo
+	@uv run kimi --yolo --prompt /skill:gen-changelog
 gen-docs: ## Generate user docs with Kimi CLI.
 	@echo "==> Generating user docs"
-	@uv run kimi -c "$$(cat .kimi/prompts/gen-docs.md)" --yolo
+	@uv run kimi --yolo --prompt /skill:gen-docs
 
 include src/kimi_cli/deps/Makefile

docs/en/customization/skills.md

@@ -10,13 +10,29 @@ For example, you can create a "code style" skill to tell the AI your project's n
 
 ## Skill discovery
 
-Kimi CLI discovers skills from the following directories:
+Kimi CLI uses a layered loading mechanism to discover skills, loading in the following priority order (later ones override skills with the same name):
 
-1. Built-in skills (shipped with the package)
-2. `~/.kimi/skills` (user directory)
-3. `~/.claude/skills` (compatible with Claude's skills)
+**Built-in skills**
 
-If a skill with the same name exists in multiple directories, later ones override earlier ones. You can also specify other directories with the `--skills-dir` flag:
+Skills shipped with the package, providing basic capabilities.
+
+**User-level skills**
+
+Stored in the user's home directory, effective across all projects. Kimi CLI checks the following directories in priority order and uses the first one that exists:
+
+1. `~/.config/agents/skills/` (recommended)
+2. `~/.kimi/skills/` (legacy compatibility)
+3. `~/.claude/skills/` (Claude compatibility)
+
+**Project-level skills**
+
+Stored in the project directory, only effective within that project's working directory. Kimi CLI checks the following directories in priority order and uses the first one that exists:
+
+1. `.agents/skills/` (recommended)
+2. `.kimi/skills/` (legacy compatibility)
+3. `.claude/skills/` (Claude compatibility)
+
+You can also specify other directories with the `--skills-dir` flag, which skips user-level and project-level skill discovery:
 
 ```sh
 kimi --skills-dir /path/to/my-skills
@@ -41,7 +57,7 @@ Creating a skill only requires two steps:
 A skill directory needs at least a `SKILL.md` file, and can also include auxiliary directories to organize more complex content:
 
 ```
-~/.kimi/skills/
+~/.config/agents/skills/
 └── my-skill/
     ├── SKILL.md          # Required: main file
     ├── scripts/          # Optional: script files

docs/en/reference/slash-commands.md

@@ -142,6 +142,6 @@ This command is only available when a flowchart has been loaded via `--prompt-fl
 
 ## Command completion
 
-After typing `/` in the input box, a list of available commands is automatically displayed. Continue typing to filter commands, press Enter to select.
+After typing `/` in the input box, a list of available commands is automatically displayed. Continue typing to filter commands with fuzzy matching support, press Enter to select.
 
-Commands support alias matching, for example typing `/h` will match `/help`.
+For example, typing `/ses` will match `/sessions`, and `/clog` will match `/changelog`. Command aliases are also supported, such as typing `/h` to match `/help`.

docs/en/release-notes/changelog.md

@@ -4,6 +4,9 @@ This page documents the changes in each Kimi CLI release.
 
 ## Unreleased
 
+- Skills: Add project-level skills support, discovered from `.agents/skills/` (or `.kimi/skills/`, `.claude/skills/`)
+- Skills: Unified skills discovery with layered loading (builtin → user → project); user-level skills now prefer `~/.config/agents/skills/`
+- Shell: Support fuzzy matching for slash command autocomplete
 - Shell: Enhanced approval request preview with shell command and diff content display, use `Ctrl-E` to expand full content
 - Wire: Add `ShellDisplayBlock` type for shell command display in approval requests
 - Shell: Reorder `/help` to show keyboard shortcuts before slash commands

docs/zh/customization/skills.md

@@ -10,13 +10,29 @@
 
 ## Skill 发现
 
-Kimi CLI 会从以下目录发现 Skills：
+Kimi CLI 采用分层加载机制发现 Skills，按以下优先级加载（后加载的会覆盖同名 Skill）：
 
-1. 内置 Skills（随软件包安装）
-2. `~/.kimi/skills`（用户目录）
-3. `~/.claude/skills`（兼容 Claude 的 Skills）
+**内置 Skills**
 
-如果同名 Skill 存在于多个目录中，后发现的会覆盖先前的。你也可以通过 `--skills-dir` 参数指定其他目录：
+随软件包安装的 Skills，提供基础能力。
+
+**用户级 Skills**
+
+存放在用户主目录中，在所有项目中生效。Kimi CLI 会按优先级检查以下目录，使用第一个存在的目录：
+
+1. `~/.config/agents/skills/`（推荐）
+2. `~/.kimi/skills/`（兼容旧版）
+3. `~/.claude/skills/`（兼容 Claude）
+
+**项目级 Skills**
+
+存放在项目目录中，仅在该项目工作目录下生效。Kimi CLI 会按优先级检查以下目录，使用第一个存在的目录：
+
+1. `.agents/skills/`（推荐）
+2. `.kimi/skills/`（兼容旧版）
+3. `.claude/skills/`（兼容 Claude）
+
+你也可以通过 `--skills-dir` 参数指定其他目录，此时会跳过用户级和项目级 Skills 的发现：
 
 ```sh
 kimi --skills-dir /path/to/my-skills
@@ -41,7 +57,7 @@ Kimi CLI 内置了以下 Skills：
 一个 Skill 目录至少需要包含 `SKILL.md` 文件，也可以包含辅助目录来组织更复杂的内容：
 
 ```
-~/.kimi/skills/
+~/.config/agents/skills/
 └── my-skill/
     ├── SKILL.md          # 必需：主文件
     ├── scripts/          # 可选：脚本文件

docs/zh/reference/slash-commands.md

@@ -142,6 +142,6 @@ YOLO 模式会跳过所有确认，请确保你了解可能的风险。
 
 ## 命令补全
 
-在输入框中输入 `/` 后，会自动显示可用命令列表。继续输入可过滤命令，按 Enter 选择。
+在输入框中输入 `/` 后，会自动显示可用命令列表。继续输入可过滤命令，支持模糊匹配，按 Enter 选择。
 
-命令支持别名匹配，例如输入 `/h` 会匹配到 `/help`。
+例如，输入 `/ses` 会匹配到 `/sessions`，输入 `/clog` 会匹配到 `/changelog`。命令的别名也支持匹配，例如输入 `/h` 会匹配到 `/help`。

docs/zh/release-notes/changelog.md

@@ -4,6 +4,9 @@
 
 ## 未发布
 
+- Skills：添加项目级 Skills 支持，从 `.agents/skills/`（或 `.kimi/skills/`、`.claude/skills/`）发现
+- Skills：统一 Skills 发现机制，采用分层加载（内置 → 用户 → 项目）；用户级 Skills 现在优先使用 `~/.config/agents/skills/`
+- Shell：斜杠命令自动补全支持模糊匹配
 - Shell：增强审批请求预览，显示 Shell 命令和 Diff 内容，使用 `Ctrl-E` 展开完整内容
 - Wire：添加 `ShellDisplayBlock` 类型，用于在审批请求中显示 Shell 命令
 - Shell：调整 `/help` 显示顺序，将键盘快捷键移至斜杠命令之前

klips/klip-8-config-and-skills-layout.md

@@ -0,0 +1,49 @@
+---
+Author: "@xxchan"
+Updated: 2026-01-14
+Status: Implemented
+---
+
+# KLIP-8: Unified Skills Discovery
+
+## Motivation
+
+> "Skills should not need vendor-specific directory layouts, duplicate copies, or symlink hacks to be usable across clients."
+
+Coding agent ecosystems are fragmented with vendor-specific layouts. Users must duplicate skills or maintain symlinks.
+
+This proposal unifies skill discovery to be compatible with existing tools.
+
+## Scope
+
+- Skills discovery
+- Future: `mcp.json` (not this KLIP)
+
+## Non-goals
+
+- `~/.kimi/config.toml` and other Kimi-specific config
+- `~/.local/share/kimi/` data directories
+
+## Skills Discovery
+
+Two-level logic:
+
+1. **Layered merge**: builtin → user → project all loaded; same-name skills overridden by later layers
+2. **Directory lookup**: within each layer, check candidates by priority; stop at first existing directory
+
+**User level** (by priority):
+- `~/.config/agents/skills/` — canonical, recommended
+- `~/.kimi/skills/` — legacy fallback
+- `~/.claude/skills/` — legacy fallback
+
+**Project level**:
+- `.agents/skills/`
+
+Built-in skills load only when the KAOS backend is `LocalKaos` or `ACPKaos`.
+
+`--skills-dir` overrides user/project discovery; only specified directory is used (built-ins still load when supported).
+
+## References
+
+- [agentskills#15](https://github.com/agentskills/agentskills/issues/15): proposal to standardize `.agents/skills/`
+- [Amp](https://ampcode.com/manual#agent-skills): `~/.config/agents/`, `.agents/skills/`

src/kimi_cli/app.py

@@ -60,7 +60,7 @@ async def create(
         # Extensions
         agent_file: Path | None = None,
         mcp_configs: list[MCPConfig] | list[dict[str, Any]] | None = None,
-        skills_dir: Path | None = None,
+        skills_dir: KaosPath | None = None,
         # Loop control
         max_steps_per_turn: int | None = None,
         max_retries_per_step: int | None = None,
@@ -80,7 +80,8 @@ async def create(
             agent_file (Path | None, optional): Path to the agent file. Defaults to None.
             mcp_configs (list[MCPConfig | dict[str, Any]] | None, optional): MCP configs to load
                 MCP tools from. Defaults to None.
-            skills_dir (Path | None, optional): Path to the skills directory. Defaults to None.
+            skills_dir (KaosPath | None, optional): Override skills directory discovery. Defaults
+                to None.
             max_steps_per_turn (int | None, optional): Maximum number of steps in one turn.
                 Defaults to None.
             max_retries_per_step (int | None, optional): Maximum number of retries in one step.

src/kimi_cli/cli/__init__.py

@@ -260,15 +260,15 @@ def kimi(
             ),
         ),
     ] = None,
-    skills_dir: Annotated[
+    local_skills_dir: Annotated[
         Path | None,
         typer.Option(
             "--skills-dir",
             exists=True,
             file_okay=False,
             dir_okay=True,
             readable=True,
-            help="Path to the skills directory. Default: ~/.kimi/skills",
+            help="Path to the skills directory. Overrides discovery.",
         ),
     ] = None,
     # Loop control
@@ -466,6 +466,10 @@ def kimi(
     except json.JSONDecodeError as e:
         raise typer.BadParameter(f"Invalid JSON: {e}", param_hint="--mcp-config") from e
 
+    skills_dir: KaosPath | None = None
+    if local_skills_dir is not None:
+        skills_dir = KaosPath.unsafe_from_local_path(local_skills_dir)
+
     work_dir = KaosPath.unsafe_from_local_path(local_work_dir) if local_work_dir else KaosPath.cwd()
 
     async def _run(session_id: str | None) -> bool: