headcount: Packing 172 Skills into a Corporate Org Chart — Chinese README Now Available

Title

headcount: Packing 172 Skills into a Corporate Org Chart — Chinese README Now Available

Meta Description

headcount organizes 172 agent skills by corporate structure, with 16 departments installable independently. The Chinese README adds a quick-start guide explaining key constraints like ChatGPT's 8000-character context budget.

Article Content

Once you've saved more than thirty prompts, chaos sets in. You forget what you have, two prompts do nearly the same thing and you can't tell which is the latest, and when you can't be bothered to dig through them you just paste one giant "mega-prompt" into the session — half of which has nothing to do with the current task.

headcount is the answer to this problem. It organizes agent skills according to a corporate structure: one CEO, 16 departments, 172 skills. Each department installs as an independent plugin, and a project only loads the parts it needs. Skills are addressed as department:skill, so names don't collide across departments.

The original repo is cbrock84/headcount, with 2,047 stars, written in Markdown, MIT licensed. The Chinese translation of the README is now published at yangshun2005/headcount-cn. This article focuses on the latter, because its translation does something ordinary translations usually don't.

What headcount actually is

The official one-liner: an agent organization organized by corporate structure — 15+ departments, 125+ skills, each independently installable, and citing the standards and regulatory bodies that adjudicate the issue. Runs on Claude Code and ChatGPT.

The README's own numbers are 16 departments and 172 skills. The one-liner says 15+ and 125+. Both figures appear in the source material; I won't reconcile them here, nor should we assume the smaller number is the outdated one — the README's department table is the finer-grained source.

The structural idea is the part worth understanding. Most prompt libraries are a flat list; headcount is a tree, with an installation boundary on every branch. The CEO's office sits at the top, with 7 skills; the departments below each carry their own skills and a agent charter in .claude/agents/. The charter lets a department be delegated to as a subagent with its own dedicated write scope — the "producer/auditor" separation described by the agent-hierarchy skill.

Addressing is namespaced. security:threat-modeling, finance:unit-economics, demand-generation:landing-page-cro-expert. You can ask in natural language and let the matching mechanism load skills, or you can invoke by name when you need a specific perspective:

/finance:financial-modeling

On .claude/agents/ and agent charters: In Claude Code's conventions, the .claude/agents/ directory holds subagent definition files — each file declares a role that the main agent can delegate to, including its responsibilities, available toolset, and permission boundaries. headcount places each department in this directory, effectively registering a Markdown-written "expert persona" as a programmatically invocable execution unit. The so-called "producer/auditor" separation means the same task is executed and reviewed by two agents whose write scopes don't overlap: the auditor can only read the producer's output and cannot rewrite it, mechanically reducing the risk of self-confirming correctness. This is also why a department isn't just a collection of prompts — it carries permission declarations, and those permissions are enforced by the host tool (Claude Code or Codex) rather than relying on the model's own compliance. Understanding this is what makes clear why "install by department" is both a context-budget problem and a permission-isolation problem.

Installation, and the one constraint that decides everything

The install commands under Claude Code:

/plugin marketplace add cbrock84/headcount
/plugin install security@headcount

Then add departments as needed — /plugin install it-operations@headcount, and so on.

ChatGPT and Codex use the same repo. You add it as a plugin marketplace (ChatGPT reads the manifest under .agents/plugins/marketplace.json), or you copy the departments you want into your own project's .agents/skills/ directory. The skill files are identical on both platforms; only the manifest files differ, and both manifests are generated from the same directory tree — so a fix in one place lands in both. This is what AGENTS.md is for.

The constraint below explains the entire design. On the ChatGPT/Codex side, skill descriptions share a context budget of roughly 8000 characters. The 16 departments together come to about 50,000 characters. Installing only the departments you'll actually use isn't fussiness — it's the only way to fit. If you've ever wondered why the plugin system bothers with per-department granularity instead of one big install, this ratio is the answer.

Installing a department doesn't touch your project. It adds skills to the assistant, writes nothing to your repo, adds no dependencies, and runs nothing on its own.

