Devin Local Customizations

Extend the Devin Local agent in Devin Desktop with rules, skills, plugins, MCP servers, and hooks, and see what each session has loaded.

Devin Local offers several ways to customize how the agent works in your projects. Use this table to pick the right one:

Feature	What it does	How it’s activated	When to use it
Rules	Tell the agent how to behave (e.g. “use bun, not npm”)	Always on, or by trigger frontmatter	Coding conventions, style guides, project constraints
Skills	Multi-step procedures bundled with supporting files (scripts, templates)	Invoked by the model when relevant, or by you	Complex tasks where the agent needs reference files
Plugins	Installable bundles of skills, rules, hooks, MCP servers, and subagents	Installed once, shared across projects and teams	Distributing a set of customizations
MCP servers	Give the agent tools from external services	Configured per project or per user	Issue trackers, design tools, internal APIs
Hooks	Run shell commands or prompts on agent lifecycle events	Configured per project or per user	Policy enforcement, logging, formatters, notifications

Because Devin Local shares its agent harness with Devin CLI, every customization uses the Devin CLI format and discovery, and a customization you write for one works in the other.

Customize

The Customize page in the Agents window has tabs for Plugins, Skills, MCPs, Hooks, Rules, and Subagents. Each tab lists what the agent has loaded, along with what your repository, organization, and account offer.

You can open it by clicking Customize in the agent sidebar.

Rules

Rules are persistent instructions that shape how the agent behaves in your project. They are injected into the agent’s context at the start of every session, which keeps behavior consistent across your team.

Common uses for rules include coding standards, architectural guidelines, preferred libraries, testing conventions, and project-specific constraints.

AGENTS.md

The simplest way to add rules is an AGENTS.md file at your project root. It uses plain Markdown with no frontmatter:

# Project Rules

- Use TypeScript for all new files
- Follow the existing patterns in src/components/
- Always run `npm run lint` before committing
- Use pnpm, not npm or yarn

AGENTS.md, AGENTS.local.md (for personal rules you keep out of version control), and AGENT.md are all read as always-on rules. The agent reads them at the workspace root and in each directory between the workspace root and the directory it is working in, so an AGENTS.md in a subdirectory gives directory-specific guidance.

Rule files

For more control, put one rule per file in .devin/rules/*.md. Each file can declare when it applies with trigger frontmatter:

---
trigger: glob
globs: "**/*.test.ts"
---

All test files must use `describe`/`it` blocks and mock external API calls.

trigger: value	When the rule reaches the agent
always_on	Every session
glob	When the agent works with files matching globs
model_decision	When the agent decides the rule’s description is relevant
manual	Only when you invoke it

