Skills

Skills package reusable workflows for Droid. A skill is a directory that contains a SKILL.md entry point, optional supporting files, and frontmatter that tells Droid when the workflow applies.

Use skills when instructions are too specific for always-on AGENTS.md, too structured for a one-off prompt, and useful enough to reuse.

Create your first skill#

Create a skill manually#

1. 1
   Create a skill directory

   Put team-shared skills under .factory/skills/ in your repository:

   Bash

   mkdir -p .factory/skills/summarize-diff

2. 2
   Add SKILL.md

   Add required name and description frontmatter, then write the workflow Droid should follow.

3. 3
   Invoke it

   Start a new Droid session if the skill is not already visible. Ask naturally for a matching task, or run /summarize-diff when the skill is user-invocable.

---
name: summarize-diff
description: Summarize the staged git diff in 3-5 bullets. Use when the user asks for a summary of pending changes.
---
 
# Summarize Diff
 
## Instructions
 
1. Run `git diff --staged`.
2. Summarize the changes in 3-5 bullets.
3. Call out migrations, risky areas, and suggested validation commands.

Create a skill from a session#

Use /create-skill to turn a workflow from your current session into a skill. It forks the conversation into a new session in Spec mode, where Droid researches the workflow, checks your existing skills, and proposes a skill. Droid writes files only after you approve, and your original session is unchanged.

In the Droid CLI#

1. 1
   Run the command

   Run /create-skill, optionally followed by a description of the workflow. The Create Skill pane opens.

2. 2
   Describe the workflow

   In Workflow to capture, write one or two sentences about what the skill does and when to use it. Put steps and checklists in the skill itself.

3. 3
   Start or cancel

   Press Enter to start, or Esc to cancel. If Droid is still working, the CLI first asks you to confirm stopping the current run.

In the Factory App#

In the Factory App on web and desktop, /create-skill opens a Create Skill wizard.

1. 1
   Open the wizard

   In the composer of an active session, type /create-skill and select it from the slash command menu. Text you type after the command is filled into the wizard.

2. 2
   Describe the workflow

   In Workflow to capture, write one or two sentences about what the skill does and when to use it. Select Use next to an example to fill the field with it.

3. 3
   Start skill creation

   Select Start skill creation, or press Cmd+Enter or Ctrl+Enter. The app opens the new session, whose title starts with [skill-creation].

In the new session, review the proposed name, description, and instructions, choose whether to save the skill to the project or to your personal skills, and approve.

When to use a skill#

Skills work best for repeatable procedures with a clear trigger and completion criteria:

• Reviewing an API change against a team checklist.
• Summarizing a staged diff in a consistent format.
• Applying project-specific frontend conventions.
• Running a validation workflow with known commands.
• Producing a standard report, ticket, or handoff format.

Use a different surface when the guidance has another shape:

Skill anatomy#

Only SKILL.md is required. Keep supporting files beside it when they make the workflow clearer, safer, or easier to validate.

.factory/skills/review-api-change/
  SKILL.md
  checklists.md
  schemas/
    ship-check.schema.json
  scripts/
    verify-api-change.sh

Good supporting files include:

• Checklists for review, shipping, or validation.
• Schemas that describe expected inputs or outputs.
• Small support scripts the skill can call.
• Reference files that point to existing modules, API surfaces, or run books.

Supporting files are not loaded automatically. Mention them from SKILL.md so Droid knows when to read or run them.

Discovery and loading#

Droid uses progressive disclosure so skill bodies stay out of context until needed:

1. 1
   Discovery: Droid finds SKILL.md files and reads each skill's name and description.
2. 2
   Selection: Droid compares the user request to the available skill descriptions.
3. 3
   Invocation: When a skill applies, Droid loads the full SKILL.md body and follows the workflow.

The description is the routing surface. Write it for model matching: name the action, trigger, and boundary in one or two sentences.

Manage skills#

