Skip to content

Factories > Factory configuration

Factory skills

Skills give a factory's workers repeatable, version-controlled procedures that can be shared across every worker or scoped to just one.

Open in ChatGPT ↗
Ask ChatGPT about this page
Open in Claude ↗
Ask Claude about this page
Copied!

A skill gives a worker a repeatable procedure, such as a security review or incident runbook. Factory skills extend a worker’s instructions without requiring changes to its prompt.

In a Blueprint, the stage prompt names the work and the skills to use. Keep reusable check commands in a skill; keep stage handoffs, transitions, and human gates in the Blueprint. A skill does not replace the workflow’s stage order.

A factory run can use skills from three sources:

  • Role and integration skills - Default workers have GitHub skills for repository work. The foreman also has a Slack skill. Choosing Linear or Jira during setup gives relevant workers the tracker’s skill and instructions. These skills come from roles and integrations, not files in your definition.
  • Warp-provided skills - Bundled capabilities include oz-platform for cloud agents, factory-files for factory definitions, and factory-mcp for sending work to factories.
  • Custom skills - Team-owned SKILL.md files live in the factory definition or are referenced from another location in the same repository or an external repository. They are shared across the factory or scoped to one worker and extend the built-in skills rather than replacing them.

For bundled skill IDs and how to attribute team-owned skill usage, see Skill actions in conversation data.

Add a custom skill for procedures the built-in skills don’t cover. For example:

  • Run required tests or lint checks.
  • Follow incident-response or triage runbooks.
  • Apply a security or compliance review checklist.
  • Teach a custom worker its job. Custom workers have no built-in skills.

Skills provide instructions, not access to tools or repositories. If a procedure requires credentials or an MCP connection, configure the worker’s secrets and MCP servers through its settings. For how that access is limited, see credential boundaries.

Configure custom skills in the factory’s definition, not its worker settings. You need permission to edit that definition.

To add or update a custom skill:

  1. Open the definition where it’s managed:

    • Warp-managed - In the web app sidebar, expand your factory and click Factory definition.
    • GitHub-backed - Open the connected definition repository. See Where the definition lives.
  2. Create or open the skill file for the scope you need:

    • Every worker - skills/<skill-name>/SKILL.md, for shared procedures such as repository conventions.
    • One worker - workers/<worker-name>/skills/<skill-name>/SKILL.md, for a role-specific procedure such as a security review. If the definition uses agents/, use agents/<worker-name>/skills/<skill-name>/SKILL.md instead. Keep the existing root, even when adding a skill.

    Replace <skill-name> with the skill’s directory name and <worker-name> with the worker’s directory name.

    In a workers/ tree, this shares repository conventions with every worker and gives only the foreman an incident-triage skill:

    skills/
    repository-conventions/
    SKILL.md
    workers/
    foreman/
    skills/
    incident-triage/
    SKILL.md
  3. Write or update the skill’s instructions, name, and description. See Skill file format for frontmatter and Skill arguments for parameters.

  4. Apply the change:

    • Warp-managed - Save the definition. Warp validates and commits it.
    • GitHub-backed - Open a pull request. The factory’s pull request checks validate the change, and merging to the production branch applies it.

For an example of a shared skill and a worker-specific skill in one definition, see 02-sdlc-issue-to-pr in warp-factory-examples.

To reuse skills without copying them, create a .yaml or .yml reference file directly in skills/ for every worker. For one worker, use workers/<worker-name>/skills/ in a workers/ tree or agents/<worker-name>/skills/ in an agents/ tree. Set source to the repository and include to the skills to load, then apply the definition change as described above.

The source can be the repository containing your definition or an external repository. Pin it to a full commit SHA to keep using a particular version of the skill and its supporting files. See Skill reference files for same-repository, external-repository, and SHA-pinned examples.

When a Scorer with Self-improvement enabled flags a recurring failure, the factory can update the responsible skill in a follow-up run. Changes arrive as pull requests for your team to review in the web app or your Git host.