欢迎加入：和 TranFu Skill 系统一起工作的第一天

欢迎加入 TranFu。

你第一天可能会同时听到一串新词：Skill、tfs、GitHub、TRANFU//AGENTS、Agent 管家小羊、调用看板……先别急着记。它们其实只是在解决一件事：把一个人验证过的工作方法，变成整个团队下次都能直接使用的能力。

你可以先把这套系统想成三样东西：

• tranfu-skills 是团队共同维护的“工作方法库”。
• tfs 是管理员，帮你搜索、安装、更新和发布 Skill。
• TRANFU//AGENTS 是反馈器，记录哪些 Skill 真的被用到了，帮助我们决定下一步优化什么。

这篇指南会陪你完整走一遍。你不需要先学 Git 命令，也不需要自己研究 SKILL.md 格式。跟着做完第一次安装、第一次调用和第一次发布，就能理解整个系统。

flowchart LR
  You["你有一套好用的方法"] --> Create["skill-create-workflow 帮你整理"]
  Create --> PR["通过 PR 进入公司库"]
  PR --> Team["同事安装并调用"]
  Team --> Data["看板记录真实使用"]
  Data --> Improve["AI 与作者继续优化"]
  Improve --> PR

先完成第一次接入

这一段是你的入场手续。正常情况下，半小时内可以全部完成。

第一步：让系统认识你

如果还没有 GitHub 账号，先注册一个，然后把 GitHub 用户名发给技术总监。管理员会邀请你加入 tranfu-labs 组织。

接着，把你的 Lark Public ID 和 GitHub User ID 一起发给管理员。管理员会在「🐑 Agent 管家小羊」中关联两个身份，并把你拉进「Tranfu Skill 运营」群。

你可能会问：

为什么要关联两个身份？

因为 Skill 的代码和 PR 在 GitHub，提醒和讨论在 Lark。关联后，当你的 Skill 发布成功、审核需要你判断，或者有人想修改你的 Skill 时，机器人才能在群里找到并艾特正确的人。

第二步：请 Agent 安装公司 Skill 库

确认电脑已有 Node.js 20+，并且 npm 全局目录可写。遇到权限问题时不要使用 sudo npm i -g 强行安装，让 Agent 按安装文档排查。

打开任意一个你正在使用的 Agent，把下面这句话完整发给它：

请阅读 https://github.com/tranfu-labs/tranfu-skills/blob/main/INSTALL.md 并按文档步骤帮我安装公司 skill 库。

你会看到 Agent 安装 tranfu-skills，初始化 tfs，再做一次环境自检。完成后，系统里会出现两个常用入口：

• tranfu-router 负责搜、装、列、升级、卸载和诊断。
• tranfu-publish 负责发布自己的 Skill、推荐外部 Skill 和补充使用案例。

你不需要主动调用它们的技术命令。后面只要用自然语言表达意图，Agent 会帮你选择正确入口。

如果想了解安装过程，可以读：走一遍基础流程，安装 tranfu-skills。

第三步：让每个 Agent 都能记录 Skill 调用

TRANFU//AGENTS 调用统计是必装项，而且是每个 Agent 环境分别接入一次。例如你同时使用 Claude Code 和 Codex，就在两个环境里各做一次；Hermes、OpenClaw 也是同样的规则。

在当前 Agent 中发送：

请根据 https://raw.githubusercontent.com/tranfu-labs/tranfu-agents-app/refs/heads/main/INSTALL.md
帮我接入 TRANFU//AGENTS。
 
我的姓名：<你的姓名>
这个 Agent 的用途：<例如写代码、调研、文档写作>
看板地址：https://tranfu-agents-app.tranfu.com
接入密钥：请提示我向管理员获取，不要使用公开文档中的示例密钥。

安装器会自动识别当前是 Codex、Claude Code 还是其他 runtime。接入密钥不要写进公开文档、仓库或截图，直接向管理员获取。

默认统计只包含操作人、Agent 用途、运行状态、活跃时间和调用的 Skill 名，不包含 Prompt、代码、参数或输出。不要自行开启内容采集；如果工作确实需要，必须先确认相关内容允许被看板访问者看到。

第四步：完成你的第一次 Skill 调用

现在我们做一个没有副作用的小测试：

安装公司库中的 prompt-review skill，并在当前会话调用一次。
这次只测试 Skill 调用统计，不修改任何文件。

随后打开 Skill 调用看板，或者直接查看 prompt-review 的调用记录。

当你在最新记录里看到自己的名字时，第一次接入就完成了。到这里，你已经具备日常使用公司 Skill 的全部基础条件。

日常使用时，你只需要“说人话”

第二天开始，你几乎不会再碰安装命令。需要什么，直接告诉 Agent。

你：搜公司 Skill 关于市场研究的。

Agent：我会从公司库里找最匹配的候选，并告诉你各自适合什么场景。

找到合适的之后继续说：

安装 prompt-review 到用户级。

想看看本机已经装了什么：

列出我已经安装的公司 Skill。

想拉取最新版：

更新 TranFu 库。

想移除一个由公司库安装的 Skill：

卸载公司 Skill prompt-review。

默认装到用户级即可，这样同一个 Agent runtime 下的不同项目都能使用。

偶尔你会在仓库里看到三个目录。meta-skills 是管理这套系统的工具，own-skills 是公司成员原创的能力，external-skills 是团队认可并推荐的外部能力。作为普通使用者，你不需要按目录操作；知道它们来源不同就够了。

当你第十次重复同一件事，就该想想 Skill 了

也许某天下午，你又一次对 Agent 解释：报告必须有哪些栏目、什么情况不能下结论、文件应该放在哪里。这个时刻往往就是一个新 Skill 的起点。

先不要急着写文件。问自己四个问题：

这件事是不是经常重复，而且每次都占用不少时间？

流程是不是相对固定，而不是每次都完全不同？

这里面有没有 Agent 自己猜不到的公司规则、判断标准或交付格式？

我能不能说清楚什么时候该用、做到什么算完成？

如果多数答案是“是”，就值得继续。反过来，普通翻译、简单润色、一次性临时任务，或者只有结论没有流程的经验，通常不需要做成 Skill。

拿不准时，直接把原始材料交给 skill-content-fit：

请用 skill-content-fit 判断下面的内容是否值得做成 Skill，并指出缺失信息：
 
<粘贴你的经验、规则、流程或复盘>

它不会为了增加数量而一味说“可以”。它会检查内容是否可重复、有没有明确触发条件、能不能执行、如何验证，以及边界和反例是否足够。

更完整的判断方法见：讲解什么内容适合做成 Skill。

第一次创建 Skill，不要一个人闷头写

确定值得沉淀后，把材料交给公司标准入口 skill-create-workflow：

请用 skill-create-workflow，把下面这套工作方法创建成一个公司 Skill：
 
<粘贴规则、流程、案例或提供本地文件路径>

接下来，Agent 不应该立刻丢给你一个看起来完整的文件。它会先和你聊：真实用户会怎么说、哪些相邻请求不该触发、输入输出是什么、缺文件或权限时怎么办、什么结果才算完成。

这种追问不是在拖慢进度。一个 Skill 最有价值的部分，恰恰是把“你凭经验就知道”的判断讲清楚，让下一位同事和下一次对话都能复用。

在后台，标准工作流会帮你完成这些事：

1. skill-content-fit 先判断内容是否达到准入标准。
2. skill-domain-framing 找到合适的任务域、名称和边界。
3. Agent 通过访谈补全流程、失败路径、正反例和验收标准。
4. skill-creator 负责创建符合平台格式的文件。
5. prompt-review 检查触发、边界、指令力度和流程完整性。
6. tranfu-publish 把成果提交到公司库并创建 Pull Request。

你不需要逐项申请人工审批。通过标准工作流时，prompt-review 会自动执行；真实案例测试建议在发布前跑一次，也会在高频 Skill 后续优化时继续补充。只有依赖作者真实意图的问题，系统才会回来问你。

如果你想先了解写作过程，可以读：讲解如何编写 Skill。

提交 PR 之后，会发生什么

创建流程结束后，你会在 GitHub 上得到一个 Pull Request。它是 Skill 进入公司库的唯一正式入口，main 分支不会被直接修改。

自动流程会检查格式，补充或规范中英文可读名称和中英文 README，再运行仓库校验、生成 catalog。合并发布后，「🐑 Agent 管家小羊」会在 Lark 推送“Skill 已上线”卡片并艾特作者。卡片里的入口可以直接打开刚发布的 Skill。

自动补充 Icon 还没有实现，所以暂时不要把“没有 Icon”当成发布失败。

大多数格式性问题交给 AI 处理，但下面几种情况会停下来找人：

• 格式异常，自动流程无法确认怎样修才安全。
• PR 意外删除了已有文件或 Skill。
• 修改已有 Skill 的人不是原作者。
• prompt-review 发现必须由作者决定的 think 问题。

你可能会在群里看到 direct 和 think 两个词。direct 表示存在标准答案，例如字段名对齐、格式修正，可以自动处理；think 表示答案取决于真实业务意图，例如用户平时到底会怎么称呼这个 Skill、两条规则冲突时哪条优先。AI 不会替作者编造这些答案，而是把问题发到「Tranfu Skill 运营」群里。

当前阶段的重点是让更多真实工作方法进入公司库，再根据使用数据逐步优化。因此，普通版本和 1.0.0+ 版本不设置额外的人工审批差异，但所有变更都必须保留 PR 记录。

发布之后，Skill 由原作者继续维护。其他同事发现问题时，先在运营群联系作者；非原作者直接修改已有 Skill 的 PR 不能自动通过。

完整发布教程见：讲解如何发布你的第一个 Skill。

看到一个好用的外部 Skill，也可以带回来

你不需要重新包装或复制别人的完整内容。把上游 URL 交给 tranfu-publish 即可：

推荐这个外部 Skill 到公司库：
<外部 Skill 或仓库 URL>

Agent 会验证链接，判断上游包含一个还是多个 Skill，为每个 Skill 创建指向 source_url 的薄指针，并起草推荐场景、同类对比、使用技巧和已知限制，最后通过 PR 提交。

公司库不会复制并接管外部 Skill 的完整正文。安装时，tfs 仍从上游获取内容。因此，“进入推荐列表”不等于公司替上游提供安全或许可证担保。推荐前至少确认来源可信、许可证允许使用、不会读取或上传不必要的数据，并留意后续上游更新可能带来的变化。

Skill 上线不是终点，真实使用才是

TRANFU//AGENTS Skill 看板 是公开的。它会展示哪些 Skill 被调用、调用次数和趋势、谁使用得最多，以及当前活跃的 Agent。

每天晚上 20:00，公司大群会收到当天的 Skill 调用日报。它不是排行榜考核，而是帮助我们回答更实际的问题：哪些 Skill 已经进入日常工作？哪些开始增长？哪些高频能力值得优先优化？

当某个 Skill 使用变多，或者到了定期治理时间，系统会重新运行质量检查。能机械修正的 direct 问题由 AI 处理；需要业务判断的 think 问题在运营群里交给原作者。作者可以结合真实使用场景决定是否接受，优化建议目前不是强制整改任务。

一个工作日早晨，更新应该悄悄完成

理想状态下，每台接入的 Mac 会在工作日早上 9:00 自动检查 TranFu Core 和本机已经安装的公司 Skill。普通版本和大版本都直接更新；上游删除的 Skill 不会顺手删除本地副本；改过的本地 Skill 不会被覆盖。

更新结束后，macOS 会发一条系统原生通知，例如：

TRANFU//SKILLS 更新完成
 
Core：0.6.0 → 0.7.0
已更新 3 个 Skill：
- prompt-review：0.9.0 → 0.9.1
- skill-content-fit：0.3.0 → 0.4.0
- market-analysis：1.2.0 → 2.0.0

如果某个 Skill 因本地修改或其他原因更新失败，通知会写清楚名字和原因：

TRANFU//SKILLS 更新部分失败
 
Core：0.6.0 → 0.7.0
成功：2 个 Skill
失败：1 个 Skill
- prompt-review：检测到本地修改，未覆盖

收到失败通知时，不需要自己排查底层脚本，直接到「Tranfu Skill 运营」群联系管理员。

这套工作日自动更新仍是目标机制，管理员实施项在文末。在它完成前，或者你想立即拉取最新版，可以在任意 Agent 中说：

更新 TranFu 库。

