Skills

Teach Devin reusable procedures by committing SKILL.md files to your repos

What are Skills?

Skills are SKILL.md files you commit to your repositories that teach Devin reusable procedures — any repeatable workflow you want Devin to follow consistently. Testing your app before opening a PR, deploying to an environment, investigating a codebase, scaffolding a new service — if you can write it as step-by-step instructions, you can turn it into a skill.

They follow the open Agent Skills standard, so the same skill files work across multiple AI coding tools.

Place skill files at .agents/skills/<skill-name>/SKILL.md in your repository. Devin automatically discovers them across all your connected repositories. See the Agent Skills specification for the full file format reference.

Why Skills Matter

Without skills, Devin has to figure out workflows from scratch every session. With skills, you define a procedure once and Devin follows it reliably every time. Skills are useful whenever you have a workflow that:

• Should be done the same way every time — testing checklists, deployment steps, review procedures
• Requires repo-specific knowledge — which services to start, what ports to use, which commands to run
• Benefits from dynamic context — pulling in git diffs, branch names, or environment info at invocation time

Devin Suggests Skills Automatically

Devin can automatically suggest skills for you. After Devin tests your application or learns something new about your setup during a session, it will suggest creating or updating a skill to capture that knowledge. You’ll see a suggestion in your session timeline with:

• A summary of what was learned (e.g. “how to start the backend with Docker”)
• The proposed SKILL.md file contents
• A “Create PR” button to commit the skill to your repo

Over time, Devin builds up a library of skills in your repo about how to run, test, and deploy your application.

Examples

Testing before opening a PR

A skill that tells Devin how to verify a Next.js app before creating a pull request:

---
name: test-before-pr
description: Run the local dev server and verify pages before opening any PR that touches frontend code.
---

## Setup

1. Install dependencies: `npm install`
2. Start the database: `docker-compose up -d postgres`
3. Run migrations: `npx prisma migrate dev`
4. Start the dev server: `npm run dev`
5. Wait for "Ready on http://localhost:3000"

## Verify

1. Read the git diff to identify which pages changed
2. Open each affected page in the browser
3. Check for: console errors, layout issues, broken links
4. Screenshot each page at desktop (1280px) and mobile (375px) widths

## Before Opening the PR

1. Run `npm run lint` and fix any issues
2. Run `npm test` and confirm all tests pass
3. Include screenshots in the PR description

Deploying to an environment

A skill that deploys the app using arguments for the target environment, with dynamic content injection:

---
name: deploy
description: Deploy the app to a target environment and run smoke tests.
argument-hint: <environment>
triggers: ["user"]
---

## Deploy

1. Make sure you are on the correct branch for this deploy
2. Run `./scripts/deploy.sh $0`
3. Wait for the deploy script to complete successfully

## Verify

1. Curl `https://$0.example.com/health` and confirm a 200 response
2. Run the smoke test suite: `npm run test:smoke -- --env=$0`
3. Report the deployment URL and test results

## Current context

- Branch: !`git branch --show-current`
- Last commit: !`git log --oneline -1`

Invoking with @skills:deploy staging substitutes staging for $ARGUMENTS and $0, and the !`command` blocks inject live git info. The triggers: ["user"] field ensures Devin only runs this skill when you explicitly ask for it — it won’t auto-activate.

Investigating a part of the codebase

A skill for guided code exploration that restricts Devin to read-only tools:

---
name: investigate
description: Research a part of the codebase and produce a written summary with file references.
allowed-tools: Read, Grep, ListDir
argument-hint: <topic or area to investigate>
---

## Research

1. Search the codebase for files related to: $ARGUMENTS
2. Read the most relevant files thoroughly
3. Trace the call chain and data flow

## Summarize

1. Write a summary of how $ARGUMENTS works
2. Include specific file paths and line numbers for every claim
3. Note any concerns, edge cases, or areas that need attention

The allowed-tools field restricts Devin to read-only operations — no editing, no shell commands. This is useful for exploration tasks where you want analysis without side effects.

Skill Discovery

Devin discovers skills from two sources, merged together at the start of every session:

1. Indexed repos — Devin’s backend indexes SKILL.md files across all repositories connected to your organization. These are available immediately when a session starts, before any repos are cloned.
2. Cloned repos — As repositories are cloned onto the session’s machine, Devin scans them for SKILL.md files on disk. Disk-scanned skills update or override any matching indexed skill from the same repo, ensuring Devin always uses the latest version on the branch being worked on.

When a repo clone completes mid-session, Devin automatically re-scans that repo so newly added or modified skills are picked up without restarting.

Supported Skill File Locations

Devin searches for SKILL.md files in all of the following directories:

• .agents/skills/<skill-name>/SKILL.md (recommended)
• .github/skills/<skill-name>/SKILL.md
• .claude/skills/<skill-name>/SKILL.md
• .cursor/skills/<skill-name>/SKILL.md
• .codex/skills/<skill-name>/SKILL.md
• .cognition/skills/<skill-name>/SKILL.md
• .windsurf/skills/<skill-name>/SKILL.md

All seven paths are scanned in every repo.

What Devin Loads from a Skill File

When a skill is discovered, Devin parses the YAML frontmatter (the --- block at the top) and extracts:

Field	Purpose
name	Identifies the skill. Falls back to the parent directory name if omitted.
description	Short summary shown in the skill list so Devin (and you) know what the skill does.
allowed-tools	Restricts which tools Devin can use while the skill is active.

Devin also supports these additional frontmatter fields beyond the standard spec:

Field	Purpose
argument-hint	Hint text shown alongside the skill name describing expected arguments.
triggers	Controls who can invoke the skill — ["user", "model"] by default. Set to ["user"] to prevent Devin from auto-activating it.

Everything after the frontmatter is the skill body — the step-by-step instructions Devin is prompted to follow when the skill is invoked.

See the Agent Skills specification for the full file format reference.

Dynamic content

In addition to the standard spec, Devin supports two kinds of dynamic content in the skill body that are processed at invocation time:

• $ARGUMENTS — replaced with the full arguments string passed when the skill is invoked (e.g. via @skills:deploy staging prod). You can also access individual arguments by index: $ARGUMENTS[0] or $0 for the first, $ARGUMENTS[1] or $1 for the second, etc. Arguments are split by whitespace.
• !`command` — the command is executed in the repo root and replaced with its stdout, letting skills include dynamic values like branch names or port numbers.

How Devin Uses Skills

At the start of every session, Devin sees a list of all available skills (name + description). When a skill is invoked, Devin reads the full SKILL.md file and injects its body into its current context as a system-level instruction. This means Devin actively follows the skill’s steps for the remainder of the task — it’s not just a reference, it directly guides Devin’s behavior.

Devin can use skills in several ways:

Automatic invocation

When Devin determines a skill is relevant to the current task, it invokes it automatically. For example, if you ask Devin to fix a bug in frontend code and there’s a test-before-pr skill, Devin will activate it before opening the PR. Set triggers: ["user"] in the frontmatter to prevent auto-invocation for skills you only want triggered explicitly.

Mention a skill in your prompt

You can tell Devin to use a specific skill by including @skills:skill-name in your message:

Fix the login bug on the /auth page @skills:test-before-pr

You can also pass arguments:

@skills:deploy staging

The arguments are substituted into the skill body wherever $ARGUMENTS, $ARGUMENTS[0], $1, etc. appear.

One active skill at a time

Devin can only have one skill active at a time. Invoking a new skill replaces the previous one. When active, Devin is prompted to follow the skill’s steps in order and complete each one before moving on.

Searching and listing

Devin can search for skills by keyword or directory if it needs to find the right one mid-session. You can also ask Devin to list available skills or reload them after you’ve pushed changes to a skill file.

Limitations

• Global / org-level skills — Today, skills live inside repositories. For org-wide skills, you can create a dedicated “skills” repo as a workaround. We’re exploring first-class support for org-level skills that apply across all repos.
• Composing multiple skills — Currently only one skill can be active at a time. We’re working on support for chaining and composing workflows.

Skills vs. Playbooks

Both skills and playbooks give Devin reusable instructions, but they work differently:

	Skills	Playbooks
Where they live	In your repo as SKILL.md files — version-controlled alongside your code	In the Devin web app — managed through the UI
How they’re triggered	Devin discovers and invokes them automatically, or you reference them with @skills:name in any prompt	Manually attached to a session when you start it
Scope	Scoped to a repo — Devin picks up the right skills based on which repos are relevant to the task	Org-wide — any team member can attach any playbook to any session
Auto-suggestion	Devin suggests new skills after testing your app or learning something new	Created manually by team members
Best for	Testing procedures, local dev setup, deployment checklists, repo-specific workflows	Reusable prompt templates, cross-repo task patterns, onboarding guides

Which should I use? If your instructions are tied to a specific repo — how to run it, test it, or deploy it — use a skill. If your instructions are general-purpose prompts that apply across repos or teams, use a playbook.

Learn More

• Agent Skills specification — the open standard for SKILL.md file format, frontmatter fields, and directory structure
• Knowledge — for contextual tips and facts (not step-by-step procedures)
• Playbooks — for reusable prompt templates attached to sessions