Factory skills

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

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 and are shared across the factory or scoped to one agent. They 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

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

Custom skills live 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.

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.

Related pages

• About factory agents - Understand the agents that use factory skills
• Creating custom agents - Add specialized roles and skills
• Factory definition syntax - Look up definition files and fields
• Skills for agents - Write skills with arguments and supporting files
• Measure and improve a factory - Evaluate runs and propose improvements