企业官网建设流程全解析

最近有同事把我拽到工位前，指着终端问：为什么同样的 Kimi Code CLI，别人敲一句“帮我把这个仓库的提交记录整理成更新日志”就能拿到一份像模像样的结果，他敲完却只得到一句“我暂时做不到”？问题多半不在模型，而在**技能（Skill）**有没有装对。这篇就把Kimi Code CLI 安装 AI 助手技能的全过程讲清楚，核心动作就一条命令：npx skills。它解决的是“CLI 助手能力边界太窄”的问题——把常用工作流、领域知识、脚本工具打包成技能，按需装进终端环境，让助手在本地就能调用。适合三类人看：刚接触 CLI 编码助手的新手、想把团队规范固化下来的开发者、以及想自己写技能包的中高级用户。下面从概念、环境、命令、目录结构到排错，一层层拆开。

1. 先搞清楚：CLI 助手和“技能”到底是什么关系

1.1 为什么要在终端里装 AI 助手，而不是再开一个网页

很多人第一反应是：我浏览器里开个对话窗口不也一样？差别在于上下文。终端里的 CLI 助手天生就站在项目目录里，它能看到你的package.json、你的src目录树、你的 git 提交记录，甚至能直接执行命令并把结果读回来。网页对话你得手动复制粘贴文件内容，几轮下来上下文就散了。

但“能看到文件”只是第一步。CLI 助手默认的能力是通用的：会读代码、会写代码、会解释报错。可一旦遇到你团队特有的东西——比如内部的提交信息规范、某个业务模块的特殊目录约定、一份必须按固定模板生成的周报——通用能力就不够用了。这正是“技能”要补的口子：它不是重新训练模型，而是把领域知识和操作流程以文件形式喂给助手，让它在需要的时候自己加载。

我自己的感受是，没有技能的 CLI 助手像一个刚入职的聪明新人，什么都懂一点，但什么都要问你；装好技能之后，它更像一个待了半年的老员工，知道这个仓库的规矩在哪、文档在哪、该跑哪条命令。这个差别在重复性任务上尤其明显。

1.2 技能的本质：一段被结构化包装的提示词加工具说明

剥开外壳看，一个技能通常就是一个目录 + 一个入口文件。入口文件（常见命名是SKILL.md）里包含两部分：头部是元信息，比如技能叫什么、什么时候该被触发、需要哪些工具权限；正文是给人（也给模型）看的操作说明，可以写流程、写约束、写示例。

有些技能还会带脚本。比如一个“生成变更日志”的技能，正文里写着“先执行git log --oneline拿到提交列表，再按类型分组”，同时目录里塞一个scripts/parse.js做格式化。助手在合适的时机读到这份说明，就知道该调用哪条命令、输出该长什么样。

这里有个关键点容易被忽略：技能不是硬编码的功能开关，而是“按需加载的说明书”。它的触发靠描述匹配，而不是靠你记住某个子命令。所以写得好的技能，描述里会明确写“当用户要求整理提交记录、生成 CHANGELOG、汇总版本变更时使用”，覆盖面越精准，误触发越少。反过来，描述写得太宽（比如“处理所有代码相关问题”），助手就会在不该用的时候也去加载，白白占上下文。

注意：技能说明的字数是有隐性成本的。每加载一个技能，就消耗一部分上下文预算。堆十几个技能进去，反而会让助手抓不住重点。我的习惯是常驻技能控制在 5 个以内，其余按项目临时装。

1.3 npx skills 在这条链路里扮演什么角色

npx是 Node 生态里“临时执行一个包、不永久全局安装”的方式。npx skills就是把一个叫skills的命令行工具拉下来跑一次，用完不留在全局环境里。这个工具干的事情很朴素：帮你把技能包从源地址取下来，放到助手约定的目录里，并且维护一份清单。

为什么要有这么个工具，而不是手动复制文件夹？三个理由。第一，技能包可能有多个文件甚至多层目录，手动复制容易漏。第二，安装位置有约定（用户级还是项目级），记错位置就等于没装。第三，也是最重要的——可复现。团队里每个人手动拷贝，版本必然发散；用一条命令，配一份清单文件，谁装出来的环境都一样。

