> ## Documentation Index > Fetch the complete documentation index at: https://docs.devin.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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](https://agentskills.io/specification), so the same skill files work across multiple AI coding tools. Place skill files at `.agents/skills//SKILL.md` in your repository. Devin automatically discovers them across all your connected repositories. See the [Agent Skills specification](https://agentskills.io/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: ```markdown theme={null} --- 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: ```markdown theme={null} --- name: deploy description: Deploy the app to a target environment and run smoke tests. argument-hint: 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: ```markdown theme={null} --- name: investigate description: Research a part of the codebase and produce a written summary with file references. allowed-tools: Read, Grep, ListDir argument-hint: --- ## 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.md` **(recommended)** * `.github/skills//SKILL.md` * `.claude/skills//SKILL.md` * `.cursor/skills//SKILL.md` * `.codex/skills//SKILL.md` * `.cognition/skills//SKILL.md` * `.windsurf/skills//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](https://agentskills.io/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](/product-guides/creating-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](https://agentskills.io/specification) — the open standard for `SKILL.md` file format, frontmatter fields, and directory structure * [Knowledge](/product-guides/knowledge) — for contextual tips and facts (not step-by-step procedures) * [Playbooks](/product-guides/creating-playbooks) — for reusable prompt templates attached to sessions