Claude Managed Agents Guide: Reusable Skills and Context Budgets
Answer in brief
Claude Managed Agents supports reusable, filesystem-based skills that are attached to an agent or discovered from a mounted GitHub repository. Skills are selected automatically when relevant, while each added skill uses some session context and a larger skill set can increase sandbox startup time.
Key facts at a glance
| Product / model | Current ID or version | Use case | Evidence |
|---|---|---|---|
| claude-managed-agents | Official source does not specify a selectable model ID | Confirm the current product surface | Official source |
Failure modes and verification
| Failure mode | Verification action |
|---|---|
| Stale model or version reference | Compare the model name and ID with the official source before release. |
| Unstructured or incomplete output | Validate the response against the documented contract and a deterministic fixture. |
| Unverified factual claim | Keep the claim qualified or remove the claim when the official source does not support it. |
FAQ
How are reusable skills added to Claude Managed Agents?
Add an Anthropic or custom skill to the agent’s skills array, or mount a GitHub repository containing correctly structured repository skills. The supported paths are described in the official skills documentation.
Do users need to activate a skill manually?
No. Claude Managed Agents automatically invokes an available skill when it is relevant to the task. For repository skills, discovery occurs at session start and the matching files are read when needed, as documented in the official source.
Where must a repository skill be stored for startup discovery?
It must be stored at .claude/skills/<skill-name>/SKILL.md under the mounted repository root, exactly one skill directory below .claude/skills. Other locations are not announced at startup, although a skill in another subtree may surface later if the agent reads that subtree. See the official layout rules.
What happens if the read tool is disabled?
Repository skills are not loaded through the startup discovery mechanism because discovery depends on the agent toolset’s read tool. This limitation is stated in the official documentation.
What is the context-window cost of a skill?
Each added skill uses a modest amount of the session’s context window for instructions and metadata. The official source does not provide an exact token amount and also warns that making more skills available increases sandbox startup time.
How many skills can one session support?
A session supports up to 500 skills, counted as the deduplicated set across all agents participating in that session. The limit and counting method are documented on the official skills page.
Why should repository skills be reviewed before mounting?
A mounted repository is part of the agent’s trust boundary, and its skills are loaded at session start without a separate review step. Review .claude/skills and mount only trusted repositories, especially when powerful session tools are enabled. See the official security guidance.
Sources and freshness
- Official source
- Last verified: 2026-08-27
Extended guide
Claude Managed Agents lets teams package workflows, context, and best practices as reusable, filesystem-based skills. Skills can be attached through agent configuration or discovered from a GitHub repository mounted on the session.
Evidence and scope
This entry was verified against the official Claude Platform documentation as of 2026-08-27. That page documents skill creation, attachment, repository discovery, automatic activation, context-window cost, startup impact, and repository trust considerations.
Delivery and activation paths
| Path | Configuration | Activation | Important constraint |
|---|---|---|---|
| Anthropic pre-built skill | Add type: anthropic and a short skill_id, such as xlsx, to the agent’s skills array. |
The agent automatically invokes the skill when it is relevant to the task. | Pre-built skills are already available in every workspace and do not need to be uploaded. |
| Workspace custom skill | Upload a directory containing SKILL.md and optional supporting files, then attach the returned skill_* ID with type: custom. |
The agent automatically invokes the skill when the task matches its purpose. | Skill bundles are uploaded directly to the Skills API, not through the Files API. |
| Repository skill | Mount a GitHub repository through the session’s github_repository resource. |
At session start, discovered skill metadata becomes available to the agent. The agent reads the matching SKILL.md, scripts, and resources when relevant. |
Startup discovery requires the read tool and is supported only in cloud sandboxes. |
Configuration procedure
-
Choose the delivery path. Attach a pre-built or workspace custom skill when it should be part of the agent’s explicit configuration. Use a repository skill when the instructions and supporting resources should live alongside the codebase. Both paths provide automatic, relevance-based activation.
-
Prepare the skill. A custom skill is a directory containing
SKILL.mdplus any supporting files. It can be uploaded as a zip archive or as individual files, and creation returns theskill_*identifier used in agent configuration. For repository discovery, place each skill at exactly.claude/skills/<skill-name>/SKILL.mdunder the repository root. -
Attach or mount the resource. Attached skills are added to the
skillsarray when the agent is created. The optionalversionfield can pin a specific version or uselatest; omitting it defaults tolatest. Repository skills require neither a separate upload nor an entry in the agent’sskillsarray. They become available when a session mounts the repository. -
Preserve repository discovery. Skills do not require a user-facing manual activation command. For repository skills, the default
readtool enables startup discovery and later access to the skill files. Ifreadis disabled, repository skills are not loaded through this discovery mechanism. -
Follow the exact startup layout. A bare
.claude/skills/SKILL.md, a deeply nested path such as.claude/skills/tools/code-review/SKILL.md, or a directory outside.claudeis not announced during startup. A.claude/skillsdirectory inside a package subdirectory is also excluded from startup discovery, although a skill there may still surface later if the agent reads that subtree. -
Control session overhead. Every added skill incurs a modest context-window cost because the session includes instructions and metadata that help the model decide when and how to use it. The documentation does not specify an exact token amount. A session supports up to 500 skills, calculated as the deduplicated set across all agents in that session. Making more skills available also increases sandbox startup time, so each agent should receive only the skills needed for its task.
Trust and API considerations
A mounted repository is part of the agent’s trust boundary. Malicious skill instructions may enter through a contributor change, a merged external pull request, or a compromised dependency path. Because the platform loads repository skills at session start without a separate review step, review .claude/skills before mounting repositories that accept outside contributions. Tools such as bash and web_fetch can extend the practical reach of those instructions.
Managed Agents API requests require the managed-agents-2026-04-01 beta header. Memory store endpoints use agent-memory-2026-07-22 instead, and the SDK selects the appropriate beta header automatically.
Deployment checklist
- Use
.claude/skills/<skill-name>/SKILL.mdfor every startup-discovered repository skill. - Keep
readenabled when repository discovery is required. - Review repository skills as agent instructions within the trust boundary.
- Attach or expose only task-relevant skills to limit context and startup overhead.
Model availability note: The official source does not specify a selectable model ID.
Evidence and freshness
Evidence level: Documentation-verified
AI-assisted editorial content; verify current product details against the linked official sources.
Last verified: