2026年移植别人的skills，到自己的Kimi Code CLI Skill 如何保持兼容性？依赖兼容，系统，终端版本..需要重写部分代码以兼容自己的cli终端

大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。

 
  
    
     下面给你一版重写后的“指导性推荐手册”。

它的目标只有一个：让你按步骤把 Kimi Code CLI skill 做出来，并尽量一次做对。

先做最小可用版，再做增强版。

不要一开始就同时处理：

多目录发现
复杂脚本
Windows 兼容
外部 skill 迁移
Flow Skill

正确顺序是：

先做一个最小 skill
确认 Kimi 能发现它
确认它会被触发
再加脚本和资源
最后做跨平台兼容

原因很直接：Kimi Code CLI 启动时会发现 skills，并把 skill 的名称、路径、描述注入系统提示；模型再按需读取具体 SKILL.md。所以最先决定 skill 是否“能工作”的，不是脚本，而是目录结构和描述写法。

目录名一律用：

小写
连字符
语义明确

例如：

my-code-review/ └── SKILL.md

推荐你把目录名和 name 字段写成完全一致。
Agent Skills 规范要求 name 合法，并与父目录名匹配。

直接用这个：

--- name: my-code-review description: Reviews code for correctness, maintainability, and common risks. Use this when the user asks for code review, bug finding, refactoring advice, quality checks, 代码审查, 查 bug, 重构建议, 质量检查. compatibility: Cross-platform. Prefer Python scripts. On Windows, avoid bash-specific shell chains. --- # My Code Review Skill Purpose Review code and identify: - correctness issues - maintainability problems - risky assumptions - refactoring opportunities When to use Use this skill when the user asks to: - review code - find bugs - improve code quality - suggest refactoring - assess implementation risks Workflow 1. Read the relevant files. 2. Identify correctness issues first. 3. Then check readability and maintainability. 4. Flag risky logic, missing validation, and fragile assumptions. 5. Summarize findings by severity.

这套写法符合两件事：

Kimi 的 skill 机制依赖 name、description 等元数据做发现和注入。
Agent Skills 规范强调 description 要写清“做什么”和“什么时候用”。

这是最重要的一步。

不推荐

description: Code review helper.

太短，几乎没有触发线索。

为什么优先它

因为它：

不污染你现有环境
方便 A/B 测试
方便迁移外部 skill
出问题时最好排查

适用场景：

团队统一规范
跟仓库一起版本管理
某个项目专属 skill

适合：

个人长期复用
多项目通用 skill
稳定成熟后再全局安装

答案：等最小 skill 已经被发现、被触发以后。

推荐目录：

my-code-review/ ├── SKILL.md ├── scripts/ │ └── analyze.py ├── references/ │ └── review-checklist.md └── assets/ └── output-template.md

Kimi 官方文档已经给出这类目录结构示例。

用法建议

scripts/
放可执行逻辑，比如：

Python 脚本
PowerShell 脚本
shell 包装脚本

references/
放长说明，比如：

检查清单
审查规则
领域规范

assets/
放模板，比如：

输出模板
提示模板
样板配置

明确建议：

核心逻辑优先 Python

只要能用 Python 写，就先用 Python。

原因：

Kimi Code CLI 官方安装本身就围绕 Python 环境展开。
Python 跨平台更稳
Windows 下 shell 差异大，Python 更少踩坑

shell 只做薄包装

例如：

Linux/macOS 调 run.sh
Windows 调 run.ps1
真正业务逻辑在 run.py

这比把逻辑全部写死在 bash 里稳定得多。

这是实操里最容易出问题的地方。

Kimi Code CLI 在 Windows 上当前默认 shell 是 Windows PowerShell。这件事可以从官方仓库源码和相关 issue 看出来。

所以你不能假设：

默认就是 bash
&&、|| 一定可用
Linux 命令能原样跑
GNU 工具一定存在

不推荐：

Run: `grep -R "TODO" . && echo done || echo fail`

推荐写法：

 Platform notes - Linux/macOS: run `scripts/check.sh` - Windows: run `scripts/check.ps1` - Cross-platform fallback: run `python scripts/check.py`

Kimi 仓库中的 PowerShell 指南已经明确提示，应采用 PowerShell 风格命令组织，而不是直接照搬 bash 风格链式写法。

最推荐

核心能力写成 Python。

次推荐

同时提供：

