Skills

Skills are reusable agent capabilities that bundle instructions and tool references into a single, activatable package. When an agent connects, it sees a lightweight catalog of available skills and can activate any skill on demand to receive detailed guidance and recommended tools.

Skills vs. Instructions

Skills and Instructions both deliver content to agents, but they serve different purposes:

	Instructions	Skills
Purpose	Governance content (rules, guidelines, prompts)	Task-oriented capabilities (playbooks, workflows)
Delivery	Always-on (system mode) or opt-in (prompt mode)	On-demand via activate_skill tool
Scope	Assigned to specific servers	Available across all servers in your organization
Includes tools	No	Yes — optional tool references
Versioning	Full version history	No versioning (edited in-place)
Lifecycle	Draft → Published → Archived	Always active once created
Ownership	Organization only	Organization or personal

When to use which:

• Use Instructions for content that should always be present or that agents should follow without being asked — compliance rules, coding standards, safety guidelines.
• Use Skills for task-oriented capabilities that agents activate when needed — code review playbooks, deployment checklists, troubleshooting workflows.

How Skills Reach Agents

Skills use a two-phase delivery model to keep initial connections lightweight:

Phase 1: Catalog (at connection time)

When an agent connects to the organization-wide Airlock MCP endpoint, it receives two startup signals:

• A compact catalog in the system instructions listing available skills by name and description
• A structured bootstrap payload in initialize.result._airlock for Airlock-aware clients

The system instructions look like:

## Available Skills

Use `activate_skill` with the skill name to get full instructions and tool references.

- **Code Review**: Expert code review guidelines and checklist
- **Bug Triage**: Step-by-step bug triage workflow

The catalog is automatically injected — no configuration needed.

The structured bootstrap looks like:

{
  "_airlock": {
    "bootstrap_version": 1,
    "skill_source": "preferred",
    "disable_local_skills": false,
    "routing_mode": "airlock_first",
    "airlock_authority_scope": "matching_skills",
    "activation_tool": "activate_skill",
    "attachment_tool": "read_skill_attachment",
    "skills": [
      { "name": "Code Review", "description": "Expert code review guidelines and checklist" }
    ]
  }
}

Clients that understand the Airlock bootstrap should prefer Airlock skills first for requests that match the listed Airlock skills. Local SKILL.md and bundled skill catalogs can still remain available when no Airlock skill matches.

Phase 2: Activation (on demand)

When an agent needs a skill, it calls the activate_skill tool with the skill name. The full content and tool references are returned:

{
  "name": "Code Review",
  "description": "Expert code review guidelines and checklist",
  "instructions": "## Code Review Process\n\n1. Check for...",
  "recommended_tools": [
    { "project": "github", "tool": "list_pull_requests" },
    { "project": "github", "tool": "create_review" }
  ],
  "attachments": [
    { "type": "reference", "filename": "style-guide.md" },
    { "type": "script", "filename": "run-checks.sh" }
  ]
}

This lazy-loading approach keeps the initial system instructions compact while making detailed guidance available when needed.

Skill Discovery Across MCP Clients

Whether the Phase 1 catalog actually reaches the model depends on how the MCP client integrates the initialize response. The catalog is always delivered to the client — both as human-readable text in initialize.result.instructions and as a structured payload in initialize.result._airlock — but only some clients surface that text to the model as system context.

Client	Forwards initialize.result.instructions to the model?	Workaround needed?
Claude Code	Yes	No
claude.ai	Yes	No
Anthropic Managed Agents runtime (docs)	No (verified 2026-04-21)	Yes — see below
Other MCP clients	Behavior may vary	Test with your target runtime

In the Managed Agents case, a direct curl to the org MCP endpoint confirms the catalog is present in the initialize response — it just never reaches the LLM. As a result, the agent has no way to know which skills exist or what their exact names are: it cannot guess a name to pass to activate_skill, and list_services / search_tools return tools but not skills.

Workaround: discover skills via management tools

Airlock exposes skill-discovery tools under the airlock-management namespace. These are regular MCP tools and therefore appear in list_services and search_tools, so an agent can find them even without seeing the catalog. Invoke them through the org endpoint's execute_tool meta-tool.