当前手动更新可能重新下载并替换由 tfs 管理的 Skill 目录。如果你改过本地 Skill，先保留改动或联系管理员，不要假设现有更新命令已经具备本地修改保护。

你可能还会问

我可以直接改本地安装的 Skill 吗？

可以，用来验证想法没有问题。但本地修改不会自动变成团队标准版本。确认有效后，回到运营群联系原作者，通过公司库 PR 发布正式改动。

看板是公开的，会不会把我的工作内容传出去？

默认不会上传 Prompt、代码、参数或输出，只记录操作人、Agent 用途、运行状态、活跃时间和 Skill 名。但“调用了什么 Skill、调用了多少次、谁在使用”本身是公开可见的。不要自行开启内容采集。

公开仓库里最容易犯的错误是什么？

把内部信息当成案例一起提交。任何 Skill、README、案例、测试数据和截图都不能包含密钥、客户资料、非必要个人信息、内网地址、未公开产品或商业计划，以及没有授权公开的 Prompt、代码、日志和 Agent 输出。

目前自动敏感信息审核还没有完成，所以 CI 通过不等于内容一定适合公开。提交前，作者仍要自己检查。

安装、统计、发布或更新出了问题，我应该找谁？

统一到「Tranfu Skill 运营」群联系管理员。请带上报错文字、PR 链接或 macOS 通知里的失败原因，但不要在群里粘贴密钥。

走到这里，你已经会用了

不需要背诵全文。确认自己完成下面几件事即可：

• GitHub 已加入 tranfu-labs，Lark 与 GitHub 身份已经关联。
• 已进入「Tranfu Skill 运营」群。
• 已安装 tranfu-skills，自己的每一个 Agent 都已接入 TRANFU//AGENTS。
• 已调用一次 prompt-review，并在公开看板看到记录。
• 会用自然语言搜索、安装和更新公司 Skill。
• 知道什么时候值得创建 Skill，以及如何交给 skill-create-workflow。
• 知道原创 Skill 和外部推荐都通过 PR 进入公司库。
• 知道 Skill 由原作者维护，公开仓库不能提交密钥和未授权信息。

接下来最好的学习方式不是再读一遍文档，而是找到一个你今天正在重复的工作，先问问 skill-content-fit：这件事值得成为团队能力吗？

参考资料：

• 公司 Skill 仓库
• 公司 Skill 库安装说明
• Skill 入门第 1 篇：安装 tranfu-skills
• Skill 入门第 2 篇：什么内容适合做成 Skill
• Skill 入门第 3 篇：如何编写 Skill
• Skill 入门第 4 篇：如何发布第一个 Skill
• TRANFU//AGENTS 安装说明
• 公开 Skill 调用看板

管理员 TODO

下面的内容不属于新职员入门步骤。它们是访谈中确认、但尚未全部实现的目标能力。管理员可以把任意一段直接复制给 Agent，在对应仓库中执行。

TODO 1：实现工作日 9:00 自动更新和 macOS 通知

请在 tranfu-skills-cli 中设计并实现 macOS 自动更新安装流程。
 
目标：
- 安装或初始化 TranFu Skill 系统时，为当前用户注册工作日早上 9:00 执行的定时任务。
- 定时任务在后台检查并更新 TranFu Core 和本机所有由 tfs 管理的已安装 Skill。
- 普通版本和大版本都自动更新。
- 上游已删除的 Skill 只报告，不删除本地目录。
- 更新完成后用 macOS 自带的 osascript display notification 发送原生通知。
 
成功通知必须包含：
- Core 的旧版本和新版本。
- 更新成功的 Skill 数量。
- 每个 Skill 的名称、旧 semver 和新 semver，不显示内部 SHA。
 
失败或部分失败通知必须包含：
- 成功和失败数量。
- 每个失败 Skill 的名称和可理解的具体原因。
- 不要求用户打开新 Agent 会话。
 
约束：
- 定时任务必须幂等安装，重复运行不会创建重复任务。
- 不能依赖交互式 shell 的 PATH；必须可靠定位 node、npm 和 tfs。
- 不使用 sudo。
- 提供安装、状态检查、手动执行和卸载定时任务的命令。
- 为版本比较、通知内容、部分失败和上游删除补充自动化测试。
- 更新 README、INSTALL.md 和 CHANGELOG。

