📚 离职知识库

tiktok-agent-skills 拆解与 Skill 工程范式

沉淀日期：2026-08-03 对象仓库：https://github.com/aronhy/tiktok-agent-skills （MIT，32 star / 6 fork，主分支 35 commits，最后一批提交 2026-07-30） 本地临时克隆已随会话销毁；需要时重新 git clone --depth 1 即可。

#给未来的 Claude Code：这份文档怎么用

Leo 让我调研了这个仓库。这份文档有两层用途，读的时候分清楚：

  1. 业务层：如果 Leo 之后要做 TikTok / TikTok Shop 相关的选品、账号诊断、内容获客，这个仓库是现成的 skill 包，直接抄或改。但它强依赖付费第三方数据源（KSS MCP），没 key 基本跑不动 —— 见「落地门槛」一节，别上来就建议装。
  2. 方法论层（更重要）：这是我见过写得最规范的一套中文 Agent Skill，它的目录组织、防幻觉约束、渐进式加载写法，可以直接迁移到 Leo 自己的 skill 上（~/.claude/skills/ 下那批：broadcast、逆向、微信、img 等）。见「可迁移的 Skill 工程范式」一节。

如果 Leo 只是随口问起这个项目，讲第 1 层；如果他在写 / 改自己的 skill，第 2 层才是重点。

#一、事实档案

#是什么

一套给 CLI Agent（作者原文写的是 Codex，但格式是通用的 Anthropic Skill 规范，Claude Code 直接可用）的 TikTok 运营 skill 合集。定位是：把 TikTok 电商 / 内容运营里反复做的数据查询、账号诊断、策略规划，封装成 Agent 能直接执行的 skill，用户只说业务目标，不用记 MCP 工具名和参数。

#三条业务闭环

商品运营：选品 → 店铺 → 视频 → 达人 → 字幕 → 行动方案
账号增长：账号链接 → 账号诊断 → 类目研究 → 差距匹配 → 30 天计划
内容获客：业务简报 → 建号/诊断 → 内容实验 → 单一 CTA → 私域承接 → 线索复盘

三条可独立使用。作者刻意把 Shop 成交路径和私域线索路径分开规划、分开测量 —— 这个产品判断挺清醒。

#5 个 skill

skill 干什么 依赖
tiktok-shop-operator 选品、店铺分析、爆款带货视频、达人匹配、字幕拆解，是整个仓库的事实底座 kss-universal + kss-caption
tiktok-account-audit 公开账号诊断、竞品拆解、未来 7 天行动 可选账号 MCP + 浏览器降级
tiktok-category-strategy 指定国家 + 类目的市场进入研究 kss-universal
tiktok-growth-plan 账号能力 × 类目机会匹配，产出 30 天增长路线 串联上面两个
tiktok-lead-generation-operator 内容获客 + 私域承接（非 Shop 成交向） 复用 account-audit

#目录结构

skills/<name>/
├── SKILL.md              # 27~77 行，只放决策逻辑，不放 schema
├── agents/openai.yaml    # UI 元数据：显示名、简介、默认提示词、MCP 依赖声明
└── references/           # 大头在这，几百行
    ├── mcp-tools.md      # 367 行，工具参数 / 返回字段 / 限流 / 跨表关联
    ├── workflows.md      # 245 行，每条工作流固定六段式
    ├── output-templates.md # 99 行，输出格式模板
    └── examples.md       # 146 行，十个自然语言任务 → 预期工具计划
docs/superpowers/
├── plans/     # 8 份实施计划（按日期命名）
├── specs/     # 4 份设计文档
└── validation/ # 3 份压力测试记录（含真实 transcript）

全仓 ~12,700 行，其中 skill 正文只占约 1,700 行，docs 占大头。也就是说这是"先写设计文档和压测、再写 skill"的做法，不是随手糊的。

#二、可迁移的 Skill 工程范式（重点）

以下每条都是从这个仓库里抠出来、可以直接用到 Leo 自己 skill 上的写法。

#1. SKILL.md 只放决策，schema 全部外链

tiktok-shop-operator/SKILL.md 只有 77 行，开头就是：

