Skip to main content
Glama

Attach a skill to an agent

attach_skill
Idempotent

Attach a skill to an agent so the agent can use it. Give skill as org: or a bare name for a skill the organization published. The agent always follows the skill's latest version, so a skill with a version pin such as @v2 is refused before anything changes; give the ref without the pin. An org skill must already exist and be published (create_service with kind skill, then publish_skill), except a built-in such as governance or security: when the organization has published no skill of that name, the agent holds Valet's default, follows it, and moves to the organization's own skill once one is published. Give catalog: for a skill from Valet's curated catalog: it installs a copy into the organization, or reuses the copy installed before, and attaches it at its latest version. A catalog skill whose name the organization's own skill holds is refused. The agent is rebuilt so the change takes effect. A skill that is already attached answers that nothing changed, without a rebuild; one whose name another attached skill holds is refused with nothing changed. Skills attach to agents only. Returns the agent, the skill's name, its source (org, or default for a built-in's Valet default), the latest version it follows, and whether it was already attached. Requires connecting a Valet account.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "name": "<name>",
      "skill": "<skill>"
    },
    "name": "attach_skill"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameYesThe agent's name, as list_services shows it: the agent to attach the skill to.
skillYesThe skill to attach, as a ref. org:<name> or a bare name picks an organization skill; catalog:<name> installs a catalog skill and attaches it. The agent follows the latest version, so a ref with a @v<N> pin is refused.
org_nameNoThe Valet organization the agent belongs to. Omit to use the organization the account joined first.

Output Schema

