Skill development and MCP integration
To let an agent use capabilities from your own systems, both sides need a shared interface contract. Skills define methods, and MCP provides the tooling interface. Together, they enable an agent to call external systems.
How it works
Skills and MCP solve two different problems. A skill carries the "how" — workflow steps, input requirements, output format, and failure handling. MCP carries the "what" — callable tools along with their parameters and return structures. A skill can declare in its body which MCP tools it depends on.
A skill consists of metadata and execution content. The name and description are parsed by the platform and serve as the basis for the agent to decide when to invoke the skill. The SKILL.md body is the working instruction the agent reads at execution time. Lightweight skills are written directly on the page. Skills that include scripts and assets are uploaded as a zip package, and the metadata is parsed from the frontmatter of the SKILL.md file inside the package.
MCP services are registered as connectors. After registration, a connectivity and capability handshake is completed through probing, the tool list is retrieved, and the connector is then associated with an agent. Remote services use streamable_http or sse transport. Services that require a local process use stdio.
Usage notes
The ownership of a skill is determined at creation and cannot be changed afterward. A skill visible only to yourself can be used only by you. A skill visible to all members within the tenant can be mounted by members of the same tenant.
MCP service connectors are visible only to yourself by default. To share a connector with your team, select tenant-wide visibility when you create it.
stdio-type MCP services run in a sandboxed environment without network access and can use only the libraries and commands available in the runtime environment. Logic that installs dependencies over the network at startup cannot be executed in this environment.
Organize your working method
A workflow that has not been validated through real tasks is not suitable for direct encapsulation as a skill. Only methods that have been consistently reproduced should be encapsulated.
Start by manually completing several instances of the target task in conversations and recording the actual steps each time. The parts that repeat consistently across instances form the main workflow of the skill, and the exceptions that occurred form the failure handling branches. If the instances vary too much, the task boundary is not yet clear. In this case, split the task first and then encapsulate.
A skill addresses only one type of task. Daily report generation and anomaly investigation are two different types of tasks. Merging them into a single skill makes the description ambiguous, which reduces the agent's selection accuracy.
Write skill content
The skill content is the sole basis for agent execution. Write it as an "operation guide for a colleague taking over," not as a feature introduction.
-
Choose a name. The name can contain only lowercase letters, digits, underscores, and hyphens. It must start with a letter, be no longer than 64 characters, and must not use the reserved words
anthropicandclaude. -
Write a description that directly states what the skill does and when to use it. This field determines whether the agent can select the skill at the right moment.
-
Organize the execution workflow step by step in the body, annotating the purpose and checkpoint of each step.
-
Declare each input explicitly: its meaning, whether it is required, and value constraints. When a value is missing, the agent must proactively ask instead of guessing. Include this requirement in the body.
-
Define a fixed output structure and format so that downstream tasks and artifact management can consume the output. See artifact management for details.
-
Declare the MCP tools and data connections that the skill depends on, so that users can verify their environment.
-
State the boundaries clearly: inapplicable scenarios and known limitations.
-
Define a failure handling strategy, including retry conditions, fallback approaches, and termination conditions. Also specify what to explain to the user upon failure.
Register and verify a skill
A registered skill participates in real execution. Covering diverse input types during verification is more important than the number of verification runs.
-
Create a skill on the Skills page of the workbench. For a lightweight skill, select manual authoring and directly fill in the name, description, and SKILL.md body. For a skill that includes scripts or assets, select zip package upload. The metadata is parsed from the SKILL.md inside the package. A single file in the zip package cannot exceed 50 MB.
-
Set the ownership. During personal verification, keep the skill visible only to yourself. After verification passes, create a tenant-wide visible version for team use. Ownership cannot be changed after creation.
-
Associate the skill with a test agent.
-
Run the skill once with normal inputs and verify that the output conforms to the declared format.
-
Run the skill once with missing inputs and verify that the agent proactively asks for the values instead of assuming them.
-
Run the skill once with abnormal inputs and verify that it terminates according to the failure handling strategy and provides an understandable explanation.
-
After all three types of test cases pass, let the production agent mount the skill.
Content changes are submitted by publishing a new version. Changes affect all agents and scheduled tasks that have mounted the skill. Before publishing, perform regression verification in a test session. See the Skill Management API for details.
Integrate an MCP service
The number of tools directly affects the agent's selection accuracy and invocation cost. Determine the scope of integration based on actual task needs. Do not integrate all tools first and then filter.
-
Identify the tasks the target agent needs to complete, and determine the required tool scope accordingly.
-
Determine the integration method. Use streamable_http or sse for remote services. Use stdio for services that require a local process.
-
Register a connector on the Connectors page of the workbench and select MCP Service as the service type. For a remote service, enter the URL. The URL must use HTTPS and must not contain a username or password. For a stdio service, enter the executable, command arguments, environment variables, and custom request headers.
-
Authentication generally does not require manual configuration. The system automatically discovers the authentication service from the MCP address, attempts dynamic registration when no Client ID is provided, and credentials are managed by the server. Specify the OAuth configuration only when you need to override the default behavior.
-
After saving, run a probe to verify connectivity and capability handshake, and check whether the retrieved tool list covers the capabilities required by your tasks.
-
Perform an actual call in a conversation. The probe only verifies the handshake. Whether the authorization scope, parameter conventions, and returned content are usable can only be confirmed through an actual call.
-
After verification passes, associate the connector with the target agent. For details, see Connector management.
Wrap a self-built system as an MCP service
Whether an agent can correctly use a tool depends on how clearly the tool description is written, not on how completely the tool itself is implemented.
When implementing a server according to the MCP specification, declare the name, description, input parameters, and output structure for each tool. Clearly describe the purpose, applicable conditions, and limitations in the description, as this is the only basis on which the agent selects tools. Keep tool granularity at the level of a single-step operation. A tool that handles a multi-step process makes failure diagnosis difficult.
The server verifies the caller identity on its own. Credentials passed from ADA are configured with the least privilege. Errors are returned as structured information that describes the failure reason and suggested actions. The agent uses this information to present the error in the conversation and adjust accordingly.
Mark the impact scope in the declaration for write-operation tools, and keep per-call confirmation enabled on the ADA side instead of setting them to always allow. For details, see Approval and manual confirmation.
Apply to production environments
Changes to skills and tools are equivalent to behavioral changes. The consumers are not notified of changes, and scheduled tasks reflect new content only at the next trigger. Therefore, schedule changes outside task execution windows.
When tools are added, undeployed, or have parameter adjustments, update the tool descriptions accordingly. When a description is inconsistent with the actual behavior, the agent selects tools based on the description, and the failure cause often falls on call parameters, making it hard to diagnose.
Configure health checks and alerts for MCP services in the production environment. When a connection error occurs, the task logs provide the failure reason, but the time to detection depends on the task trigger time.
Manage credentials and access policies for MCP services independently and rotate them periodically. When the same service is associated with multiple agents, a credential change affects all associated agents.
For skills that depend on external data or tools, specify the prerequisite configurations in the skill body. If the configuration is missing in the user's environment, the call fails during execution rather than reporting an error at mount time.
Quotas and limits
|
Item |
Description |
|
Skill name |
Lowercase letters, digits, underscores, or hyphens. Must start with a letter and cannot exceed 64 characters. |
|
Reserved words |
|
|
zip skill package |
A single file cannot exceed 50 MB. |
|
Ownership |
Cannot be modified after creation. |
|
MCP address |
Must use HTTPS and must not carry usernames or passwords in the URL. |
|
stdio runtime environment |
No network sandbox. Only the libraries and commands provided by the environment can be used. |
|
MCP connector ownership |
Visible only to the creator by default. |
FAQ
-
Q: What is the boundary between skills and system prompts?
A: System prompts define the responsibilities and behavioral boundaries of the agent, while skills define the execution methods for specific tasks. Stable role definitions go in system prompts, and reusable task workflows are encapsulated as skills.
-
Q: Can a skill call other skills?
A: A skill can declare dependencies on other skills and MCP tools in its body, and the agent calls them as needed during execution. An excessively deep dependency chain makes individual skills impossible to verify independently, so keep the hierarchy under control.
-
Q: The probe passed but the call failed?
A: The probe only verifies the handshake. Check in order whether the call credentials have the required permissions for the target operation, whether the request parameters are complete, and whether the external service returns the expected business results.
-
Q: Can a single MCP service be associated with multiple agents?
A: Yes. The same connector can be associated with multiple agents, each using its tools as needed. Whether other members' agents can associate with a connector depends on ownership restrictions. MCP service connectors are visible only to the creator by default.
-
Q: How many tools should be integrated?
A: This depends on the actual requirements of the target task. Too many tools increase the agent's selection burden and invocation costs. Additionally, selecting incorrect tools makes it difficult to identify the cause of failures.