Run /skills to inspect the skills Droid discovered and the version that is active. The manager separates skills into Effective, User, Project, Plugins, Built-in, and Import from Claude tabs.

The Effective tab groups every discovered skill by status:

Select a skill and press Space to toggle it. The User tab writes the choice to disabledSkills in ~/.factory/settings.json; the Project tab writes to <project>/.factory/settings.json. If another scope or enabled: false frontmatter disabled the skill, the manager identifies that source instead of changing the wrong configuration.

{
  "disabledSkills": ["deploy-production", "summarize-diff"]
}

disabledSkills stores sanitized skill names. User and project arrays are combined, so a disable at either level wins. Removing a name re-enables the skill unless another settings level or its frontmatter still disables it. Names for skills that are not currently installed have no effect.

Where skills live#

Droid can load skills from several scopes. A skill is any directory under a skills/ folder that contains SKILL.md.

Droid searches skill folders recursively. The first directory that contains SKILL.md is treated as a skill directory.

Resolution precedence#

When multiple sources provide the same sanitized skill name, Droid keeps one effective version and shows the others as overridden. Outside mission and automation sessions, the main user-facing precedence is:

1. 1
   Folder-specific and project skills.
2. 2
   Project plugin skills.
3. 3
   Personal skills.
4. 4
   User plugin skills.
5. 5
   Built-in skills.

Skills from organization plugins rank above every source in this list, including mission and automation skills. In a mission session, mission skills rank above project skills. In an automation's sessions, the automation's own skills override every source in the list. To adapt an organization plugin skill for one repository, give the local skill a different name, because a same-named local skill is overridden. Open the Effective tab to see the winning source and the reason each other copy was overridden.

If two skills in the same source share a name, Droid ignores one of them and /diagnostics reports the ignored copy. Rename or remove the duplicate.

Frontmatter reference#

---
name: my-skill
description: What this skill does and when to use it. Use when the user asks to ...
allowed-tools:
  - Read
  - Grep
  - Glob
enabled: true
user-invocable: true
disable-model-invocation: false
license: MIT
compatibility: droid
version: 1.0.0
metadata:
  owner: platform-team
---

Control who invokes a skill#

By default, both you and Droid can invoke a valid enabled skill.

Use disable-model-invocation: true for manual workflows with side effects, such as deployment. Use user-invocable: false for background guidance where a slash command would not be meaningful.

Declare intended tools#

allowed-tools records the tools the skill is designed to use. Droid stores it as skill metadata and shows it in skill surfaces, but standard skill invocation is not a runtime sandbox. A skill cannot add tools that are unavailable in the current session.

allowed-tools:
  - Read
  - Grep
  - Glob

Use allowed-tools when it makes the skill easier to review:

• Read-only audit skills.
• Workflows that should not edit files.
• Workflows that should not call external systems.
• Team-shared skills that need a narrow, reviewable capability set.

Do not rely on allowed-tools as a security boundary for skills. To enforce tool access, use a custom droid with a tool policy or run the workflow in a restricted subagent.

Skills as slash commands#

A valid enabled skill with user-invocable enabled appears as /skill-name. Use it at the start of a prompt or anywhere inside one, and name as many skills as you need:

/summarize-diff focus on migration risk
review this branch with /review-api-change, then /summarize-diff

Droid sends your prompt exactly as typed and attaches each named skill's instructions after it, so the text around the tokens is the request. A skill named more than once loads once.

Typing / after a space opens a skills-only menu; press Tab or Enter to complete the token in place. Recognized skill tokens are highlighted in the input and in the sent message.

A token activates a skill only when it is a whole word that matches a skill name, so paths like /tmp stay plain text. If the prompt starts with a slash command that is not a skill, that command owns the rest of the line and later tokens do not activate skills.

If a custom slash command already uses the same name, the custom command keeps that slash command and the skill remains available for automatic selection by Droid.

Best practices#

Troubleshooting#