On the 8000-character skill-description budget: At session startup, Claude Code, ChatGPT plugins, and Codex inject the names and descriptions of all loaded skills into the system context so the model can judge when to trigger them. This content is resident and cannot be unloaded on demand, so it constitutes a hard budget. Estimating English descriptions at roughly 40–60 characters each on average, 8000 characters accommodates only about 100–200 concise descriptions; write detailed department descriptions and the capacity shrinks fast. The 16 departments totaling about 50,000 characters means installing all at once would exceed the budget several times over — the model would either receive truncated content or refuse to load entirely, and both outcomes break the triggering mechanism. You think you've installed 172 skills; what's actually live might be a small fraction. Installing by department is therefore not a matter of style — it's a necessary operation to keep the system in a runnable range. The same logic applies to other plugin ecosystems: any system that keeps metadata resident in context will eventually evolve on-demand loading boundaries.

What the Chinese version adds

The Chinese repo is a translation of the original README, dated 2026-10-14, with the original kept as README_en.md. As of writing, the star count is zero — it shipped today, and there's no point pretending otherwise.

The interesting part is that it's more than a translation. The page has two clearly separated layers:

• A Chinese quick-start section at the top, explicitly labeled as supplementary onboarding material, not part of the original. It answers the questions a Chinese developer hits in the first five minutes: what problem does this solve, what's the shortest path to running it, what are the requirements, what are the pitfalls.
• The translated README body below, which the page states aims to be faithful to the original.

That split matters more than it sounds. A faithful translation of headcount's README gives you the department table and the install commands, but it won't tell you that the 8000-character budget on the ChatGPT side is precisely why you should install two departments instead of sixteen. The original README does mention the budget — but it's buried in a section you only read after forming the wrong mental model. The Chinese page pulls it up into the onboarding section, alongside notes that "installing a department doesn't modify your repo" and that "the original doesn't state OS, hardware, or version requirements."

That last point is a small honesty signal worth flagging. Many translated READMEs quietly fill gaps with plausible-sounding requirements. This one says "the original doesn't state" and moves on. Same with the domestic-network section: it says the original doesn't mention mirrors or accelerated downloads, rather than inventing a mirror that may not exist.

For Chinese developers, the practical difference is onboarding cost. The install path is three commands plus a natural-language question, and the onboarding section gets you there without reading the whole README in a second language. The department:skill addressing scheme, the auto-loading behavior, and "which departments should I install first" all have answers before the translated body even begins.

The page also invites issues or PRs for translation inaccuracies, which is the right posture for a translated document that drifts as upstream changes.

On the plugin marketplace manifest: marketplace.json is the index file by which the host tool identifies "where to install plugins from and under what names," typically declaring the plugin name, source repo, version, and included directories. headcount's cleverness lies in generating two manifests from the same skill directory tree — one for Claude Code, one for ChatGPT/Codex (at .agents/plugins/marketplace.json). The skill files themselves are unchanged; only the index format differs by platform. This "single source of truth, multiple target manifests" approach avoids the version drift typical of forked maintenance: fix one skill description, and the files both manifests point to update together. In this architecture, AGENTS.md plays the role of a cross-platform consistency note — essentially telling any tool that reads it "where the skills are, how to install them, what to watch out for." If your team uses multiple agent platforms at once, this manifest-generation pattern is more worth borrowing than manual syncing.

The part actually worth evaluating

The skills themselves are prose. Markdown files describing how an expert should approach a problem. Whether security:threat-modeling produces useful output depends on the model you run it with and the specifics of your system; I haven't tested it with a real threat model. My sample size is zero. Treat the department table as a map of coverage, not as evidence of output quality.

What's verifiable is the structure. Namespaced addressing prevents collisions. Per-department installation boundaries respect real context limits. Agent charters give departments dedicated write scopes when delegated. And there's a layer of documentation that makes things navigable for a second audience without rewriting the source files.

If you have a flat prompt folder that's already out of hand, installing is cheap and reversible — add a marketplace, install one department, and see whether the matching mechanism actually triggers on your problem. If you read Chinese, start with the Chinese page; the onboarding section is the fastest path to a usable configuration. If not, the original README and docs/GETTING-STARTED.md cover the same ground.

One caveat: the Chinese repo is a translation, so it lags upstream. The translation date is 2026-10-14. If the original adds departments after that, the Chinese page won't have them until someone updates it.

Chinese docs: https://github.com/yangshun2005/headcount-cn

The author is an independent enterprise AI delivery consultant — private LLM deployment, RAG, agent workflows, AIOps.