所以整条链路是：npx skills负责“取和放”，CLI 助手负责“读和用”。你不需要改助手本身的配置，也不用手动编辑什么全局 JSON，装完重启会话就生效。这个设计我觉得挺克制的，比那种要你改一堆配置文件的方案省心。

2. 动手之前：环境准备的三件必查项

2.1 Node 版本与 npm 版本基线

npx是 npm 自带的，所以第一件事是确认 Node 在不在、版本够不够。很多“命令跑不起来”的问题，根子上都是 Node 版本太老，npx对某些包的行为不一致。

node -v npm -v npx -v

我的经验基线是Node 18 以上、npm 9 以上。低于这个线，npx在解析包名和缓存策略上会有一些古怪行为，表现为命令卡住或者报一个和真实原因完全无关的错。如果版本不够，别硬扛，用版本管理工具切一下，比修环境快得多。

# 用 nvm 之类的版本管理工具切换（示例） nvm install 20 nvm use 20

顺带说一句，npx第一次执行某个包时会问你一句“需要安装，是否继续”，输入y回车即可。如果你在脚本里跑，记得加-y参数跳过询问，否则脚本会卡在交互上。这个坑我踩过一次，CI 里跑了二十分钟才被发现是卡在确认提示。

2.2 安装位置的选择：用户级还是项目级

技能装在哪里，直接决定了“谁能用到”。常见两种粒度：

我一般的做法是：通用型技能（提交信息规范、代码评审清单）装用户级；业务强相关的技能（这个仓库的数据表结构说明、这套接口的调用约定）装项目级。项目级的目录建议加进版本库，这样新人拉下代码、跑一条安装命令，环境就对齐了。

判断标准其实很简单：换一个仓库还用得上吗？用得上就用户级，用不上就项目级。别嫌麻烦，混装最后一定是“这个项目里助手怪怪的，换个项目又好了”这种玄学问题。

2.3 目录权限与清理旧版本

安装本质是往磁盘写文件，权限问题在老机器或者多人共用的开发机上很常见。表现是命令跑完了、显示成功，但助手就是加载不到。这时候先看两个东西：目标目录存不存在、当前用户有没有写权限。

# 查看目标目录是否存在及权限 ls -la ~ | grep -i kimi # 如果目录不存在，手动建一个（路径按你本地实际约定） mkdir -p ~/.kimi/skills

另外提醒一句：升级前先清旧版本。技能包如果改了目录结构（比如从单文件改成多文件），直接覆盖安装可能留下孤儿文件，助手读的时候会混乱。稳妥做法是先卸再装，或者直接把旧的技能目录整个删掉重来。反正技能目录里都是可再生的内容，删了不心疼。

注意：删除之前确认一下目录里有没有你手写的自定义技能。我自己就干过一次“清理缓存顺手把自研技能删了”的事，重写花了半小时。

3. npx skills 实操：从安装到验证的完整流程

3.1 先看帮助：命令结构拆解

任何不熟的命令，第一步都是看帮助。这一步别省，因为这类工具的版本迭代比较快，参数名可能和你看到的旧教程不一样。

npx skills --help

输出通常会列出几个子命令，核心就三类：add（安装）、list（列出已装）、remove（卸载）。常见的调用形态是：

npx skills add <技能名或源地址> npx skills list npx skills remove <技能名>

有几个参数值得记住：指定安装目标目录的参数（用于切换用户级/项目级）、指定版本的参数（用于锁定版本）、以及静默模式参数（用于脚本）。如果你不确定参数名，npx skills add --help单独看子命令帮助更清楚。

这里说明一下：不同版本的skills工具在参数命名上可能有细微差异，上面是基于常见实践整理的结构，实际以你本地--help的输出为准。养成先看帮助的习惯，比背命令强。

3.2 一次完整的交互式安装记录

下面是我在某台开发机上的真实操作顺序，中间遇到的提示也一并写出来。

第一步，进到项目根目录。这一步很重要，因为项目级安装会以当前目录为基准找落盘位置。

cd ~/workspace/demo-project

第二步，执行安装。

npx skills add changelog-writer

第一次跑会看到类似这样的输出：

Need to install the following packages: skills@x.y.z Ok to proceed? (y)

输入y。接着工具会去拉取技能包，然后问你装到哪：

