> ## 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. # 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](#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](#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](#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](#mcp-servers)** | Give the agent tools from external services | Configured per project or per user | Issue trackers, design tools, internal APIs | | **[Hooks](#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](https://cli.devin.ai), 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: ```markdown theme={null} # 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: ```markdown theme={null} --- 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](https://docs.devin.ai/cli/extensibility/rules.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: ```markdown theme={null} --- 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//` (`.agents/skills/` and the legacy `.windsurf/skills/` are also read) | Current workspace only. Committed with your repo. | | Global | `~/.config/devin/skills//` (`~/.agents/skills/` is also read) | All workspaces on your machine. Not committed. | | Plugin | Inside an installed [plugin](#plugins) | Wherever the plugin is installed. | See the [Devin CLI skills documentation](https://docs.devin.ai/cli/extensibility/skills/overview.md) for skill triggers, permissions, and third-party skills, and [creating skills](https://docs.devin.ai/cli/extensibility/skills/creating-skills.md) 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 `/:` commands. See [plugins](https://docs.devin.ai/cli/extensibility/plugins/overview.md) for the plugin format, the `devin plugins` commands, and governance. > [!WARNING] > > **Plugins** here means Devin *agent* plugins. They are unrelated to [Windsurf Plugins](https://docs.devin.ai/windsurf/plugins/getting-started.md), which bring Devin to JetBrains, VS Code, and other editors, or to the [editor extensions](https://docs.devin.ai/desktop/recommended-extensions.md) 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](https://modelcontextprotocol.io/) 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](https://modelcontextprotocol.io/). ### Configuration MCP servers are configured in [config files](https://docs.devin.ai/cli/extensibility/mcp/configuration.md) 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](https://docs.devin.ai/desktop/devin-local/permissions.md#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: ```json theme={null} { "PreToolUse": [ { "matcher": "exec", "hooks": [ { "type": "command", "command": "./scripts/check-command.sh" } ] } ] } ``` Hooks neither load nor run while a workspace is open in [Restricted Mode](https://docs.devin.ai/desktop/devin-local/overview.md#restricted-mode). See [hooks](https://docs.devin.ai/cli/extensibility/hooks/overview.md) for the hook events, the configuration format, exit codes, and examples. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.