Skip to content
Warp

Factories > Factory configuration

Factory skills

Skills give a factory's agents repeatable, version-controlled procedures that can be shared across every agent 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 an agent a repeatable procedure, such as a security review or incident runbook. Factory skills extend an agent’s instructions without requiring changes to its prompt.

Skill sources in a factory

Section titled “Skill sources in a factory”

A factory run can use skills from three sources:

  • Role and integration skills - Default agents have GitHub skills for repository work. The foreman also has a Slack skill. Choosing Linear or Jira during setup gives relevant agents 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 agent 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.

When to add a custom skill

Section titled “When to add a custom skill”

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 agent its job. Custom agents 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 agent’s secrets and MCP servers through its settings. For how that access is limited, see credential boundaries.

Add or edit a skill

Section titled “Add or edit a skill”

Configure custom skills in the factory’s definition, not its agent 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 agent - skills/<skill-name>/SKILL.md, for shared procedures such as repository conventions.
    • One agent - agents/<agent-name>/skills/<skill-name>/SKILL.md, for a role-specific procedure such as a security review.

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

    For example, this layout shares repository conventions with every agent and gives only the foreman an incident-triage skill:

    skills/
      repository-conventions/
        SKILL.md
    agents/
      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 an agent-specific skill in one definition, see 02-sdlc-issue-to-pr in warp-factory-examples.

Reference existing skills

Section titled “Reference existing skills”

To reuse skills without copying them into the definition, create a .yaml or .yml reference file directly in skills/ for every agent or agents/<agent-name>/skills/ for one agent. 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.

Skills and self-improvement

Section titled “Skills and self-improvement”

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.

Section titled “Related pages”