scripts/run.sh
scripts/run.ps1

不推荐

只提供 .sh，然后指望 Windows 自动兼容。

检查：

是否有 SKILL.md
name 是否合法
name 是否和目录名一致
description 是否清楚

如果这四项都不对，不要继续。

很多外部 skill 不是“不能用”，而是“不会被触发”。

把这种：

description: SQL helper

改成这种：

description: Helps analyze SQL queries, explain execution logic, identify performance issues, and suggest safer rewrites. Use this when the user asks about SQL optimization, query debugging, execution plans, or database troubleshooting, SQL 优化, 查询调试, 执行计划分析.

这是迁移成功率最高的改动之一。

重点检查：

是否依赖 bash 特有语法
是否依赖 /tmp、~/ 等 Unix 路径习惯
是否依赖 GNU 工具链
是否默认 shell 一定是 bash
是否只写了 .sh

如果是，就做平台改造，不要直接投入使用。

用独立目录 + --skills-dir 启动。

你要确认：

skill 能被发现
frontmatter 没报错
name 合法
目录名匹配

至少测 5 组问题：

强命中
“帮我做代码审查”
弱命中
“这段实现有没有风险”
同义表达
“帮我看看代码质量”
中文表达
“帮我查 bug”
英文表达
“Please review this code for bugs and maintainability.”

如果 skill 只在一种问法下被触发，就继续改 description。

至少测：

Linux 或 macOS
Windows PowerShell
Python fallback

如果 Windows 不稳定，优先让 skill 走 Python 路径，不要继续强化 bash。

一个 skill 到了什么程度，可以认为“够成熟”？

有合法 SKILL.md
name 和目录名一致
description 清楚
至少有一个真实触发场景
能被发现
没有明显平台误导

有 compatibility
有 Python fallback
有 references/
有测试样例
有 Windows 说明

— name: my-skill description: Helps with [task]. Use this when the user asks for [scenarios], including [keywords in English], [中文关键词].

compatibility: Cross-platform. Prefer Python scripts. On Windows, avoid bash-specific shell chains.

My Skill

Purpose

This skill helps with:

When to use

Use this skill when the user asks to:

Workflow

Understand the task.
Read the necessary context or files.
Apply the relevant checks or transformations.
Summarize clearly.

Platform notes

Linux/macOS: use `scripts/run.sh` if needed.
Windows: use `scripts/run.ps1` or `python scripts/run.py`.
If shell compatibility is uncertain, prefer Python.

References

See files in `references/` for detailed rules or checklists.

如果你现在只打算做一件最正确的事，那就是：

先做一个只有 SKILL.md 的最小 skill，用 –skills-dir 测试；把 description 写成“做什么 + 什么时候用 + 中英文关键词”；需要执行逻辑时优先 Python；Windows 不要把能力绑定在 bash 命令链上。

这是目前最稳、最容易成功、也最符合 Kimi 当前 skill 机制的做法。下面是检查清单。验证skill的规范性和可移植性。

# Skill 规范与兼容性检查清单

一、基本信息

Skill 名称：
目录名：
检查日期：
检查人：
版本：
来源：
- [ ] 新建
- [ ] 外部迁移
- [ ] 旧版修订

二、目录与文件结构

2.1 基本结构

[ ] Skill 为独立目录
[ ] 目录内包含 `SKILL.md`
[ ] 文件命名清晰规范
[ ] 无无关临时文件
[ ] 无明显冲突文件

2.2 命名规范

[ ] 目录名使用小写 kebab-case
[ ] 目录名语义明确
[ ] `name` 字段与目录名一致
[ ] 未使用含糊或过短命名

2.3 可选目录

[ ] 如需脚本，使用 `scripts/`
[ ] 如需长文档，使用 `references/`
[ ] 如需模板或静态资源，使用 `assets/`
[ ] 可选目录内容用途清晰

结论：

[ ] 通过
[ ] 不通过
备注：

三、`SKILL.md` 规范性

3.1 frontmatter

[ ] 存在 YAML frontmatter
[ ] frontmatter 格式合法
[ ] `name` 已填写
[ ] `description` 已填写
[ ] 如有兼容性差异，已填写 `compatibility`
[ ] 未出现明显语法错误
[ ] 未出现乱码或异常缩进

3.2 name 检查