? 选择安装范围 ❯ 当前项目 (.kimi/skills) 用户级 (~/.kimi/skills)

用方向键选，回车确认。装完之后会打印落盘路径和文件清单，形如：

✓ 已安装 changelog-writer@1.2.0 → .kimi/skills/changelog-writer/SKILL.md → .kimi/skills/changelog-writer/scripts/parse.js

第三步，验证。先看清单：

npx skills list

输出应该能看到刚装的技能名和版本号。再直接看目录，确认文件真的在：

ls -R .kimi/skills

两处都对上了，才算装成功。只信命令的“✓”是不够的——我就遇到过显示成功但实际写到另一个目录的情况，因为当时 shell 的工作目录和我以为的不一样。

第四步，重启 CLI 助手会话。技能的加载通常发生在会话初始化阶段，正在进行的对话不会热加载。退出重进，然后问一句“你现在有哪些技能可用”，如果它能把刚装的技能名报出来，就通了。

3.3 非交互式安装：写进脚本和 CI

团队协作场景下，交互式安装不现实。做法是把技能清单固化成文件，用一条命令批量装。常见做法是维护一个skills.json或类似清单：

{ "skills": [ { "name": "changelog-writer", "version": "1.2.0", "scope": "project" }, { "name": "review-checklist", "version": "0.9.3", "scope": "user" }, { "name": "api-convention", "version": "2.0.1", "scope": "project" } ] }

然后写一个安装脚本，读清单逐条装：

#!/usr/bin/env bash set -euo pipefail # 从清单读取并安装，路径按本地实际约定调整 while IFS= read -r line; do name=$(echo "$line" | cut -d'@' -f1) ver=$(echo "$line" | cut -d'@' -f2) echo "installing $name@$ver" npx -y skills add "$name@$ver" --yes done < <(node -e ' const cfg = require("./skills.json"); cfg.skills.forEach(s => console.log(`${s.name}@${s.version}`)); ')

几个要点：npx -y跳过包安装确认，--yes跳过范围选择（默认用清单里配置的），set -euo pipefail保证任何一步失败就立刻中断。没有这三样，脚本很容易“跑完了但没装上”。

提示：把版本号写死，不要用latest。技能包更新可能改变触发描述，某天你的助手突然开始乱用技能，八成是自动升级惹的祸。

3.4 验证安装结果的三层检查法

装完别急着用，按三层检查一遍，能省掉后面大量排查时间。

三层里最容易出问题的是第三层。文件在、清单也在，助手就是不认，原因通常是路径约定不匹配——比如你装到了用户级目录，但当前助手实例被配置成只读项目级目录。这种时候去看助手启动时的日志或者配置说明，比反复重装有效得多。

4. 技能目录结构与自定义技能写法

4.1 一个技能包的最小结构

搞清楚结构，你才能改、才能自己写。最小可用的技能包长这样：

changelog-writer/ ├── SKILL.md # 必需：元信息 + 操作说明 ├── scripts/ │ └── parse.js # 可选：辅助脚本 └── references/ └── template.md # 可选：参考文档、模板

SKILL.md是唯一必需的。其余目录按需加：要跑脚本就建scripts，要放长文档就建references。这里有个设计上的巧思——长文档独立成文件，正文里只写“详见 references/template.md”，助手需要的时候再去读。这样平时不占上下文，需要时又不缺信息。

我自己写技能时，目录命名会尽量直白：scripts里放能直接执行的东西，references里放给人看的资料。别搞出utils、misc这种，过两个月你自己都想不起来里面是什么。

4.2 SKILL.md 的头部字段怎么写

头部通常是 YAML 格式的元信息块，用于被解析。常见的字段和写法：

--- name: changelog-writer description: 当用户要求整理提交记录、生成 CHANGELOG、汇总版本变更时使用。 version: 1.2.0 --- # 变更日志生成 ## 使用时机 用户提到"更新日志""CHANGELOG""版本变更汇总"等意图时触发。 ## 执行步骤 1. 执行 `git log --oneline --no-merges` 获取提交列表 2. 按 feat / fix / docs / chore 归类 3. 按 references/template.md 的模板输出 ## 约束 - 不臆造提交内容，只做归类和润色 - 提交信息缺失类型前缀时归入"其他"