Tool	Purpose
airlock-management/list_skills	List all skills available to the agent (organization + personal)
airlock-management/search_skills	Search skills by keyword
airlock-management/get_skill	Fetch a specific skill by ID

After identifying the right skill, the agent calls activate_skill with the exact skill name from the result.

A copy-paste system-prompt fragment for managed agents:

You have access to Airlock skills that bundle instructions and recommended tools for specific tasks. Before attempting a task, call execute_tool with tool: "airlock-management/list_skills" and arguments: {} to see what skills are available. If one matches the request — by name or description — call activate_skill with that exact skill name to receive its full instructions and recommended tools. Use airlock-management/search_skills to narrow down by keyword if the catalog is large.

Clients that already surface initialize.result.instructions (Claude Code, claude.ai) do not need this prompt addition — the catalog is in the model's system context already, and the agent can call activate_skill directly with a name from it.

Ownership

Skills support two ownership levels:

Ownership	Visibility	Who can create	Who can edit/delete
Organization	All members of the organization	Admins only	Admins only
Personal	Only the creator	Any user	The creator

• Organization skills appear in the catalog for all agents connected by any user in the organization. Use these for shared team capabilities.
• Personal skills appear only when the creator's credentials are used. Use these for individual workflows or experiments before promoting to organization-level.

Creating a Skill

1. Navigate to Skills in the main navigation
2. Click New Skill
3. Fill in the details:
   • Name: A descriptive title (e.g., "Code Review")
   • Description: A one-liner explaining the skill's purpose (shown in the catalog)
   • Ownership: Choose Organization or Personal
4. Write or paste the skill content using the markdown editor
5. Optionally add Tags for organization
6. Click Create Skill

Preview the rendered markdown using the write/preview toggle in the content editor.

Editing a Skill

1. Open the skill's detail page
2. Go to the Content tab
3. Edit the content
4. Click Save Changes

Changes take effect immediately — the next time an agent activates the skill, it receives the updated content. There is no version history; edits modify the skill in place.

Tool References

Tool references let you recommend specific tools from your servers that are useful when following a skill's instructions. They are advisory — the agent decides whether to use them.

Adding Tool References

1. Open the skill's detail page
2. Go to the Tool References tab
3. Select a Server from the dropdown
4. Select a Tool from that server
5. Click Add

Removing Tool References

Click the remove button next to any tool reference to remove it.

When an agent activates the skill, tool references are included as recommended_tools in the response, showing the project name and tool name.

Attachments

Skills support file attachments that provide additional context when a skill is activated. Attachments are organized into three types:

Type	Purpose
Script	Setup scripts, automation, CLI commands
Reference	Background docs, research
Asset	Templates, configs, style guides

These categories are conceptual, not filesystem folders. Attachments are identified by their type and filename.

Adding Attachments

1. Open the skill's detail page
2. Go to the Attachments tab
3. Click Add Attachment
4. Choose the attachment type, provide a filename, and paste the content
5. Click Save

How Agents Access Attachments

Attachment content is not sent with the initial skill activation to keep responses compact. Instead, agents use the read_skill_attachment tool to load specific attachments on demand when they need them. The activation response lists available attachments by name (type and filename) so the agent knows what's available.

Managing Skills

Settings

On the skill's detail page, the Settings tab lets you edit:

• Name and Description
• Ownership (Organization or Personal)
• Tags

Deleting a Skill

1. Open the skill's detail page
2. Go to the Settings tab
3. Click Delete Skill
4. Confirm the action

Deleted skills are immediately removed from the catalog and can no longer be activated.

Best Practices

• Keep skills focused. One skill per task or workflow makes activation intuitive for agents.
• Write clear descriptions. The one-liner description is what agents see in the catalog to decide whether to activate a skill.
• Add tool references. Pointing agents to the right tools alongside instructions improves task completion.
• Start personal, promote to organization. Experiment with personal skills before making them available to the whole team.
• Use markdown structure. Headers, numbered steps, and checklists in skill content help agents follow instructions methodically.