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

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.

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.

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.

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. When you run the slash command, Droid loads the skill body and appends any text you typed after the command.

/summarize-diff focus on migration risk

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