Configured Agent for Claude Code

Official Anthropic skill for configurable plugin settings and local state.

Configured Agent is Skill Road's unambiguous mapping of the Smithery slug configured-agent to Anthropic's official plugin-settings path in the claude-code repository. The catalog name follows the registry label, while the first-party source defines the technical identity. Anthropic documents a pattern there for Claude Code plugins that need project-specific settings and state stored in a file under .claude. The file uses the plugin name with a .local.md suffix, YAML frontmatter for structured values, and an optional Markdown body for additional context. This entry is therefore classified as a skill rather than a standalone agent, server, or executable plugin.

Purpose and scope

The pattern is intended for plugin maintainers, developers, and teams that need plugin behavior to be configurable per project. According to the provider, hooks, commands, and agents can read the file and consume expected configuration values. A missing document is a normal state. A plugin can then use safe defaults or skip an optional feature. This separation keeps shared plugin logic distinct from local preferences and prevents one workstation's state from silently becoming a team convention. The skill documents a file pattern; it does not install an extension and it does not grant additional permissions.

Structure and operation

Anthropic describes YAML frontmatter between two delimiter lines and a Markdown section for notes, task descriptions, or supporting context. Configuration may contain activation flags, modes, numbers, strings, and simple lists. A responsible implementation first checks whether the file exists, accepts only a defined schema, and validates every value before using it. Boolean values should be compared strictly, numeric values need meaningful bounds, and paths must be protected against unexpected targets and traversal. Successfully reading a file is not the same as approving a hook or script for execution.

Lifecycle and team boundaries

The file is designed for one project and local customization. According to the provider, it should normally stay out of Git, and matching .gitignore rules help prevent accidental sharing. Claude Code must be restarted after a settings change so hooks recognize the new configuration. The skill recommends using the CLAUDE_PLUGIN_ROOT variable for plugin-owned resources instead of hardcoded paths. Teams should document the schema, defaults, allowed values, runtime dependencies, and restart behavior in the plugin. Shared standards belong in versioned plugin files, not in local state files.

File Format and Reading

The settings live in a file following the pattern .claude/plugin-name.local.md in the project. It consists of YAML frontmatter between two lines with --- and free-form markdown below. Typical fields are booleans such as enabled: true, strings, numbers and lists. Hooks read the frontmatter in Bash with sed and first check whether the file exists. If it is missing, the hook exits without an error. The files belong in .gitignore (.claude/*.local.md). Changes only take effect after restarting Claude Code, because hooks cannot be swapped during a session.

Security and limitations

Settings files are inputs and may contain sensitive or ambiguous content. Secrets, tokens, and credentials do not belong in this file. Before activation, review hooks, shell scripts, network access, write operations, and environment variables separately. The frontmatter format grants no permissions and proves no trustworthiness. It also does not replace centralized secret management, code review, or defenses against prompt injection. Skill Road lists this as an external, verified Anthropic skill according to the provider sources and states no concrete prices. Check current Claude Code availability and terms for connected services with the provider.

Installation instructions

Step 1: What a Configured Agent for Claude Code is and why it is used

A Configured Agent in Claude Code refers to a custom subagent, a specialized AI assistant with its own system prompt, its own tool access, and its own permissions, set up for a specific type of task. According to Anthropic's official Claude Code documentation at code.claude.com, subagents exist to take on work that would otherwise flood the main conversation with search results, logs, or file contents that won't be needed again. The subagent does that work in its own isolated context window and returns only a summary to the main session at the end. This matters because Claude Code, as a coding agent, quickly runs up against the limits of the available context window on complex, multi-step tasks; a well-configured subagent keeps the main session lean while simultaneously being restricted to a narrower set of tools and rules, which lowers cost and improves result quality for recurring, clearly scoped tasks.

Step 2: Prerequisites

The prerequisite is an installed and working version of Claude Code, since subagents are purely a feature of that product. According to the documentation, a subagent is defined as a single file with YAML frontmatter in which at minimum the name and description fields must be set; all other fields such as tools, model, or permissionMode are optional. To reuse subagents across multiple projects, it is recommended to place them at the user level rather than the project level, which requires familiarity with Claude Code's directory structure. Anyone wanting to connect a subagent to its own MCP servers additionally needs a working MCP server configuration, and anyone wanting to use specific models like Haiku for cheaper subagents needs access to the corresponding Anthropic model quota.

Setting it up step by step

A new subagent is created by adding a file with YAML frontmatter in Claude Code's relevant skills or agents directory; according to the documentation, the filename does not have to match the name field, but it must not contain a colon, since that character is reserved for plugin-scoped identifiers. The first step is choosing the scope, i.e. whether the subagent should only be available for the current project or globally for the user. Next, a short, precise description is written, since Claude uses this description to decide when to delegate a task to the subagent; according to the provider, once the combined descriptions of all subagents exceed roughly 15,000 tokens, this noticeably consumes context and triggers a warning at startup. After that, the tool set can optionally be restricted via tools and disallowedTools, a model can be set via model, and a permission mode can be chosen via permissionMode if needed. Finally, the subagent can either be invoked automatically by Claude based on its description or addressed explicitly by the user.

Security and best practices

From a security standpoint, the most important lever is deliberately restricting tool access through the tools and disallowedTools fields, since a subagent inherits every tool available to subagents by default if nothing is specified. According to the documentation, an entry with a specifier, such as Bash(git push *), removes the entire associated tool rather than just the specified subcommand, which should be kept in mind when configuring one. The permissionMode field additionally lets a subagent run more strictly than the main session, for example in plan mode without execution rights. The provider also recommends limiting the maximum number of turns via maxTurns to avoid uncontrolled long runs, and using the omitClaudeMd field when a subagent should deliberately operate without project-specific CLAUDE.md rules because it already receives everything it needs through the delegation prompt.

A practical example and its limits

A typical example from the official documentation is a code-reviewer subagent that is given only read and analysis tools and automatically performs delegated reviews on every code change without having write access to the repository itself, or a database query validator that checks queries before they run. The limits are that subagents operate within a single session and are not suited to fully independent, parallel-running sessions; for that, the documentation points to separate concepts such as background agents or agent teams. In addition, every extra description consumes context right from Claude Code's startup, which means too large a number of subagents with lengthy descriptions can itself become a performance problem.

Free
Provider
Anthropic
License
Apache-2.0
Last reviewed
09.09.2026

Repository and documentation

Categories

Compatible with

Claude Code