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.

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.