## Load References
1. Read references/mcp-tools.md before choosing tools, parameters, joins, or return fields.
2. Read references/workflows.md for operational or multi-step tasks.
3. Read references/output-templates.md before presenting results.
4. Read references/examples.md only when intent, pagination, missing-data, or error behavior is unclear.

Do not duplicate detailed tool schemas in this file.

三个要点：

  • 明确"什么时候读哪个"，而不是笼统说"参考 references/"。第 4 条还带了条件（"只在意图不清时读"），省 token。
  • 最后一句 Do not duplicate detailed tool schemas in this file 是给未来维护者（含 AI）的防腐指令 —— 防止后续迭代把 schema 复制回主文件，导致两处不一致。
  • 结果：主文件常驻上下文的成本很低，重活按需加载。

#2. 每条工作流固定六段式

workflows.md 里六条工作流，每条都严格是：

### Required inputs      # 必填输入
### Tool sequence        # 工具调用顺序
### Pagination and sorting # 分页与排序规则
### Validation           # 校验规则
### Output               # 输出什么
### Stop conditions      # 什么情况下停下

Stop conditions 是最容易被忽略、也最值钱的一段。 大多数 skill 只写"该做什么"，不写"什么时候必须停"，结果 agent 在数据拿不到时会疯狂重试或编造。

#3. 防幻觉约束写成可执行的硬规则

这是全仓最值得抄的部分。SKILL.md 的 Execute Safely 一节（原文英文，摘译）：

  • 先查最小可用范围，再扩大。
  • 用户说"全部"时，分页直到没有下一页、触及工具上限、或额度/限流中断为止。
  • 绝不把第一页称为全部结果。
  • 分页对象按稳定 ID 去重。
  • 用户没给排序时，按返回的销售额降序 —— 有默认值，且默认值要披露。
  • 不要编造 reference 里没有的 orderField 值；必要时在已披露的范围内本地排序。
  • 地区、币种、时间窗口三者严格分开，不混算。
  • 编码百分比增长过滤前先查实时 schema，绝不猜 50% 是 50 还是 0.5。
  • 绝不编造字段、结果、链接、额度状态或"成功的工具调用"。
  • 缺失字段一律写「未提供」。
  • 遇到 401 / 工具不可用 / ERROR_API_MINUTE_MAX / ERROR_API_MONTH_MAX 就停，并报告已完成 vs 未完成。
  • 空结果后不许偷偷放宽筛选条件 —— 只能建议一条放宽方案，然后等用户批准。

最后两条尤其好：它们把"agent 为了交差而自作主张"这个最常见的失败模式，写成了明确禁令。

#4. 数据分层 + 可信度分级

账号类 skill 定义了三层数据来源，优先级写死：

  1. MCP 优先 —— 读实时 schema，实时 schema 永远压过仓库里的参考文档。
  2. 浏览器降级 —— MCP 不可用/为空/字段不足时，只读浏览器里公开可见的页面；遇登录、验证码、反爬、地域限制立刻停止并记录原因。
  3. 公开数据边界 —— 不绕过访问控制，不把搜索摘要或记忆当作已获取的真实数据。

结论按证据完整性打 A/B/C：

  • A：关键结论有完整、可比、可追溯的多层证据
  • B：证据可用但存在已披露的覆盖或字段限制
  • C：只能给出范围有限的初步观察或部分报告

这套「分层 + 分级」可以直接搬进 Leo 的 /逆向 和 /元认知 skill —— 前者需要区分"官方文档 / 抓包实证 / 推测"，后者需要区分"论文原文 / 综述转述 / 我的推断"。

#5. 一次只问一个问题

反复出现的规则：信息缺失时，在做完所有允许的重试、分页和浏览器降级之后，才可以提问，且一次只问一个最关键的问题，并说明这个缺失会影响什么。

对比常见的糟糕做法（一上来甩五个问题让用户填表），这个约束顺序是对的：先自己想办法，实在不行才问，且只问一个。

#6. 凭据边界写进 skill 正文

