Creating Skills

Skills are defined as SKILL.md files inside a named directory. This page covers everything you need to know to write effective skills.

File Structure

Place skills in the appropriate directory depending on scope:

# Project-specific (committed to git)
.devin/skills/
└── my-skill/
    └── SKILL.md

# Global — available in all projects (not committed)
# Linux/macOS:
~/.config/devin/skills/
└── my-skill/
    └── SKILL.md

# Windows:
%APPDATA%\devin\skills\
└── my-skill\
    └── SKILL.md

The directory name is the skill’s identifier (used for /my-skill invocation). The SKILL.md file contains optional YAML frontmatter and the skill’s prompt content.

On Windows, %APPDATA% typically resolves to C:\Users\<YourUser>\AppData\Roaming.

Frontmatter Reference

---
name: my-skill
description: What this skill does (shown in completions)
argument-hint: "[file] [options]"
model: sonnet
allowed-tools:
  - read
  - grep
  - glob
  - exec
permissions:
  allow:
    - Read(src/**)
  deny:
    - exec
  ask:
    - Write(**)
triggers:
  - user
  - model
---

Your prompt content goes here...

All Frontmatter Fields

Field	Type	Default	Description
`name`	string	directory name	Display name of the skill
`description`	string	none	Shown in slash command completions
`argument-hint`	string	none	Hint shown after the command name (e.g., `[filename]`)
`model`	string	current model	Override the model used when running this skill
`subagent`	boolean	`false`	Run the skill as a subagent instead of inline
`agent`	string	none	Run the skill as a subagent using a specific custom subagent profile
`allowed-tools`	list	none	Tools that are auto-approved (no permission prompt) while the skill runs. Does not restrict tool availability — see Auto-Approved Tools. Not applied when the skill runs as a subagent
`permissions`	object	inherit	Permission overrides for this skill. Not applied when the skill runs as a subagent
`triggers`	list	`[user, model]`	How the skill can be invoked

Model Override

Use the model field to run a skill with a different model than the one active in the current session. This is useful for using a faster model for simple tasks or a more capable model for complex ones:

---
name: quick-fix
description: Fast lint fix using a lightweight model
model: swe
---

Fix the lint errors in the current file.

The model name uses the same values as the --model CLI flag (e.g., opus, sonnet, swe, codex). See Models for the full list.

Running Skills as Subagents

Running skills as subagents is experimental. The subagent and agent frontmatter fields may change in future releases.

By default, a skill’s prompt is injected into the current conversation — the agent processes it inline. You can instead run a skill as a subagent, which spawns an independent worker with its own context window. This is useful for skills that perform focused, self-contained tasks where you don’t want the output to clutter the main conversation. There are two ways to run a skill as a subagent:

`subagent: true`

Set subagent: true to run the skill as a subagent using the default subagent_general profile:

---
name: deep-research
description: Thorough codebase research on a topic
subagent: true
model: sonnet
---

Research the topic the user asked about thoroughly.

Search broadly, follow references, and trace call chains.
Report all findings with specific file paths and line numbers.

When invoked, this skill spawns a foreground subagent that runs the skill’s prompt as its task. The parent agent waits for the subagent to complete, then reads and summarizes the results.

When a skill runs as a subagent, its allowed-tools and permissions frontmatter are not applied. The subagent runs with the tool set of its profile — subagent_general has access to all tools. To limit which tools a subagent skill can use, define a custom subagent profile with allowed-tools and reference it with agent: instead of subagent: true.

`agent: <profile>`

Use the agent field to run the skill as a subagent with a specific custom subagent profile:

---
name: review-pr
description: Review the current PR using the reviewer subagent
agent: reviewer
---

Review the staged changes for correctness, security, and style issues.

The agent value must match the name of a registered subagent profile (either built-in like subagent_explore / subagent_general, or a custom profile you’ve defined). The subagent inherits the profile’s system prompt, tool restrictions, and model — while the skill’s content becomes the task. A custom profile’s allowed-tools is a true restriction (unlisted tools are unavailable to the subagent), so this is the way to run a skill with a limited tool set.

If both agent and subagent are set, agent takes precedence. The model field on the skill overrides the subagent profile’s model when both are specified.

Skills running as subagents do not spawn nested subagents — if the skill is already executing inside a subagent, it runs inline instead to prevent infinite recursion.

Orchestrating Subagents Using Skills

Because skills can run as subagents, you can use them to orchestrate multi-step work. Define a set of subagent skills that each handle a focused task, then write a regular skill that invokes them. The outer skill becomes the orchestrator — it calls each subagent, collects the results, and decides what to do next. For example, here are two subagent skills and an orchestrator that coordinates them:

---
name: research-changes
description: Research recent code changes and their impact
subagent: true
---

Analyze the recent changes in this repository:

1. Run `git log --oneline -20` to see recent commits
2. For each significant commit, examine what changed and why
3. Identify any patterns, risks, or areas that need attention

Report your findings with specific file paths and commit references.

---
name: validate-tests
description: Run tests and validate coverage for recent changes
subagent: true
---

Validate the test suite for the project:

1. Identify the test framework and run command
2. Run the full test suite
3. Check for any failing tests
4. Review test coverage for recently changed files

Report which tests pass, which fail, and any coverage gaps.

---
name: health-check
description: Full project health check — research changes then validate tests
---

Perform a full health check on this project:

1. First, use the /research-changes skill to understand recent changes
2. Then, use the /validate-tests skill to verify the test suite
3. Finally, synthesize the findings from both into a summary:
   - What changed recently and why
   - Whether tests are passing
   - Any risks or recommended actions

Invoking /health-check runs the orchestrator in the main agent. It calls /research-changes, which spawns a subagent to explore the repo. Once that finishes, it calls /validate-tests, which spawns another subagent to run the tests. The orchestrator then synthesizes both results into a final summary. A subagent skill will never use a subagent when calling other skills, even if those skills have subagent: true — they run inline instead. This means you don’t need to worry about unbounded nesting. The orchestration pattern is always one level deep: the orchestrator spawns subagents, and those subagents execute everything else inline.

Prompt Content

The body of the SKILL.md file (after the frontmatter) is the prompt that gets injected when the skill is invoked.

Permissions

Skills can define their own permission scope using the same syntax as the main permissions config:

permissions:
  allow:
    - Read(src/**)
    - Exec(npm run test)
  deny:
    - Write(/etc/**)
    - exec
  ask:
    - Write(src/**)

How skill permissions work:

allow — These scopes are auto-approved during skill execution
deny — These scopes are blocked during skill execution
ask — These scopes always prompt the user

deny is the way to hard-block a tool for an inline skill. Tool-name entries such as exec or edit block the entire tool, and mcp__server__tool patterns block MCP tools — see Tool-Based Permissions.

Skill permissions are additive to (not replacing) the session’s base permissions. A skill cannot grant permissions that are denied at a higher level (project or organization config).

Skill permissions apply only when the skill runs inline. They are not applied when the skill runs as a subagent (subagent: true or agent:).

Auto-Approved Tools

allowed-tools lists tools that are auto-approved while the skill runs, so the agent can use them without a permission prompt:

allowed-tools:
  - read
  - grep
  - glob

Each entry is equivalent to a permissions.allow entry for that tool name. Available tool names: read, edit, grep, glob, exec You can also auto-approve MCP tools:

allowed-tools:
  - read
  - mcp__github__list_issues
  - mcp__github__create_issue

allowed-tools is not a restriction. Tools that are not listed remain available to the skill and go through the normal permission checks (prompting the user, or running without a prompt if the session’s permissions already allow them). Omitting allowed-tools changes nothing about which tools the skill can use — it only means no tool is pre-approved.To actually prevent a skill from using a tool:

For inline skills, add the tool name to permissions.deny (see Permissions).
For subagent skills, define a custom subagent profile with allowed-tools and run the skill with agent: <profile>. On a subagent profile, allowed-tools restricts the tool set; on a skill, it does not.

Examples

Code Review Skill

---
name: review
description: Review staged changes for issues
allowed-tools:
  - read
  - grep
  - glob
  - exec
permissions:
  allow:
    - Exec(git diff)
    - Exec(git log)
---

Run `git diff --staged` and review the changes for quality issues.

Evaluate:
1. **Correctness** — Any logic errors or edge cases?
2. **Security** — Any vulnerabilities introduced?
3. **Performance** — Any obvious inefficiencies?
4. **Style** — Consistent with the codebase?

Provide a summary with specific line references.

Component Generator

---
name: component
description: Generate a React component from a description
argument-hint: "<ComponentName>"
allowed-tools:
  - read
  - edit
  - grep
  - glob
model: sonnet
permissions:
  allow:
    - Write(src/components/**)
---

Create a new React component using the name the user provides:

1. Check existing components in src/components/ for style conventions
2. Create the component file at src/components/<ComponentName>/<ComponentName>.tsx
3. Create a barrel export at src/components/<ComponentName>/index.ts
4. Add basic tests at src/components/<ComponentName>/<ComponentName>.test.tsx
5. Follow the patterns you find in existing components

Deployment Checklist

---
name: deploy
description: Run through the deployment checklist
triggers:
  - user
allowed-tools:
  - read
  - exec
  - grep
permissions:
  allow:
    - Exec(npm run)
    - Exec(git)
---

Run through the deployment checklist:

1. Run the test suite: `npm run test`
2. Run the linter: `npm run lint`
3. Check for uncommitted changes: `git status`
4. Verify the build: `npm run build`
5. Show the current branch and last commit

Report the status of each step. If anything fails, stop and explain the issue.

Search Expert

---
name: find
description: Find relevant code across the project
argument-hint: "<what to find>"
allowed-tools:
  - read
  - grep
  - glob
triggers:
  - user
  - model
---

Search the codebase thoroughly for what the user asked about.

Use grep for content search and glob for file discovery.
Provide relevant file paths and code snippets.
Explain how the pieces connect.

Tips

Keep prompts focused

A skill should do one thing well. Create multiple skills rather than one mega-skill.

Include examples

Show the agent what good output looks like in your prompt.

Deny what a skill must not do

Use permissions.deny (or a custom subagent profile) to block tools. allowed-tools only skips prompts.

Test with /skill-name

Invoke your skill and iterate on the prompt until the output is what you want.

Getting Started

Editor Integrations

Extensibility

Enterprise

Reference

Changelog

File Structure

Frontmatter Reference

All Frontmatter Fields

Model Override

Running Skills as Subagents

`subagent: true`

`agent: <profile>`

Orchestrating Subagents Using Skills

Prompt Content

Permissions

Auto-Approved Tools

Examples

Code Review Skill

Component Generator

Deployment Checklist

Search Expert

Tips

Keep prompts focused

Include examples

Deny what a skill must not do

Test with /skill-name

​File Structure

​Frontmatter Reference

​All Frontmatter Fields

​Model Override

​Running Skills as Subagents

​subagent: true

​agent: <profile>

​Orchestrating Subagents Using Skills

​Prompt Content

​Permissions

​Auto-Approved Tools

​Examples

​Code Review Skill

​Component Generator

​Deployment Checklist

​Search Expert

​Tips

Keep prompts focused

Include examples

Deny what a skill must not do

Test with /skill-name

File Structure

Frontmatter Reference

All Frontmatter Fields

Model Override

Running Skills as Subagents

`subagent: true`

`agent: <profile>`

Orchestrating Subagents Using Skills

Prompt Content

Permissions

Auto-Approved Tools

Examples

Code Review Skill

Component Generator

Deployment Checklist

Search Expert

Tips