TODO 2：保护本地修改，禁止自动覆盖

请在 tranfu-skills-cli 的更新流程中增加本地修改保护。
 
要求：
- 安装 Skill 时记录足以判断本地文件是否被修改的内容摘要。
- 更新前比较当前目录与安装时摘要。
- 如果发现本地修改，跳过该 Skill，不删除、不覆盖、不自动合并。
- 更新结果返回稳定的 machine-readable 状态 local-modified。
- 结果中包含 Skill 名、安装版本、远端版本和“检测到本地修改，未覆盖”的原因。
- macOS 自动更新通知必须展示这个失败原因。
- 提供用户显式放弃本地修改后重新安装的安全入口，但绝不在后台自动执行。
- 覆盖新增文件、删除文件、修改文件和无法读取文件等测试。

TODO 3：非原作者修改 PR 转人工审核

请在 tranfu-labs/tranfu-skills 仓库的 PR 审核流程中增加作者身份校验。
 
规则：
- 新增原创 Skill 时，记录并校验 frontmatter author 与提交者身份。
- 修改已有 own-skill 时，如果 PR 作者不是该 Skill 的原作者，禁止自动审核通过和自动合并。
- Bot 在「Tranfu Skill 运营」群中通知原作者和管理员，附 PR 链接、提交者、受影响 Skill 和改动摘要。
- 原作者或管理员明确批准后才能继续。
- Bot 或管理员自己的维护提交要有清晰、可审计的白名单机制。
- 身份无法解析时默认转人工，不允许默认放行。
- 为原作者修改、非原作者修改、多人 Skill、机器人维护和身份缺失补测试。

TODO 4：增加公开仓库敏感信息审核

请在 tranfu-labs/tranfu-skills 的 PR CI 中增加公开内容安全检查。
 
至少检查：
- API Key、Token、密码、Cookie、私钥和证书。
- Lark、GitHub、云服务和常见 SaaS 凭证格式。
- 私有 IP、内网域名和内部服务入口。
- 手机号、邮箱、身份证等不必要个人信息。
- 可能包含客户资料、未脱敏日志或内部商业信息的高风险文件。
 
处理规则：
- 高置信度密钥和私钥必须阻断合并。
- 低置信度个人信息或业务信息转人工确认。
- 报告只显示文件和位置，不得在日志中完整回显秘密。
- 支持有理由、有审计记录的误报豁免。
- 扫描 SKILL.md、README、cases、脚本、测试数据、图片元数据和其他提交文件。
- 在 README 和贡献说明中补充公开仓库安全要求。

TODO 5：实现自动生成和补充 Skill Icon

请为 tranfu-labs/tranfu-skills 的新 Skill 发布流程实现 Icon 自动补充。
 
要求：
- 明确 Icon 的文件格式、尺寸、透明背景、命名和目录规范。
- 新 Skill PR 缺少 Icon 时由自动流程生成候选资源并提交到 PR 分支。
- 不覆盖作者已经提交且符合规范的 Icon。
- 生成失败不能静默，必须在 PR 和「Tranfu Skill 运营」群中说明原因。
- 资源不得包含第三方商标侵权元素、个人信息或未授权素材。
- 给 catalog、官网展示和安装包建立同一份稳定的 Icon 路径约定。
- 补充格式校验、尺寸校验、文件大小和回归测试。

TODO 6：修正公司库 README 与当前审核规则

请更新 tranfu-labs/tranfu-skills 仓库 README 和相关发布文档，使其与当前公司规则一致。
 
需要修正：
- 删除“发布 1.0.0 或更高版本前必须人工审核批准”的旧规则。
- 说明当前阶段默认走自动格式审核和可追溯 PR。
- 说明格式异常、意外删除、非原作者修改和 think 类作者决策必须转人工。
- 说明自动流程会补充中英文可读名称和中英文 README。
- 把自动补 Icon 标为待实现，不得写成已经上线。
- 说明 Skill 原作者负责维护，其他人先在「Tranfu Skill 运营」群联系原作者。
- 说明当前 tfs 已支持手动一键更新；工作日 9:00 自动后台更新在对应功能完成前标为目标机制。
- 检查 README、INSTALL、CHANGELOG 和其他贡献文档是否还有冲突表述，并保持一致。