1. 绝不重复、存储、记录用户提供的 MCP Key，或把它写进生成的文件、示例、回答里。
2. 引用凭据一律用 ${KSS_MCP_KEY} 或打码值。
3. 不购买额度、不改订阅、不绕限流。
4. 不联系达人、不发消息、不下单、不发布内容。
5. 只产出研究、草稿、建议和行动方案；任何外部执行动作都算独立的、需用户单独授权的任务。

第 5 条是好设计：明确区分"规划"和"执行"，skill 只负责前者。

#7. 输出模板里预留"坏情况"格式

output-templates.md 除了正常的商品/店铺/视频/达人结果模板，还专门给了三个模板：非完整结果、空结果、数据风险。

大多数人写模板只写 happy path。给失败态也备好格式，agent 才不会在拿不到数时临场发挥。

#8. 参考文档标注核验日期和权威顺序

mcp-tools.md 开头：

本文档是 Skill 内唯一的 KSS MCP 工具事实来源。工具实际返回与本文件冲突时，以 MCP 实时工具 schema 为准，并记录差异。 官方来源：https://o.kolsprite.com/doc/api.html 核验日期：2026-07-20

"唯一事实来源" + "冲突时谁赢" + "核验日期" 三件套。文档会过期，但写明了过期时该信谁，就不会烂掉。

#三、落地门槛（务必先说清楚再建议安装）

  • 必须有 KSS MCP 的 key，来自 kolsprite.com（第三方 TikTok 数据服务，付费，README 写的是"管理员发放"）。两个 endpoint：
    • kss-universal：https://mcp.kolsprite.com/universal/mcp —— 商品/店铺/视频/达人
    • kss-caption：https://mcp.kolsprite.com/caption/mcp —— 视频字幕
    • 认证 header 名固定为 secret-key，且 KSS MCP Key 和普通 API Key 是两套凭证，不能混用。
  • 没有 key 的话：只有 tiktok-account-audit 能靠浏览器降级跑一点公开主页分析，其余四个 skill 基本是空转。价值大打折扣。
  • 真实查询会消耗用户自己的套餐额度，限流错误码 ERROR_API_MINUTE_MAX / ERROR_API_MONTH_MAX。
  • README 写的是装到 ~/.codex/skills/，但 SKILL.md 是标准 frontmatter（name + description）格式，直接拷到 ~/.claude/skills/ 就能被 Claude Code 加载，无需改造。
  • agents/openai.yaml 是 Codex/OpenAI 侧的 UI 元数据，Claude Code 会忽略它，留着不碍事。

#四、如果要动手，怎么做

只想借鉴写法（推荐先做这个）：

git clone --depth 1 https://github.com/aronhy/tiktok-agent-skills.git /tmp/tas
# 重点读这三个文件，其它都是衍生
# /tmp/tas/skills/tiktok-shop-operator/SKILL.md              主文件怎么瘦身
# /tmp/tas/skills/tiktok-shop-operator/references/workflows.md   六段式工作流
# /tmp/tas/skills/tiktok-shop-operator/references/mcp-tools.md   事实源文档怎么写

真要用起来：先确认能拿到 KSS MCP key，再谈安装。key 到手后：

mkdir -p ~/.claude/skills
cp -R /tmp/tas/skills/* ~/.claude/skills/

MCP 配置照 mcp.example.json 抄，key 放本地配置或环境变量，别提交进任何仓库。

#五、一句话结论

数据能力上，它是 KSS 这家第三方 TikTok 数据服务的一层自然语言外壳，天花板由对方 API 决定；真正的价值在提示词工程 —— 它把"agent 拿不到数据时会瞎编"这个通病，拆成了分层降级、可信度分级、停止条件、非完整结果模板这四套可执行的硬约束。这套约束跟 TikTok 一点关系都没有，任何做数据查询、调研、逆向的 skill 都该抄。

#相关沉淀

  • 02-AI与API/2026-07-27-智能体提示词泄漏压测清单.md —— 同为 skill/提示词工程方向
  • 05-变现与运营/ —— 若后续真做 TikTok 变现，产出归到那边

来源：沉淀/02-AI与API/tiktok-agent-skills拆解与Skill工程范式.md（整理于 2026-08-18）

相关笔记