企业官网建设流程全解析

headcount开发者指南：从写第一个技能到新增一个部门的完整贡献流程

【免费下载链接】headcountAn agent organization structured as a company — 15+ departments, 125+ skills, each independently installable, citing the standards and regulators that settle the question. Runs in Claude Code and ChatGPT.项目地址: https://gitcode.com/gh_mirrors/hea/headcount

headcount 是一个把 AI Agent 组织成"公司"的开源项目：16 个部门、143 个技能，每个部门都能独立安装，运行在 Claude Code 和 ChatGPT 中。本文是 headcount 贡献流程的完整指南，带你从零开始，先学会写一个合格的 Agent 技能（Skill），再掌握新增一个部门的五步流程，并了解本地校验脚本check-all.sh如何通过 CI 保证每次贡献的质量。

上手前先认识这个项目的"公司结构"

headcount 的设计思路像一家公司的组织架构图：CEO（executive 部门）统管 16 个职能部门，每个部门下有一组专业技能，技能按需自动加载——问到"这个落地页为什么不转化"，就触发demand-generation:landing-page-cro-expert；问"这个岗位招得起吗"，就触发finance:unit-economics。

对贡献者来说，只需要记住三层目录结构：

项目的贡献规范集中在 CONTRIBUTING.md，贡献前建议先通读一遍——它只有几屏内容，却覆盖了对技能的全部评审标准。

准备工作：克隆仓库并跑通检查脚本 🛠️

git clone https://gitcode.com/gh_mirrors/hea/headcount cd headcount ./scripts/check-all.sh

scripts/check-all.sh 会一次性运行全部检查，和 CI 执行的是同一套脚本，所以本地通过就等于 CI 通过。第一次贡献者跑通它就意味着环境就绪。

第一步：写你的第一个技能

1. 选对地方放文件

在目标部门下新建目录，技能文件固定叫SKILL.md：

plugins/<department>/skills/<skill-name>/SKILL.md

动手前请先确认没有现成技能覆盖同一领域。两个描述相似的技能会互相抢触发、导致两者都不可靠——规范的建议是优先扩展现有技能，而不是新增"近邻技能"。完整的写作方法论可以阅读项目自带的 skill-authoring 技能文档。

2. 写好 frontmatter：name 与 description

技能文件以 YAML frontmatter 开头，其中只有description会在"是否加载"决策时被读取，它直接决定技能的触发质量：

• name必须与目录名完全一致，且为小写连字符格式（如unit-economics），否则技能无法加载
• description先写"这个技能做什么"，再写"什么情况下该用它"——用真实用户会说的话，包括各种绕弯的问法
• 描述过短（不足约 80 字符）会被 scripts/validate-skills.py 判定为"薄到无法可靠触发"

3. 正文写作四原则

正文面向"有能力但今天没想过这个问题的人"：

• 方法优先于口号——"要彻底"是噪音，有步骤的操作流程才是指令
• 每条规则说明它背后的失败案例，否则下个读者会把它优化掉
• 具体到可以被证明是错的，模糊到无法反驳的指引等于没有指引
• 长材料放进references/子目录，正文只留工作记忆能装下的内容

⚠️ 特别提醒：如果技能涉及法律、隐私、薪酬、医疗、财务等受监管领域，必须明确写出"哪些可以结构化指导、哪些需要持证专业人士介入"。

4. 上线前自测

写出 3 条应该触发该技能的请求和 2 条不该触发的请求，逐条核对 description 是否真的能区分。有近失请求会被误触发？那就收紧描述。

第二步：本地验证——提交前必做的检查

打开 Pull Request 之前，运行：

git add -A ./scripts/check-all.sh

注意：必须先git add暂存文件。表面守卫（surface guard）读取的是git ls-files，未暂存的新文件对它不可见，会出现"本地通过、提交后 CI 失败"的陷阱，脚本检测到未跟踪文件时会主动告警。

各检查项的作用一览：

📌语言风格：项目统一使用美式英语。scripts/check-us-english.py 会因英式拼写让构建失败，还带--fix参数自动改写——但匹配的是精确词形而非词干，analysis、analyst这类本身正确的词绝不会被误改。

第三步：新增一个部门（五步缺一不可）

新增部门的门槛更高：以下五项必须在同一次变更中完成，否则检查必然失败。

1. 插件目录与清单：创建plugins/<name>/skills/和plugins/<name>/.claude-plugin/plugin.json（可参考 security 部门的清单 格式）
2. 表面图登记：在 docs/AGENT-SURFACES.md 中加一行 roster 和一个surface:块
3. 部门章程：在.claude/agents/<name>.md写该部门的授权与职责边界（charter）
4. 市场注册：在 .claude-plugin/marketplace.json 中加入新部门条目
5. 显示元数据：在 scripts/build-readme.py 的META字典中加入(rank, title, executive)元组，然后运行python3 scripts/build-readme.py重新生成文档

第 5 步有个巧妙的设计：生成器直接从磁盘读取部门列表，如果磁盘上存在但META里没有，会直接拒绝运行——新部门不可能"漏出 README 和 org chart 而检查仍然通过"。

💡 一个组织学建议：先给部门写 chief（部门负责人技能），再补专家技能——部门的职责范围应该先于其中的技能存在。

两个容易忽略的贡献细节

📄 许可证与来源：提交即表示你的贡献采用 MIT License 授权，且只能贡献你有权利这样授权的内容。scripts/check-provenance.py 是兜底扫描（查许可证头、版权声明、SPDX 标识符），它防不住"无声搬运"——真正拦截它的是人工评审，所以引用了他人材料就必须在 PR 中说明来源。

📋 决策记录：凡是有多个可辩护答案的选择，都记入 docs/DECISION-LOG.md。编号在问题被提出时分配、永不复用，每条决策必须带字母选项和明确的推荐项——用D7b这样的"编号+字母"方式引用答案。

贡献流程速查清单 ✅

• 新技能先查重叠，优先扩展现有技能
• name与目录名一致，小写连字符，description 具体且充分
• 受监管领域明确标注需专业介入的边界
• 新部门五步（插件、表面图、章程、市场、META）同一次提交完成
• git add之后再运行./scripts/check-all.sh
• 全绿后提交 PR，附来源说明（如有）

headcount 的 CI 与本地跑的是同一套脚本，贡献流程也因此简单得反直觉：本地全绿，就是合格的贡献。从写第一个技能到新增一个部门，你走的每一步都有可执行的检查在背后守护——这正是这个项目"每个路径有且只有一个负责人"理念在贡献流程上的延伸。

【免费下载链接】headcountAn agent organization structured as a company — 15+ departments, 125+ skills, each independently installable, citing the standards and regulators that settle the question. Runs in Claude Code and ChatGPT.项目地址: https://gitcode.com/gh_mirrors/hea/headcount