[ ] `name` 为小写
[ ] `name` 使用 kebab-case
[ ] `name` 与目录名一致
[ ] `name` 不含空格
[ ] `name` 不含无意义缩写

3.3 description 检查

[ ] 明确描述 skill 做什么
[ ] 明确描述什么时候使用
[ ] 包含任务触发关键词
[ ] 不只是空泛一句话
[ ] 不写成作者介绍或营销文案
[ ] 能帮助模型判断是否调用此 skill

结论：

[ ] 通过
[ ] 不通过
备注：

四、内容质量检查

4.1 任务边界

[ ] skill 的职责清晰
[ ] 没有把多个不相关任务混在一起
[ ] 输入场景明确
[ ] 输出目标明确
[ ] 有已知边界说明

4.2 指令质量

[ ] 步骤清晰
[ ] 顺序合理
[ ] 不依赖隐含上下文
[ ] 不需要作者额外口头解释
[ ] 使用者可以直接照做

4.3 结果定义

[ ] skill 说明了预期产物
[ ] skill 说明了完成标准
[ ] skill 说明了失败或不适用条件

结论：

[ ] 通过
[ ] 不通过
备注：

五、触发性检查

5.1 强触发测试

[ ] 用直接任务描述可触发
[ ] 用典型问题表述可触发

示例测试：

[ ] “帮我做代码审查”
[ ] “帮我找 bug”
[ ] “帮我检查实现风险”

5.2 弱触发测试

[ ] 用较弱表述也能命中
[ ] 用同义表达能命中
[ ] 用自然语言描述问题能命中

5.3 多语言测试

[ ] 中文表述能命中
[ ] 英文表述能命中
[ ] 混合关键词场景可接受

5.4 description 触发能力

[ ] 含足够具体关键词
[ ] 无明显歧义
[ ] 不会与其他 skill 大面积重叠

结论：

[ ] 通过
[ ] 不通过
备注：

六、兼容性检查

6.1 平台兼容性

[ ] 已说明支持平台
[ ] Linux/macOS 行为明确
[ ] Windows 行为明确
[ ] 不同平台差异已注明
[ ] 不支持的平台已注明

6.2 脚本兼容性

[ ] 核心逻辑优先使用跨平台方案
[ ] 若使用 shell，未默认假设一定是 bash
[ ] 若存在 Windows 场景，已提供 PowerShell 或 Python 替代
[ ] 未使用未说明的系统级依赖
[ ] 路径写法未明显绑定 Unix 环境
[ ] 路径写法未明显绑定单一 Windows 环境

6.3 命令兼容性

[ ] 未把核心流程写死在 `&&` / `||` 链式命令
[ ] 未假设 GNU 工具链一定存在
[ ] 未假设 PATH 中一定有某工具
[ ] 外部依赖已列明
[ ] 无法跨平台时已给出 fallback

6.4 fallback 策略

[ ] 有跨平台 fallback
[ ] 首选 Python 或其他稳定方案
[ ] shell 仅做薄包装
[ ] 不兼容时有清晰替代路径

结论：

[ ] 通过
[ ] 不通过
备注：

七、资源与依赖检查

7.1 资源组织

[ ] `references/` 内容清楚
[ ] `assets/` 内容清楚
[ ] 模板与说明一致
[ ] 无失效资源引用

7.2 依赖透明度

[ ] 已说明运行依赖
[ ] 已说明外部工具依赖
[ ] 已说明版本要求
[ ] 已说明安装前提

结论：

[ ] 通过
[ ] 不通过
备注：

八、测试与验收

8.1 发现测试

[ ] 已在隔离目录测试
[ ] 已验证 skill 可被发现
[ ] 已验证 frontmatter 可解析

8.2 功能测试

[ ] 已完成最小功能测试
[ ] 已完成典型场景测试
[ ] 已完成异常场景测试
[ ] 已完成边界场景测试

8.3 平台测试

[ ] 已测试 Linux/macOS
[ ] 已测试 Windows
[ ] 已测试 fallback 路径

8.4 发布判定

[ ] 可投入使用
[ ] 可小范围试用
[ ] 需修复后再测
[ ] 不建议发布

结论：

[ ] 通过
[ ] 不通过
备注：

九、已知问题与限制

已知问题：
不支持场景：
风险提示：
后续改进建议：

十、最终结论

[ ] 规范性合格
[ ] 兼容性合格
[ ] 建议发布
[ ] 建议整改后发布

签字：日期：