Skills

Skills are reusable agent capabilities that package task-oriented instructions (and optional file attachments) into a single, activatable unit. When an agent connects, it sees a lightweight catalog of available skills and can activate any skill on demand to receive its detailed guidance.

Skills vs. Instructions

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

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 the skill catalog through two channels:

• The activate_skill tool description: airlock builds this dynamically to list every available skill with its trigger phrase. Because tool descriptions are delivered through the standard tools/list response, this is the universal channel: it reaches the model on every MCP client.
• A structured bootstrap payload for airlock-aware clients, including a machine-readable skills array. On the legacy MCP protocol it arrives as initialize.result._airlock; on the 2026-07-28 protocol it rides result._meta['airlock/bootstrap'] on tools/list (and on initialize for clients that still send one). The payload is identical in both places.

The system instructions also carry a short Skills pointer that tells the agent where the catalog lives and when to use it. It points at the activate_skill tool rather than repeating the skill names:

## Skills

Airlock skills are focused workflows. The full catalog with trigger phrases is
in the `activate_skill` tool description. When a user request matches a listed
skill, call `activate_skill` (with `name` for an exact match or `intent` for
free-text) before taking any other action.

The activate_skill tool description then lists the skills themselves:

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

Everything is injected automatically, with no configuration needed.

The structured bootstrap looks like:

{
  "_airlock": {
    "bootstrap_version": 1,
    "model_catalog_version": 3,
    "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.

model_catalog_version lets a long-lived client notice that the organization's model catalog was republished mid-session and re-fetch it.

Phase 2: Activation (on demand)

When an agent needs a skill, it calls the activate_skill tool, either with the exact skill name, or with a free-text intent describing what the user wants, which airlock fuzzy-matches to the best skill. The full content and attachment list are returned:

{
  "name": "Code Review",
  "description": "Expert code review guidelines and checklist",
  "instructions": "## Code Review Process\n\n1. Check for...",
  "attachments": [
    { "id": "att_1", "type": "reference", "filename": "style-guide.md" },
    { "id": "att_2", "type": "script", "filename": "run-checks.sh" }
  ],
  "attachment_hint": "Use read_skill_attachment with the attachment ID to load the full content of any attachment."
}

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

Skill Discovery Across MCP Clients

Because the skill catalog is carried in the activate_skill tool description, it reaches the model on every MCP client: tool descriptions are part of the standard tools/list response that every client renders. This works even on clients that drop the system instructions from initialize.result.instructions (some runtimes do, including Cursor, Codex, ChatGPT, Gemini, and Copilot): they still see the tools, and therefore still see the skills.

Clients that also forward initialize.result.instructions (Claude Code, claude.ai) get the Skills pointer as additional context, but no client depends on it to discover skills, because the names and trigger phrases are always in the activate_skill description.

Optional: discover skills via management tools

For clients where you want skill discovery to flow through the standard meta-tool path, airlock also exposes skill-discovery tools under the airlock-management namespace. These are regular MCP tools, so they appear in list_services and search_tools. Invoke them through the org endpoint's execute_tool meta-tool.

A large body is read in parts. get_skill, get_skill_version and read_skill_attachment each return up to 40,000 characters per call, which is roughly 10,000 tokens: about 5% of a typical agent's context. When there is more, the response says so, reports the full size, and carries the nextOffset to pass back for the next part. Skills small enough to fit come back whole and unchanged, which is nearly all of them. activate_skill reads the same way, and when a skill is too long to hand over in one call it names the part it gave and tells the agent to call activate_skill again with the same skill name and the reported nextOffset.

Because a long skill is read in parts, update_skill will not accept a whole replacement body that is SHORTER than a skill longer than one read. A shorter body may be a partial read written back, which would delete the rest of the skill without saying so. Edit a long skill with update_skill_content instead, which replaces only the text you name and cannot lose the text it never received. Skills short enough to read in one call are not affected.

The three version tools have one extra condition. If your organization turns off Allow members to use older skill versions, non-admin members are pinned to the latest version: list_skill_versions returns only that version, and get_skill_version and create_skill_version refuse an older one. Admins are never restricted. Restoring is append-only: the earlier content is written as a new version and becomes current, so nothing is overwritten and a restore can itself be undone.

After identifying the right skill, the agent calls activate_skill with the exact skill name from the result, or simply passes a free-text intent and lets airlock match it.

Because these are regular MCP tools, you can author a skill straight from the agent you already work with: "Save this workflow as an airlock skill called Sprint Planning". The new skill appears in the Control Room immediately and can be activated from any connected client. That is exactly what the Push from your AI client option on the New Skill page walks you through.

Ownership

Skills support two ownership levels:

• Organization skills appear in the catalog for all agents connected by any user in the organization by default. 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.

Restricting Access

By default an organization skill is visible to everyone in the organization. To scope it, open the skill's Settings tab and use the Access section (just under Ownership) to grant access to specific users or groups. See Access Control for the full model. As soon as a skill has at least one access grant, only the granted users and groups can discover and activate it. Everyone else stops seeing it in the catalog, in activate_skill, and in the management discovery tools. Remove all grants to return the skill to organization-wide visibility.

Creating a Skill

1. Navigate to Skills in the main navigation
2. Click New Skill
3. Choose how to start:
   • Push from your AI client: ask an agent already connected to your organization's MCP endpoint to save a workflow as a skill ("Save this workflow as an airlock skill called Sprint Planning"). It appears here immediately.
   • From Scratch: write the skill yourself
   • Sync with GitHub: connect a repository of skills; airlock imports them, security-scans every new version, and re-syncs daily. See Syncing skills from GitHub below.
   • From Preset: start from a curated preset and customize it in a short wizard
4. 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 (new skills, including ones created from a preset, default to Personal)
5. Write or paste the skill content using the markdown editor
6. Optionally add Tags for organization
7. Click Create Skill

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

Draft a skill with Claude

You don't have to write a skill by hand. Claude can design it with you in conversation and then save it to airlock itself, with no copy-pasting.

1. Connect airlock to Claude. Add your organization's MCP endpoint as a connector in Claude and sign in. See Connect your agent for the steps for each client.
2. Ask Claude to draft the skill. Describe the workflow you want to capture: when the skill should be used, the steps to follow, the tools to call, and what a good result looks like. Try it on a real task and refine the draft until it does what you want.
3. Tell Claude to push it to airlock. For example: "Save this as an airlock skill called Sprint Planning." Claude calls airlock-management/create_skill, and the skill appears on the Skills page right away.

A pushed skill is Personal unless you ask for organization ownership: only you can see and use it. Making a skill available to your organization needs an admin, and only organization skills can be limited to specific users or groups (see Restricting Access). Review and edit the skill from the Skills page; each edit to its content is saved as a new version. Ask Claude to make later changes too: it updates the same skill with update_skill_content.

If the workflow depends on particular integrations, ask Claude to name the exact tools in the skill (for example github/create_issue) so the agent using it doesn't have to search for them. See Best Practices for more on writing skills that agents pick up reliably.

Editing a Skill

1. Open the skill's detail page
2. Go to the Content tab
3. Edit the content
4. Optionally add a "What changed?" note describing the edit
5. Click Save New Version

Each save creates a new version with an optional "What changed?" note, and the new version becomes the one agents receive the next time they activate the skill. The Versions tab shows the full history, where each entry has a version number, change note, and a Current badge on the active version, and you can Restore any earlier version (which creates a new version with that content while keeping the history intact).

Syncing skills from a GitHub repository

Instead of authoring skills one at a time, admins can connect a repository and let airlock import the skills in it, then keep them in step as the repository changes.

Open Skills → New Skill → Sync with GitHub and paste the repository URL. Public repositories work from the URL alone; private ones need the airlock Code GitHub App installed on your organization.

The wizard is three steps:

1. Connect: airlock does a dry run, parsing the repository and security-scanning every skill it finds. Nothing is written yet.
2. Select: pick whole plugins or individual skills. Skills with security findings are unchecked by default, but you can select them anyway; they import quarantined.
3. Access: choose one access setting (personal, organization, or specific people and groups) that applies to every skill in the import.

What airlock recognizes

Each one becomes its own skill, and each goes through the same pipeline: security scan, quarantine on findings, and content-hash change detection.

Living with a connected repo

• Airlock re-syncs daily, and you can sync on demand. Admins manage existing connections with Manage GitHub syncs on the Skills page.
• Synced skills are read-only in airlock while sync is on, because the repository is the source of truth. Detach an individual skill from the sync if you want to edit it in airlock instead.
• Quarantined skills are not delivered to agents. An admin reviews the findings and releases the skill, which applies the reviewed content only if the repository still matches what was reviewed.
• Disconnecting a repository deletes every skill it still syncs, along with their attachments and access grants. Skills you detached first are local copies the organization owns, so those stay. Detach anything you want to keep before disconnecting.

Skill usage analytics

Open Analytics → Skills in the sidebar to see how your skills are actually used: total activations and calls, success and error counts, how many distinct people activated each skill, and first and last use per skill, plotted over time.

It is the fastest way to spot two problems: skills nobody activates (usually a description that doesn't carry the right trigger phrases) and skills that error often.

Attachments

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

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
• License and Compatibility metadata
• Access: who can discover and activate the skill (organization skills only). Grant access to individual users or groups to scope the skill; with no grants, it is visible to the whole organization. See Restricting Access above.

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.
• Attach supporting files. Scripts, references, and assets give the agent extra context it can load on demand via read_skill_attachment.
• 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.