AI Factory: a CLI that installs AI agent skills and spec-driven workflows into a project

The setup work AI Factory moves out of your hands

Every coding agent needs context before it is useful: which skills it can call, which MCP servers are reachable, what a plan looks like, where commits happen. Teams usually rebuild that by hand per repository, and the result drifts. AI Factory's stated purpose is to remove that step. The README puts it as "Stop configuring. Start building." and describes a single command, `ai-factory init`, that installs relevant skills, configures integrations and wires up a workflow. The package description in package.json is narrower and more accurate: "CLI tool for automating AI agent context setup in projects".

The intended audience is developers who already use an agent and want a repeatable process around it. The README lists Claude Code, Cursor, Windsurf, Roo Code, Kilo Code, Antigravity, OpenCode, Warp, Zencoder, Codex CLI, Codex app, GitHub Copilot, Gemini CLI, Junie and Qwen Code, with a link to a supported-agents doc for anything else. That breadth is the point: the same skill set is transformed for each target rather than written once for one vendor. If you use a single agent and never switch, the value shrinks to the workflow itself, which is spec-driven development: plans are written to files, executed task by task, and committed at checkpoints.

What the CLI actually writes into a repository

The repository layout shows the shape of the mechanism. There is a `skills/` directory holding the skill definitions, a `src/` TypeScript codebase compiled to `dist/cli/index.js` and exposed as the `ai-factory` binary, a `subagents/` directory, `schemas/`, `mcp/` and `scripts/`. The README also names `.ai-factory.json` as the project configuration file and points to a full `config.yaml` key reference with a skill read/write matrix.

So the flow is: `init` collects your agent choice, skill selection and MCP servers, then writes agent-specific files into the project and into the agent's own configuration location. The README mentions agent transformers and managed Codex config, and the subagents doc covers a "baseline Codex native agent-file bundle". The test scripts back this up: `test-codex-targets`, `test-managed-skill-receipts` and `test-skill-migration-modes` all exist, which tells you the project tracks what it installed and how to migrate it. That receipt mechanism matters more than it sounds. A tool that edits another tool's config directory needs to know which lines are its own before the next run.

Skills are invoked as slash commands inside the agent. The README shows `/aif`, `/aif-explore`, `/aif-grounded`, `/aif-plan`, `/aif-improve`, `/aif-implement`, `/aif-reference`, `/aif-fix`, `/aif-ci github` and `/aif-docs`. Codex CLI and Codex app use `$aif` style invocations instead. The distinction between explore and grounded is deliberate: explore surveys options, grounded answers a question against the repository before anything changes.

Installing AI Factory and running the first plan

The README gives two global install routes. npm is the primary one, and mise is offered for people who manage global tools that way. Both install the `ai-factory` binary.

npm install -g ai-factory

Then, from inside the project you want to configure, run the interactive wizard. It asks which agent you use, which skills to install and which MCP servers to configure. There is no project scaffolding step and nothing is generated outside the repository and your agent's config directory.

ai-factory init

For scripted or repeatable setups the README shows the non-interactive form with flags. The example below names two agents and two MCP servers, `playwright` and `github`. Use the exact names your agent expects; the README does not publish the full list of accepted values here, it points to the Getting Started doc.

ai-factory init --agents claude,codex --mcp playwright,github

After init, open the agent and invoke the entry command. In Claude Code and most of the listed agents that is a slash command; Codex CLI and Codex app use the `$aif` form instead. From there the documented sequence for a feature is plan, optionally improve, then implement. The plan step is described as creating a branch, analyzing the codebase and building a step-by-step plan; implement walks the tasks and commits at checkpoints. The README also shows `ai-factory update` and `ai-factory upgrade` as CLI commands, though their exact behaviour is left to the Getting Started doc.

/aif-plan Add user authentication with OAuth
/aif-improve
/aif-implement

Where the skills-only route falls short

The README is unusually explicit about a limitation, which is worth taking at face value. If you only want the `aif-*` skills without the full setup, there is a second install path through skills.sh. The command is `npx skills add lee-to/ai-factory --skill '*'`, and the disclaimer states plainly that this installs only the skill files. The CLI commands `ai-factory init`, `update` and `upgrade` are not available, nor is MCP auto-configuration, nor the agent transformers, nor the interactive wizard.

That is a real fork in the road. Skills alone still give you slash commands, but every piece of environment setup stays manual, and the receipt tracking that makes upgrades safe is gone. Anyone who wants `ai-factory update` to work later has to install through npm from the start. The README also links a separate project, `aif-handoff`, described as an autonomous Kanban board built on AI Factory, and points to HLV for people whose goals exceed what AI Factory covers. Neither is documented here, so treat the links as pointers rather than recommendations.

The cost of a tool that edits your agent's configuration

AI Factory's job is to write into directories it does not own: your agent's config, your repository's skill folder, your MCP server list. That is the design, and it is also the risk. The README does not document a rollback command, and it does not describe what happens when a skill file it manages has been edited by hand. The presence of `test-skill-migration-modes` and `test-managed-skill-receipts` in package.json suggests the project tracks ownership, but the README does not spell out the conflict resolution rules. If your team edits generated skill files, find that answer in the configuration and extensions docs before you rely on `ai-factory update`.

The second cost is agent churn. The supported list is long and each target needs its own transformer. A new agent version that changes its skill format is a change AI Factory has to absorb. The release history shows steady iteration: 2.17.0 on 2026-07-06, 2.18.0 on 2026-08-12, 2.18.1 on 2026-08-14, and package.json carries 2.19.0, with the last push to the repository on 2026-09-07. Nothing here indicates a frozen interface, so pin the version you validated rather than tracking latest in CI.

Licensing is the least ambiguous part. The README ends with a License section reading MIT, though the package.json license field is truncated in the repository file, so confirm it from the npm registry entry before you redistribute. MIT permits commercial use and modification; it also means no warranty and no support obligation from the author.

How AI Factory differs from skills marketplaces and hand-written prompts

The obvious alternative is doing nothing and writing your own prompts and MCP configuration per project. That is free and fully under your control, and for a single repository it is often enough. The difference appears at the second and third repository: AI Factory regenerates the same skill set for each agent target, while hand-written files have to be copied and adjusted, and drift the moment one project updates.

The closer alternative is skills.sh itself. The README frames it as the lightweight route: `npx skills add lee-to/ai-factory --skill '*'` pulls skill files from the same author into your project. The approach differs in scope, not in kind. skills.sh distributes skills as files; AI Factory installs skills and then configures the surrounding environment, including MCP servers, agent transformers and managed Codex config, and keeps receipts so later updates know what it owns. If your environment is already configured, the marketplace route is the smaller intervention. If it is not, you are back to manual setup, which is the problem the CLI exists to solve.

Editorial conclusion

Adopt AI Factory if your team already runs one of the supported agents and keeps rebuilding the same prompts and MCP wiring in every repository; the interactive wizard plus the `--agents` and `--mcp` flags are the fastest way to see whether the generated skill files match how you work. Skip it if you only want the `aif-*` skills, because the README states that the skills.sh route installs skill files only and leaves out the CLI, MCP auto-configuration and agent transformers. Before committing, run `ai-factory init` in a scratch clone and inspect `.ai-factory.json` and the files it writes into your agent's config directory, since the README does not document a rollback command.

Frequently asked questions

Official sources

1. Issues
2. lee-to/ai-factory on GitHub
3. Project website
4. README
5. Releases