## Advanced Features

- **Form filling**: See [FORMS.md](references/FORMS.md)
- **PDF rotation**: Use `scripts/rotate_pdf.py`

2.4 Skill 发现路径

Kimi Code CLI 按优先级从多个位置加载 Skill：

1. 内置 Skills (src/kimi_cli/skills/)
2. 用户级 Skills:
   - ~/.config/agents/skills/    ← 推荐
   - ~/.agents/skills/
   - ~/.kimi/skills/
   - ~/.claude/skills/           ← 兼容
   - ~/.codex/skills/            ← 兼容
3. 项目级 Skills:
   - ./.agents/skills/
   - ./.kimi/skills/

2.5 Skill 类型

Standard Skill（标准型）

最常见的 Skill 类型，提供领域知识和指导：

---
name: python-best-practices
description: Guidelines for writing clean, Pythonic code.
---

# Python Best Practices

## Code Style
- Follow PEP 8
- Use type hints
- Prefer list comprehensions over map/filter
...

使用方式：

/skill:python-best-practices 请检查这段代码

Flow Skill（流程型）

定义可执行的工作流程，支持决策分支：

---
name: release
description: Execute the release workflow.
type: flow
---

使用方式：

/flow:release

2.6 创建 Skill 的步骤

1. 理解需求 —— 明确 Skill 要解决的问题
2. 规划内容 —— 确定需要哪些 scripts/references/assets
3. 初始化目录 —— 创建 SKILL.md 和子目录
4. 编写内容 —— 遵循渐进披露原则
5. 测试验证 —— 实际使用，迭代优化
6. 打包分发 —— 压缩为 .skill 文件

2.7 Skill 打包

# 打包 Skill
cd ~/.config/agents/skills/
zip -r my-skill.skill my-skill

# 安装 Skill（解压到 skill 目录）
unzip my-skill.skill -d ~/.config/agents/skills/

三、Tool 系统 —— 代码级功能扩展

3.1 什么是 Tool？

Tool 是 Kimi Code CLI 的功能型插件，通过编写 Python 代码实现自定义功能。

适用场景：

• 需要自定义逻辑的功能
• 与外部系统深度集成
• 性能敏感的计算任务

3.2 Tool 基类

Kimi Code CLI 使用 kosong 框架的 Tool 系统：

from pydantic import BaseModel, Field
from kosong.tooling import CallableTool2, ToolOk, ToolError, ToolReturnValue

class Params(BaseModel):
    """Tool 参数定义"""
    arg1: str = Field(description="参数说明")
    arg2: int = Field(default=10, ge=1, description="带约束的参数")

class MyTool(CallableTool2[Params]):
    """Tool 实现"""
    name: str = "MyTool"           # Tool 名称
    params: type[Params] = Params  # 参数模型
    
    def __init__(self, runtime: Runtime):
        """构造函数，支持依赖注入"""
        super().__init__(description="Tool 描述")
        self._runtime = runtime
    
    async def __call__(self, params: Params) -> ToolReturnValue:
        """Tool 逻辑"""
        try:
            result = await self.do_something(params)
            return ToolOk(output=result, message="成功消息")
        except Exception as e:
            return ToolError(message=f"错误: {e}", brief="简短错误")

3.3 Tool 加载机制

在 agent.yaml 中注册 Tool：

agent:
  tools:
    # 内置 Tools
    - "kimi_cli.tools.shell:Shell"
    - "kimi_cli.tools.file:ReadFile"
    - "kimi_cli.tools.web:SearchWeb"
    # 自定义 Tools
    - "my_package.tools:MyTool"

加载过程：

# 1. 解析路径 "module.path:ClassName"
module_name, class_name = tool_path.rsplit(":", 1)

# 2. 动态导入模块
module = importlib.import_module(module_name)
tool_cls = getattr(module, class_name)

# 3. 依赖注入
# 根据 __init__ 参数类型自动注入依赖
for param in inspect.signature(tool_cls).parameters.values():
    if param.annotation in dependencies:
        args.append(dependencies[param.annotation])

# 4. 实例化
tool = tool_cls(*args)

3.4 依赖注入

Tool 可以通过构造函数声明依赖：

