← Guides · 日本語 · Português · 中文

Updated 2026-11-19

On this page
  1. Why skills are the layer that matters now
  2. Step 1 — Where skills live
  3. Step 2 — The SKILL.md contract
  4. Step 3 — Invocation paths
  5. Step 4 — Growing the library
  6. Walkthrough — a repo skill invoked for real, on Devin CLI v3000.14 (swe-2-flash-medium)
  7. Verify it
  8. Pitfalls
  9. Knowledge check
  10. Sources

Guide 17 — Skills & plugins: the post-playbook packaging layer

Goal: encode your org's repeatable procedures as SKILL.md files so every session and Bot follows them — and package/share them across repos with plugins. Level: intermediate · the layer that replaced playbooks Sources: docs.devin.ai/product-guides/skills · release notes · complements Guide 9

Why skills are the layer that matters now

Playbooks are moving to Skills: accounts migrate one at a time, and new accounts (from Oct 24, 2026) get Skills only — each playbook becomes a skill with the same org/enterprise scope. Skills also follow the open Agent Skills standard, so the same files work across other coding agents. Everything you knew about writing playbooks transfers; the file format and discovery model are what changed.

Artifact Lives in Best for
Knowledge Customize page / repo notes Standing context — facts Devin can't know
Bot instructions The Bot Job law for one employee
Skill SKILL.md in repo, or a plugin A named, invocable procedure
Rule Plugin Always-on constraint ("never force-push")
Hook Plugin Deterministic enforcement around tool calls

Step 1 — Where skills live

Two discovery sources, both automatic:

  1. Repositories — commit SKILL.md files; Devin scans all ten vendor paths in every connected repo: .agents/skills/ (recommended), .devin/skills/, .github/skills/, .claude/skills/, .cognition/skills/, .windsurf/skills/, .cursor/skills/, .codex/skills/, .codeium/skills/, .kiro/skills/. Repo skills are branch-versioned — a mid-session clone is scanned when it finishes.
  2. Plugins — a plugin bundles skills + rules + MCP servers + hooks, installed at personal, organization, or enterprise scope; its skills are in context before any repo clones.

Step 2 — The SKILL.md contract

---
name: test-before-pr
description: Run the dev server and verify pages before any frontend PR.
argument-hint: <environment>
triggers: ["user"]
allowed-tools: read, grep, glob
permissions:
  allow: ["Exec(npm run *)"]
---

## Setup
1. `docker-compose up -d postgres` && `npm run dev`
## Verify
1. Open each page touched by the diff
2. Screenshot at 1280px and 375px

Frontmatter that changes behavior:

Step 3 — Invocation paths

Step 4 — Growing the library

Walkthrough — a repo skill invoked for real, on Devin CLI v3000.14 (swe-2-flash-medium)

Step 3's explicit path, end-to-end: a coverage-check skill committed at .devin/skills/coverage-check/SKILL.md in a demo repo, then invoked in a fresh session. Discovery works exactly as documented — typing / surfaced the skill by name, with its description as the autocomplete blurb.

Video (60 s, silent): SKILL.md → slash autocomplete → Invoked skill coverage-check → approval → report.

The skill's report — per-function coverage tables for app.py and orders.py

1. The skill on disk — frontmatter name/description, then a numbered procedure 1. The skill on disk — .devin/skills/coverage-check/SKILL.md: frontmatter name/description, then a numbered procedure

2. Typing / lists the skill — name + description are the autocomplete entry 2. Typing / lists the skill — name + description are exactly what discovery loads

3. Invoked skill coverage-check — the first command already waits on an Allow 3. Invoked skill coverage-check — its first command still needs an Allow

4. The procedure runs verbatim — unittest, then read every source and test file 4. The procedure runs verbatim — python3 -m unittest -v, then reads app.py, orders.py, both test files

5. Result: full coverage — per-function tables naming every branch; no files modified, no commits 5. Result: full coverage — every branch accounted for, exactly the report the SKILL.md asked for

Verify it

Pitfalls

Knowledge check

  1. Why does description matter more than the skill body? (It's the only text loaded at session start — it drives auto-invocation; the body loads only after the skill is chosen.)
  2. When should a procedure be a plugin skill rather than a repo skill? (When every repo/session in a scope needs it — plugins load before cloning and can't drift per-branch.)
  3. How do you make a skill safe for destructive steps? (triggers:["user"] for explicit-only invocation, plus permissions.ask on the dangerous tool matchers.)

Sources