NameRequiredDescriptionDefault
orgYesName of the Valet organization the call acted in.
kindYesKind of the service the skill attaches to. Always agent: skills attach to agents only.
nameYesName of the agent.
skillYesThe skill's own name.
sourceYesorg for an organization skill, default for a built-in whose Valet default the agent holds because the organization has published no skill of that name.
latest_versionNoThe skill's newest version, which the agent follows. Absent when the skill has no version, as a default has none.
already_attachedNoTrue when the skill was already on the agent and nothing changed. Absent otherwise.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / skill / description
      Previous value: -"org:<name> or a bare name for an organization skill, or catalog:<name> to install and attach a catalog skill. The agent follows the latest version, so a ref with a @v<N> pin is refused."New value: +"The skill to attach, as a ref. org:<name> or a bare name picks an organization skill; catalog:<name> installs a catalog skill and attaches it. The agent follows the latest version, so a ref with a @v<N> pin is refused."
  2. Changed2 schema fields changed
    • changedInput schema / properties / skill / description
      Previous value: -"org:<name> or a bare name for an organization skill, or catalog:<name> to install and attach a catalog skill. The agent follows the latest version; a @v<N> pin is ignored."New value: +"org:<name> or a bare name for an organization skill, or catalog:<name> to install and attach a catalog skill. The agent follows the latest version, so a ref with a @v<N> pin is refused."
    • removedOutput schema / properties / pin_ignored
      Removed value: -{
      -  "description": "True when the skill you gave carried a @v<N> version pin. Pins are retired, so the agent follows the latest version anyway. Absent otherwise.",
      -  "type": "boolean"
      -}
  3. Changed8 schema fields changed
    • changedInput schema / properties / name / description
      Previous value: -"The agent's name."New value: +"The agent's name, as list_services shows it: the agent to attach the skill to."
    • changedOutput schema / properties / already_attached / description
      Previous value: -"True when attach_skill found the skill already on the agent and changed nothing."New value: +"True when the skill was already on the agent and nothing changed. Absent otherwise."
    • changedOutput schema / properties / latest_version / description
      Previous value: -"The skill's newest version, which the agent follows. Set by attach_skill; absent when the skill has no version, as a default has none."New value: +"The skill's newest version, which the agent follows. Absent when the skill has no version, as a default has none."
    • removedOutput schema / properties / not_attached
      Removed value: -{
      -  "description": "True when detach_skill found the skill not attached and changed nothing.",
      -  "type": "boolean"
      -}
    • changedOutput schema / properties / pin_ignored / description
      Previous value: -"True when the skill you gave carried a @v<N> version pin. Pins are retired, so the agent follows the latest version anyway. Set by attach_skill."New value: +"True when the skill you gave carried a @v<N> version pin. Pins are retired, so the agent follows the latest version anyway. Absent otherwise."
    • changedOutput schema / properties / skill / description
      Previous value: -"Name of the skill. attach_skill reports the skill's own name; detach_skill repeats what you passed."New value: +"The skill's own name."
    • changedOutput schema / properties / source / description
      Previous value: -"Set by attach_skill: org for an organization skill, default for a built-in whose Valet default the agent holds because the organization has published no skill of that name. Absent from detach_skill."New value: +"org for an organization skill, default for a built-in whose Valet default the agent holds because the organization has published no skill of that name."
    • changedOutput schema / required
      Previous value: -[
      -  "org",
      -  "name",
      -  "kind",
      -  "skill"
      -]New value: +[
      +  "org",
      +  "name",
      +  "kind",
      +  "skill",
      +  "source"
      +]
  4. Changed11 schema fields changed
    • changedInput schema / properties / name / description
      Previous value: -"Required. The agent's name."New value: +"The agent's name."
    • changedInput schema / properties / skill / description
      Previous value: -"Required. org:<name> or a bare name for an organization skill, or catalog:<name> to install and attach a catalog skill. The agent follows the latest version; a @v<N> pin is ignored."New value: +"org:<name> or a bare name for an organization skill, or catalog:<name> to install and attach a catalog skill. The agent follows the latest version; a @v<N> pin is ignored."
    • addedOutput schema / properties / already_attached / description
      Added value: +"True when attach_skill found the skill already on the agent and changed nothing."
    • addedOutput schema / properties / kind / description
      Added value: +"Kind of the service the skill attaches to. Always agent: skills attach to agents only."
    • addedOutput schema / properties / latest_version / description
      Added value: +"The skill's newest version, which the agent follows. Set by attach_skill; absent when the skill has no version, as a default has none."
    • addedOutput schema / properties / name / description
      Added value: +"Name of the agent."
    • addedOutput schema / properties / not_attached / description
      Added value: +"True when detach_skill found the skill not attached and changed nothing."
    • addedOutput schema / properties / org / description
      Added value: +"Name of the Valet organization the call acted in."
    • addedOutput schema / properties / pin_ignored / description
      Added value: +"True when the skill you gave carried a @v<N> version pin. Pins are retired, so the agent follows the latest version anyway. Set by attach_skill."
    • addedOutput schema / properties / skill / description
      Added value: +"Name of the skill. attach_skill reports the skill's own name; detach_skill repeats what you passed."
    • addedOutput schema / properties / source / description
      Added value: +"Set by attach_skill: org for an organization skill, default for a built-in whose Valet default the agent holds because the organization has published no skill of that name. Absent from detach_skill."
  5. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "already_attached": {
      +      "type": "boolean"
      +    },
      +    "kind": {
      +      "type": "string"
      +    },
      +    "latest_version": {
      +      "type": "integer"
      +    },
      +    "name": {
      +      "type": "string"
      +    },
      +    "not_attached": {
      +      "type": "boolean"
      +    },
      +    "org": {
      +      "type": "string"
      +    },
      +    "pin_ignored": {
      +      "type": "boolean"
      +    },
      +    "skill": {
      +      "type": "string"
      +    },
      +    "source": {
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "org",
      +    "name",
      +    "kind",
      +    "skill"
      +  ],
      +  "type": "object"
      +}
  6. Changed1 schema field changed
    • changedInput schema / properties / skill / description
      Previous value: -"Required. org:<name> or a bare name for an organization skill, optionally followed by @v<N> to pin a version, or catalog:<name> to install and attach a catalog skill."New value: +"Required. org:<name> or a bare name for an organization skill, or catalog:<name> to install and attach a catalog skill. The agent follows the latest version; a @v<N> pin is ignored."
  7. Changed1 schema field changed
    • changedInput schema / properties / skill / description
      Previous value: -"Required. catalog:<name> for a catalog skill, org:<name> or a bare name for an organization skill, optionally followed by @v<N> to pin a version."New value: +"Required. org:<name> or a bare name for an organization skill, optionally followed by @v<N> to pin a version, or catalog:<name> to install and attach a catalog skill."
  8. Added

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), it discloses that the agent is rebuilt on change, that no-op cases skip the rebuild, that refusals happen 'before anything changes,' and that a Valet account connection is required. It also explains the built-in fallback lifecycle, which no annotation could convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded and nearly every sentence carries a distinct rule, but it is a dense, unbroken paragraph of roughly 200 words where the ref-form rules, refusal rules, and rebuild semantics could be structured for faster scanning. No filler sentences, though.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a high-complexity mutation with three-way ref semantics, an output schema already present, and a required auth connection, the description covers prerequisites, exception paths, idempotency, and failure modes. Nothing an agent needs before calling it is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline would be 3, but the description adds real meaning: what each ref prefix selects, that a @v2 pin is rejected, that catalog installs a copy while org requires prior publication, and that omitting org_name falls back per account. It largely mirrors the schema's own wording but adds refusal and lifecycle context the schema lacks.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource+effect: 'Attach a skill to an agent so the agent can use it,' which cleanly separates it from detach_skill and from the create/publish siblings it references. An agent can tell what this does without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly enumerates which ref forms are accepted (org:<name>, bare name, catalog:<name>), the prerequisite chain (create_service with kind skill, then publish_skill), the built-in exception for governance/security, and the refusal conditions for version pins and name collisions. It reads as a complete when/when-not guide rather than a hint.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources