How to Use the software-factory Skill for Designing a Development Automation Foundation
機械翻訳 / Machine-translated
機械翻訳 / Machine-translated
Original article: How to Use the software-factory Skill for Designing a Development Automation Foundation (cccskills)
Skill page: software-factory
Key takeaways from this article
software-factory is a skill for designing a system that delegates everything from ticket to merge to agents, using shared terminology.
Having it installed lets development leads and solo developers work through their design following consistent terms and questions.
This article walks through the vocabulary and service configurations it provides, how to install it, example prompts, and things to know before using it.
With software-factory, you can work through a development automation design using fixed terms and fixed questions.
The "software factory" referred to here is a system where agents are triggered by tickets, PRs, or scheduled runs and produce merged, finished code.
For example, you might ask:
Use software-factory to design a software factory that triages uncategorized tickets.
Tickets are managed in GitHub Issues.
The agent starts with the problem you want to solve, before getting into the overall structure.
For common problems like uncategorized tickets, the reference is a corresponding example task in the bundled EXAMPLE-TASKS.md.
The design is split into two parts: services and tasks.
On the service side, you decide which product fills each slot—ticket tracker, Git host, and so on.
On the task side, you answer five questions covering trigger conditions, human review points, and more.
Once every slot has a product and every question has an answer, the design is complete.
If you say "job" or "workflow" mid-conversation, the agent will point you to the official term: "task."
This keeps the discussion from drifting into inconsistent terminology within your team.
At the core of this skill are nine terms used throughout the design process.
The agent uses only these terms, and will rephrase anything that falls outside them.
| Term | Meaning |
|---|---|
| Task | A type of work defined once and executed many times—review, research, implementation, etc. |
| Trigger | What initiates a run: a change in the ticket tracker or Git host, a scheduled time, or another run |
| Run | A single execution of one task on one runner |
| Runner | A disposable environment where a run takes place; nothing persists after it ends |
| Ticket tracker | Where tickets live; the interface between humans and agents |
| Ticket source | Feedback buttons, monitoring, error trackers, inboxes, etc. |
| Git host | Where branches, PRs, and reviews live |
| Orchestrator | Receives triggers, launches runs, and records waiting/running/done status |
| Observability platform | Where humans check run logs and status; optional |
The design also rests on two fixed assumptions.
First, runs end without waiting for a human response.
When a human updates a ticket or PR, a new run begins.
Second, runners retain no memory of previous runs.
All history lives only in the ticket tracker, Git host, and orchestrator.
Adding more triggers accelerates automation, but without guardrails, low-quality changes can pile up quickly.
That's why three brakes are built in:
| Brake | Description |
|---|---|
| Automated checks | Fixed gates every run must pass: type checks, linting, tests, etc. |
| Automated review | A separate run reads the diff without bias and checks it against conventions and the ticket |
| Human review | A human reads the PR before merge; issues found feed back into automated checks and reviews |
Automated triggers are added one at a time, starting narrow.
For example: process only 1 in 10 bug reports, or run scheduled tasks just once a day.
Additionally, start with humans reviewing every PR.
Cap how many times a run can loop before returning control to a human.
Each service is treated as a slot to be filled with a product.
One product can fill multiple slots.
The skill includes three example configurations:
| Service | All GitHub | Tickets in Linear | Custom Tracker |
|---|---|---|---|
| Ticket tracker | GitHub Issues | Linear | Custom app |
| Ticket source | Feedback button | Feedback button, monitoring | Feedback button, monitoring |
| Git host | GitHub | GitHub | GitHub |
| Orchestrator | GitHub Actions | Custom server + database | Custom app |
| Runner | Actions runner | Actions, E2B, Daytona, VPS | Custom app or sandbox |
| Observability platform | None (Actions run view is sufficient) | LLM trace tool | Custom app |
The guiding principle is: buy services, build tasks.
Put your design thinking into tasks; use off-the-shelf products for services.
For the ticket tracker specifically, existing products are recommended—they're stable, users already know how to use them, and they're easy to share with external contributors.
For each task, answer these five questions:
For ticket sources, there's also a question about how to prevent the same ticket from being filed twice.
Run the following command in your terminal.
You'll be prompted to choose where to install it—Claude Code, Codex, or another agent.
npx skills add https://github.com/mattpocock/skills --skill software-factory
If you'd rather let your agent handle the installation, send this message as-is:
Please install the following Agent Skill.
https://github.com/mattpocock/skills/tree/main/skills/in-progress/software-factory
First read the contents of SKILL.md and its accompanying files, confirm there is no suspicious behavior (such as sending data externally or reading credentials), then place it at ~/.claude/skills/software-factory/ for Claude Code or ~/.agents/skills/software-factory/ for Codex.
Choose the installation location based on whether you want it available across all projects or just one:
| Destination | All projects | Specific project only |
|---|---|---|
| Claude Code | ~/.claude/skills/ | .claude/skills/ in the project |
| Codex | ~/.agents/skills/ | .agents/skills/ in the project |
This skill is configured so the agent does not load it on its own initiative.
To use it, specify the skill name in your prompt, or use /software-factory in Claude Code.
Example 1: When you're not sure what to automate first
Use software-factory to design a factory that addresses the problem of PRs piling up in review.
I'd like to start while keeping human review in place.
The agent picks a matching task from EXAMPLE-TASKS.md, then works through the service slots and the five questions for each task in order.
It narrows the first trigger to one, and includes where humans review in the response.
Example 2: Deciding which products to use
Use software-factory to help me decide what to use for runners.
Compare GitHub Actions with external sandboxes.
The agent reads the bundled RUNNERS.md to get the full picture, then looks up current options.
The research material breaks down options by category and lists questions to guide your decision.
The response is a comparison structured around those questions.
Example 3: Nailing down a single task
Use software-factory to work through the automated PR review task: trigger conditions, services it reads from and writes to, what it triggers next, where humans review, and how to prevent duplicate runs.
You'll get a breakdown answering each of the five questions in turn.
Any question without a clear answer is left as an open design decision.
software-factory is a skill for organizing design—not building automation.
It includes only SKILL.md and five Markdown reference files; no scripts to run automation are included.
GitHub Actions configuration and runner setup come after the design is finalized.
Product information in the bundled reference files is a starting point for getting the big picture.
SKILL.md instructs the agent to research current options on its own.
Verify features and pricing from official sources before making decisions.
The skill lives in the in-progress folder of the repository and is licensed under MIT.
It's a good idea to read SKILL.md and its accompanying files before installing, and again after any updates.
The same mattpocock/skills repository includes skills useful before and after the design phase.
code-review is a skill for reviewing changes by separating convention compliance from spec fulfillment—a useful reference when designing automated review tasks.
domain-modeling is a skill for clarifying the domain terminology and conceptual boundaries of a project and recording them in a glossary.
If you're not sure which skill to start with, ask-matt can help.
ask-matt will recommend which skill fits your situation and in what order.
This skill covers the vocabulary and thinking for design—it doesn't include construction steps or scripts.
It helps you get as far as deciding which services to use and which tasks get triggered by what.
Yes.
One of the example configurations uses GitHub Issues as the ticket tracker, GitHub Actions as the orchestrator, and Actions runners as the runner.
In that setup, the Actions run view is sufficient, so no separate observability platform is needed.
Just describe the problem you want to solve.
If you have things like uncategorized tickets, PRs waiting on automated review, or bug reports nobody reads, the agent will pull matching task examples from EXAMPLE-TASKS.md.
The design assumes three brakes are built in: automated checks, automated review, and human review.
Start by adding triggers one at a time and having humans review every PR.
Once you trust the brakes, ease up gradually.
software-factory is a skill for designing a system that lets agents handle everything from ticket to merge, using shared terminology.
It's well-suited for development leads whose teams don't yet share consistent vocabulary, and for solo developers thinking through a configuration from scratch.
Start by clarifying the problem you want to solve and answering the five questions for the first task that addresses it.
From there, fill in the product for each slot and add triggers one by one.
Installation instructions and an overview are available on the cccskills page.
The repository is at https://github.com/mattpocock/skills/tree/main/skills/in-progress/software-factory.
This article is a reprint of the cccskills article "How to Use the software-factory Skill for Designing a Development Automation Foundation."
Skill details and installation instructions are on the cccskills software-factory page.