重点说description。这个字段是触发开关，写得准比写得全重要。我见过反面例子：描述写成“帮助处理代码相关的各种任务”，结果助手在写新功能的时候也去加载这个技能，白白浪费上下文，还干扰判断。正确写法是把触发场景写具体——“用户要求整理提交记录时使用”，边界清晰。

正文部分我习惯分三块写：使用时机、执行步骤、约束。约束这块最容易被省略，但它恰恰是效果好坏的分水岭。写清楚“不许做什么”，比写一堆“要做什么”更能稳住输出质量。

4.3 手写一个技能并挂到本地

写完之后怎么让它生效？两种方式。一是直接把目录放到.kimi/skills/下，工具会自动识别（不需要走npx skills add）；二是如果技能在本地路径，用安装命令指向本地目录。

# 方式一：手动放置 cp -r ./my-skill .kimi/skills/ # 方式二：从本地路径安装（参数以实际帮助为准） npx skills add ./my-skill

手动放置的好处是改起来方便，改完文件重启会话就行，不用重装。研发阶段我基本都用这种方式，等稳定了再打包发布。

写完一定要测触发。方法是新开会话，用自然语言提一个该技能应该响应的需求，看它是否按你写的步骤走。如果不触发，九成是description写得太含糊；如果触发了但步骤没照着走，通常是正文写得太长、重点被稀释。技能文档不是越长越好，一屏能读完的往往最有效。

5. 常见问题与排查技巧实录

5.1 报错速查表

这张表覆盖了我实际遇到过的绝大部分情况。真要说的话，出现频率最高的是“装错目录”和“描述过宽”两类，前者靠核对路径解决，后者靠改文档解决，都不需要动环境。

5.2 技能不生效时的排查顺序

遇到“明明装了却不生效”，别乱试，按这个顺序走，一般三步之内能定位：

第一步，确认文件真的落地。不看命令输出，直接ls目标目录。命令说成功但文件不存在，说明写入路径和你想的不一样，多半是工作目录搞错了。

第二步，确认助手读的是哪个目录。这一步经常被跳过。用户级和项目级是两个完全独立的位置，装 A 读 B 是经典错误。有个笨但有效的办法：在两个位置各放一个标记文件，看助手能报出哪一个。

第三步，确认会话是新的。技能通常在会话初始化时加载，老会话不会热更新。这个问题占比不低，尤其是我这种习惯一直挂着终端不关的人。

三步都过了还不生效，那就去看SKILL.md的头部格式。YAML 块对缩进和分隔符敏感，少一个---或者多一个空格，解析就可能整个失败，而工具未必会给你明确报错。

提示：调试技能触发时，把description临时改成非常直白的短语（比如“仅当用户输入 TEST-TRIGGER 时使用”），然后发一条含该短语的消息。能触发说明加载链路没问题，问题出在描述匹配上；不能触发说明是加载环节的事。这个二分法能快速缩小范围。

5.3 版本管理与回滚

技能包更新频繁的时候，最容易出现“昨天还好用今天就不对了”。防御手段就一条：版本号钉死，升级手动来。

# 查看当前已装版本 npx skills list # 卸载后装回指定版本 npx skills remove changelog-writer npx skills add changelog-writer@1.2.0

我自己的习惯是每次升级前把当前版本号记在一个NOTES.md里，升级后跑一遍常用场景验证。听着有点重，但这套动作坚持下来，至少不会在赶进度的时候被工具问题绊住。

另外提醒一句：自定义技能也要进版本库，但别放进技能安装目录本身。安装目录是“产物”，版本库该存的是“源码”。我在项目里一般是skills-src/存源文件，用脚本同步到.kimi/skills/，这样清理缓存的时候不会误删源文件。

最后分享一个我自己踩过的小坑。早期我特别喜欢一次装七八个技能，觉得能力越多越好，结果发现助手的回答反而变得啰嗦，经常答非所问。后来把技能砍到三个，并且把每个的触发描述都改得更窄，效果立刻不一样了。技能这个东西，价值在“精准命中”而不是“数量堆叠”。现在我的做法是：日常只留两三个高频技能常驻，遇到特定任务再临时装，用完就卸。听起来麻烦，实际比维护一堆互相干扰的技能省心得多。