.devin/global_rules.md is a single always-on file. Place the same files in your home directory (~/.devin/rules/*.md, ~/.devin/global_rules.md) to apply them to every project.

The legacy .windsurf/rules/*.md, .windsurf/global_rules.md, and .windsurfrules files are imported by default. Rule files in both .devin/rules/ and .windsurf/rules/ load; when both global_rules.md files exist, only .devin/global_rules.md loads. See rules and AGENTS.md for the full file list, the import settings, and rules from other tools.

Best practices

• Keep rules short and specific. Rules are in the context of every session, so they cost tokens on every message.
• Prefer a skill for anything the agent needs only sometimes, and use a rule to point the agent at the skills it should use in particular scenarios.
• Format rules as bullet points, numbered lists, and Markdown headers. These are easier to follow than a long paragraph.
• Skip generic rules such as “write good code”.

Skills

The hardest engineering tasks often take more than good prompts. They might require reference scripts, templates, checklists, and other supporting files. Skills let you bundle all of these together into folders that the agent can invoke.

Skills use progressive disclosure: only the skill’s name and description are shown to the model by default. The full SKILL.md content and supporting files are loaded only when the agent decides to invoke the skill, or when you invoke it. This keeps your context window lean even with many skills defined.

Creating a skill

Create a directory with a SKILL.md file whose YAML frontmatter names and describes the skill:

---
name: deploy-to-production
description: Guides the deployment process to production with safety checks
---

## Pre-deployment Checklist
1. Run all tests
2. Check for uncommitted changes
3. Verify environment variables

## Deployment Steps
Follow these steps to deploy safely...

• name: Unique identifier for the skill (lowercase letters, numbers, and hyphens). Used to invoke it.
• description: Brief explanation shown to the model to help it decide when to invoke the skill. Be specific about what the skill does and when to use it.

Place supporting files in the skill folder alongside SKILL.md. They become available to the agent when the skill is invoked:

.devin/skills/deploy-to-production/
├── SKILL.md
├── deployment-checklist.md
├── rollback-procedure.md
└── config-template.yaml

Invoking skills

When your request matches a skill’s description, the agent invokes the skill automatically and follows its instructions. You can also invoke a skill by name with /skill-name to make sure it is used.

Skill scopes

Scope	Location	Availability
Workspace	.devin/skills/<name>/ (.agents/skills/ and the legacy .windsurf/skills/ are also read)	Current workspace only. Committed with your repo.
Global	~/.config/devin/skills/<name>/ (~/.agents/skills/ is also read)	All workspaces on your machine. Not committed.
Plugin	Inside an installed plugin	Wherever the plugin is installed.

See the Devin CLI skills documentation for skill triggers, permissions, and third-party skills, and creating skills for authoring guidance.

Plugins

Plugins are installable bundles that contribute skills, rules, hooks, MCP servers, and subagents to the agent. Install a plugin from a GitHub repository, a git URL, a subfolder of a repository, or a local folder; its skills become available as /<plugin>:<skill> commands. See plugins for the plugin format, the devin plugins commands, and governance.

Plugins here means Devin agent plugins. They are unrelated to Windsurf Plugins, which bring Devin to JetBrains, VS Code, and other editors, or to the editor extensions you install inside Devin Desktop — both of those extend the IDE rather than the agent.

MCP servers

MCP (Model Context Protocol) is a protocol that lets the agent use tools from external services such as GitHub, databases, and issue trackers. See the official MCP docs for more information.

Installing MCP servers

Open the Customize page from the Agents window and click MCPs. Pick the scope with the Install MCPs for selector at the top, for example This computer.

• This computer lists the servers your local agent loads for the folders open in the window. Toggle a server on or off, open its config file, or refresh the list.
• Available lists the servers from your MCP registries. Click Install on a server to add it.

Enterprise admins manage registries in team settings under MCP & ACP. The MCP registry tab has a toggle that allows servers matching a registry entry in addition to the MCP allowlist, and a Registry setting (Configure) for the registry URLs. When several registries are configured, Devin Desktop takes the union of all of them. Custom registries must follow the official MCP registry schema.

Configuration

MCP servers are configured in config files on your local machine. The file location is determined by the scope:

Scope	Location	Shared with team?
Project	.devin/config.json	Yes (checked into version control)
Local override	.devin/config.local.json	No (gitignored)
User	~/.config/devin/config.json	No

Devin Local supports the stdio, Streamable HTTP, and SSE transports, and OAuth for each.

Permissions

By default the agent prompts for approval before calling any MCP tool. See MCP permissions for how to allow a tool or a server, and how admins can default-allow trusted integrations.

Re-authentication

When a server’s stored OAuth credentials expire, it shows a Needs auth state in the This computer list, on its Available card, and on the server detail page.

Click Authenticate to clear the stored credentials and re-run the browser authorization flow.

Hooks

Hooks run custom logic at events in the agent’s lifecycle, such as before a tool call. Each hook is a shell command or an LLM prompt. Use hooks to enforce policies, add context, log actions, modify permissions, or integrate with external systems.

Hooks are configured in .devin/hooks.v1.json in your project or at the user level. For example, this hook runs a script before every shell command and can block the command:

{
  "PreToolUse": [
    {
      "matcher": "exec",
      "hooks": [
        {
          "type": "command",
          "command": "./scripts/check-command.sh"
        }
      ]
    }
  ]
}

Hooks neither load nor run while a workspace is open in Restricted Mode.

See hooks for the hook events, the configuration format, exit codes, and examples.