class AdvancedTool(CallableTool2[Params]):
    def __init__(
        self,
        runtime: Runtime,           # 运行时环境
        approval: Approval,          # 审批系统
        environment: Environment,    # 环境信息
    ):
        super().__init__()
        self._runtime = runtime
        self._approval = approval

3.5 完整的自定义 Tool 示例

# my_tools/database.py
from pathlib import Path
from typing import override
from pydantic import BaseModel, Field
from kosong.tooling import CallableTool2, ToolOk, ToolError, ToolReturnValue
from kimi_cli.soul.agent import Runtime

class QueryParams(BaseModel):
    sql: str = Field(description="SQL query to execute")
    db_path: str = Field(description="Path to SQLite database file")

class DatabaseQuery(CallableTool2[QueryParams]):
    """Execute SQL queries on a SQLite database."""
    
    name: str = "DatabaseQuery"
    params: type[QueryParams] = QueryParams
    
    def __init__(self, runtime: Runtime) -> None:
        super().__init__(
            description="Execute SQL queries on SQLite databases."
        )
        self._runtime = runtime
        self._work_dir = runtime.builtin_args.KIMI_WORK_DIR
    
    @override
    async def __call__(self, params: QueryParams) -> ToolReturnValue:
        import sqlite3
        import json
        
        try:
            # 验证路径安全
            db_path = Path(params.db_path)
            if not db_path.is_absolute():
                db_path = self._work_dir / db_path
            
            # 执行查询
            conn = sqlite3.connect(str(db_path))
            conn.row_factory = sqlite3.Row
            cursor = conn.cursor()
            cursor.execute(params.sql)
            
            # 获取结果
            if params.sql.strip().upper().startswith("SELECT"):
                rows = cursor.fetchall()
                result = [dict(row) for row in rows]
                return ToolOk(
                    output=json.dumps(result, indent=2, ensure_ascii=False),
                    message=f"Query returned {len(rows)} rows."
                )
            else:
                conn.commit()
                return ToolOk(
                    output="",
                    message=f"Query executed successfully. Rows affected: {cursor.rowcount}"
                )
                
        except sqlite3.Error as e:
            return ToolError(
                message=f"Database error: {e}",
                brief="Query failed"
            )
        finally:
            if 'conn' in locals():
                conn.close()

注册使用：

# agent.yaml
agent:
  tools:
    - "my_tools.database:DatabaseQuery"

四、Agent Spec —— 角色与行为配置

4.1 什么是 Agent Spec？

Agent Spec 是 YAML 格式的配置文件，定义 Agent 的身份、行为和能力。

核心价值：

• 🎭 角色定义 —— 创建专门的 Agent（如安全审计员、数据分析师）
• ⚙️ 行为定制 —— 调整系统提示词、工具集合
• 🔄 配置继承 —— 基于现有配置扩展

4.2 配置结构

version: 1
agent:
  name: "DataAnalyst"                    # Agent 名称
  extend: default                        # 继承基础配置
  system_prompt_path: ./system.md        # 系统提示词文件
  system_prompt_args:                    # 提示词变量
    EXPERTISE: "pandas, numpy, matplotlib"
    ROLE_ADDITIONAL: |
      You are a data analysis expert.
      Always provide data-backed insights.
  tools:                                 # 工具列表
    - "kimi_cli.tools.shell:Shell"
    - "kimi_cli.tools.file:ReadFile"
  exclude_tools:                         # 排除的工具
    - "kimi_cli.tools.file:WriteFile"
  subagents:                             # 子 Agent 定义
    data-cleaner:
      path: ./sub.yaml
      description: "Specializes in data cleaning tasks."

4.3 继承机制

# data-analyst.yaml - 继承 default
agent:
  extend: default
  name: "DataAnalyst"
  system_prompt_args:
    ROLE_ADDITIONAL: "专注于数据分析"
  # tools 和 exclude_tools 继承自 default

继承规则：

• 子配置覆盖父配置
• system_prompt_args 合并（而非覆盖）
• inherit 标记表示继承父值

4.4 系统提示词模板

## Working Environment

当前工作目录是 `${KIMI_WORK_DIR}`

目录列表：