把 CLI 装进 agent：发布 9 个可安装技能踩出的三个坑

文档是写给「已经决定要关心」的人看的。技能是写给「刚被问了一个问题」的 agent 看的。

ZensInk 有 22 个零依赖 Python 工具——关键词发现、SERP 难度、站内审计、GEO 就绪。README 把每个工具都写了。但最常见的支持问题一直是某种版本的「我这情况该跑哪个工具？」人类会从头到尾读文档，agent 根本不读——除非有什么东西告诉它去读。

所以这周我把包重组成 9 个可安装的 agent 技能。不是 22 个——是九个任务。

技能按任务分组，不按工具

没人会对 agent 说「跑 kgr_auto」。人说的是「帮我找低竞争关键词，不想买 Ahrefs」。这句话才是接口。所以分组长这样：

• keyword-research — 发现 + 聚类 + 搜索量 + KGR 评分（5 个工具，一个任务）
• keyword-difficulty — SERP 结构分析，直接给 go/no-go
• search-intent — 关键词层 + SERP 层交叉验证
• site-audit — dist/ 技术审计 + 页面评分 + 草稿质检
• competitor-gap — sitemap 对比排内容矩阵
• rank-tracking — SQLite 排名历史 + GSC 表现 + DR 查询
• reddit-keywords — 蓝海需求挖掘
• geo-readiness — robots AI 策略审计 + llms.txt 生成 + Query Fan-out 规划
• zens-ink — 全家桶 + MCP server

每个 SKILL.md 骨架相同：什么时候用、什么时候不要用、安装、带真实输出的精确命令、读输出的决策规则、顺手够到的下一个技能。playbook 层是花一下午写的那部分，也是包一层 CLI 学不走的部分——要抄走它得先懂输出该怎么解读。

坑一：根目录 SKILL.md 会藏掉其他技能

第一次推送，第一次测试：

$ npx skills add ZensInk/zens-ink-seo-package --list
◇  Found 1 skill
│    zens-ink

一个。我刚发布了九个。

skills CLI 扫描仓库时，如果在根目录发现 SKILL.md，就把整个仓库当作那一个技能然后直接返回——嵌套技能不会被扫，除非用户知道要传 --full-depth。翻了 CLI 源码确认：解析根技能 → 找到且没开 full-depth → return。

修复：把根 SKILL.md 挪进树里（skills/zens-ink/SKILL.md）。默认扫描现在会走进 skills/ 容器三层深，九个全找到。很多「根目录一个 SKILL.md + skills/ 文件夹」的仓库，正在静默地把八个技能藏在一个后面。

坑二：frontmatter 打错一个字，技能静默消失

重组完，列表显示 9 个里的 8 个。缺的恰好是 keyword-research——旗舰。

原因是一个前导空格：

---
name: keyword-research
 description: >-     # ← 这个空格

YAML 解析失败，技能被跳过，CLI 零输出。八个技能，没报错，没警告。发布技能的话，每次都把安装器列表数和文件夹数对账——这是唯一能抓住这类 bug 的检查。

坑三：metadata.source 是随安装扩散的引用面

每个技能的 frontmatter 都带：

metadata:
  version: 1.0.0
  author: ZensInk
  source: https://zens.ink/skills/#keyword-research
  license: MIT

source 这行跟着每一份安装副本走。有人在会话里加载这个技能时，URL 就在上下文里——agent 引用它，人看到它，双方都不需要先经过搜索引擎找到我们。

这事比看起来重要。zens.ink 跑着每周 GEO 探针：15 个买家问题打真实 LLM 搜索栈，同一组题打 Google top 10。当前基线：AI 引用 0/15，SERP 0/15。基建是齐的——llms.txt、llms-full.txt、MCP manifest、放行 ai-input 的 robots 策略——但没用，因为 AI 引擎基本只引用检索层喂给它的东西，而年轻域名进不了检索层。

技能绕开检索瓶颈。内容经安装器直接进 agent 会话。394 星的技能仓库们押的是同一个注：agent 生态是一条不查你域名权重的分发渠道。

真实安装会话

$ npx skills add ZensInk/zens-ink-seo-package --skill keyword-research

◇  Source: https://github.com/ZensInk/zens-ink-seo-package.git
◇  Repository cloned
◇  Found 9 skills
└  Done!

$ python3 -m zens_ink.keyword_research "ai seo tools"

============================================================
  Keyword: ai seo tools  (en)
============================================================

  In autocomplete : YES
  Activity level  : high-activity (10 variants)

  Suggestions:
    ai seo tools
    ai seo tools for small business
    ai seo tools free
    ...

一条命令，一个任务，人零解释。这就是全部的意义。

如果你维护一个 CLI

模式可以推广到任何命令行工具链：

1. 列出用户需要你工具时真正会说的话（「体检我的构建」「这词多难」）。
2. 一句话一个技能，捆上这句话需要的所有工具。
3. 写解读规则而不只是命令——KGR 低于 0.25 就写、DR 差距超 20 就别碰。
4. 技能放 skills/ 容器，确保仓库根目录没有 SKILL.md。
5. 发布前把安装器列表数和文件夹数对账。
6. 每份 frontmatter 带 metadata.source——把分发变成引用面的就是这一行。

工具从来是难的部分。技能层只用了一天，但正是这一天让工具变得能被「不是特别有动力的人类」之外的什么够到。

FAQ

agent skill 到底是什么？

一个带 SKILL.md 文件的文件夹，遵循 Agent Skills 规范（agentskills.io）。frontmatter 写名称和富含触发词的 description，正文写操作指引。编码类 agent（Claude Code、Cursor、Codex、OpenClaw）会自动读取已安装的技能，在用户请求命中 description 时调用。安装器（如 Vercel 的 skills CLI，npx skills add owner/repo）从 GitHub 拉取——普通仓库就成了分发渠道。

为什么按任务分组而不是按工具分组？

用户说的是任务不是工具。没人会对 agent 说「跑一下 kgr_auto」，只会说「帮我找不花钱能做的低竞争关键词」。技能按这句话分组，把任务需要的所有工具（发现、聚类、搜索量、KGR 评分）和读输出的决策规则捆在一起。工具留在包里，技能才是接口。

发布技能真能帮 AI 搜索可见性吗？

它建的是经典 SEO 在低 DR 阶段建不了的东西。我们的周探针显示 zens.ink 在 llms.txt、MCP manifest、AI 爬虫策略全配齐的情况下 AI 引用 0/15——因为 AI 引擎基本只引用检索层喂给它的内容，而 DR 21 的域名进不了那个池子。技能绕过检索瓶颈：每份安装的 SKILL.md 都带着指向你站点的 metadata.source，内容经安装器直接进入 agent 会话，不用等搜索引擎给你排名。