Claude Skills Collection Logo
Back to notes

NOTES / GUIDES

The software-factory Skill Is a Vocabulary, Not an Automation

Matt Pocock's software-factory skill ships 922 words, five reference files and 71 vendor URLs. It changes how you name things, and it cannot auto-invoke itself.

5 min read

The software-factory skill is a shared vocabulary for designing an automated engineering pipeline, and it does not run anything. Its SKILL.md is 922 words of definitions, five sibling reference files, and a rule that bans certain words. It also carries disable-model-invocation: true, which means Claude cannot bring it into a conversation on its own — a human has to type it. On skills.pub it sits in a repository of 328,182 stars, in an in-progress/ directory the repository itself marks as "not shipped in the plugin".

What problem does a vocabulary skill solve?

Naming drift. Ask three people to describe an automated pipeline and you get "job", "workflow", "run", "pipeline", "task", and "agent" used interchangeably, and a design conversation that keeps restating the same thing in different words. The skill's response is to fix the terms and forbid the synonyms.

Its two core definitions are task and run, and the SKILL.md states the rule directly: "Use these terms, and only these, when discussing or whiteboarding a factory; when the user reaches for a word under Avoid, name the canonical term." Each definition is followed by an _Avoid_: line listing the banned alternatives.

TermWhat it means in this skillAvoid
taskA repeating unit of work the factory performsjob, pipeline step
runOne execution of a taskinvocation, job
triggerWhat starts a run — a ticket, a clock, a webhook—
serviceAn external product the factory plugs intointegration, tool
brakeAn automated check, review, or human gate—

What does the skill tell the agent to do?

Four things, all conversational rather than executable:

  1. Adopt the terms and correct drift when the user uses a banned synonym.
  2. Start from the user's problem, not from the factory — read EXAMPLE-TASKS.md first.
  3. Demand brakes. "Every trigger is an accelerator. Accelerators without brakes make a slop cannon," with three permitted brakes: automated checks, automated review, human review.
  4. Refuse to call a design finished until every slot names a product, or a deliberate none.

That fourth rule is the one with teeth. A design is complete when "every slot names a product (or, for the observability platform, a deliberate none) and every task and ticket source has an answer to every question." It is a checklist that fails visibly, which is more than most design skills offer.

The throttling guidance is concrete enough to quote: "Add one automated trigger at a time, throttled at first (one bug report in ten, a clock once a day), with human review on every PR."

Where does the actual knowledge live?

Not in SKILL.md. The file has zero URLs. The substance is in five reference files totalling about 6,377 words, which the agent is told to read:

FileWordsContents
EXAMPLE-TASKS.md69011 problem-to-task scenarios
TICKET-TRACKERS.md1,22117 vendor URLs
GIT-HOSTS.md1,11014 vendor URLs
RUNNERS.md1,28811 vendor URLs
OBSERVABILITY-PLATFORMS.md1,1227 vendor URLs

71 unique external URLs across the four vendor files, all pointing at documentation and pricing pages — GitHub Actions, Linear, E2B, Daytona, Modal, Fly.io, Langfuse, Datadog, Grafana, Honeycomb, OpenTelemetry. They are reading list entries, not API calls. The skill never fetches them; it expects the agent or the reader to look them up, and the SKILL.md says so: "then research the current options yourself".

That is the honest shape of the skill. It is a briefing document with a banned-words list, plus four files of links to products you would otherwise have to search for.

Why can it not auto-invoke?

disable-model-invocation: true in the frontmatter. The model cannot decide to use it; only a person typing the skill name can. That is a deliberate choice for a skill that rewrites the vocabulary of a conversation — an automatic trigger would hijack ordinary discussion about pipelines.

The practical consequence is that this skill only helps if you remember to ask for it. There is no hook, no session-start injection, and no tool call behind it. The only tool it implies is a file read, for the five reference files.

Installation: the in-progress trap

The repository has a .claude-plugin/marketplace.json with marketplace name mattpocock and plugin mattpocock-skills. Installing from it does not give you software-factory: the plugin's skills array lists 27 entries and does not include it. The repository's CLAUDE.md states the policy — in-progress/: "beta: public on purpose, feedback wanted, not shipped in the plugin".

RouteDelivers software-factory?Command
Claude plugin installNoclaude plugin install mattpocock-skills@claude-plugins-official
npx skills addYesnpx skills@latest add mattpocock/skills -a <agent>
Codex marketplaceYescodex plugin marketplace add mattpocock/skills then codex plugin add mattpocock-skills@mattpocock

The npx route copies editable files into your project, which is the only route that reaches in-progress skills. That is also why skills.pub can index it while the plugin install cannot deliver it: the directory indexes the repository, and the repository contains the file.

When is this skill worth the setup?

If you are about to design an automated pipeline and you have more than one person in the conversation, the banned-words list alone saves a meeting. If you are working alone and already have consistent names, the skill adds a reading list and little else — its own author marks it beta and asks for feedback.

Three checks before you rely on it:

  1. Install via npx skills add, not the plugin, and confirm software-factory/SKILL.md exists in your project.
  2. Start a conversation about a pipeline and use the word "job". The agent should correct you to task or run if the skill is active.
  3. Ask it to finish a design with an empty slot. It should refuse rather than invent a product.

File contents, word counts, URL counts, the disable-model-invocation flag, the 27-entry skills array and the in-progress policy were all read from the repository on 2026-11-20: SKILL.md and CLAUDE.md.

Sources