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.

Not sure which skills your organization is missing? With AI insights on, airlock suggests skills to create, improve or retire each week, based on how your organization works.

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.

Slash commands

airlock also offers every skill you can use as an MCP prompt, so you can pick one yourself instead of waiting for the agent to reach for it. Each client shows them its own way:

The command name is a short, lowercase version of the skill's name, such as merge-close for "Merge & Close". It is chosen once, when the skill is created, and renaming the skill does not change it, so a command you have learned keeps working. If two skills would get the same command name, the later one gets a number, such as deploy-2. A skill's Settings tab shows its exact commands. Whoever can edit the skill can change its command name there (an admin for an organization skill, the owner for a personal one); it must be unique in your organization.

The airlock in each command is the name you gave the connection when you added it, so a shorter name gives shorter commands. For example, claude mcp add --transport http al <your org URL> makes the Claude Code command /al:merge-close. Clients load the list when they connect, so a skill added later appears after you reconnect.

Picking a skill this way activates it exactly as activate_skill does: the same instructions and attachments, and it counts in skill usage analytics as Picked from the prompt menu.

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.

Choosing who can use a skill

A skill's Access tab (admins only) holds one choice with three answers: everyone in its home, chosen people, or only me. Choosing Only me makes the skill personal. Only the person who created the skill can choose it, admins included, and airlock asks first, naming the access it removes. To share a personal skill again, its creator (who needs to be an admin) chooses everyone or chosen people, and the space it will live in. A personal skill belonging to somebody else shows no controls: it is theirs.

Restricting Access

By default an organization skill is visible to everyone in its home space, which is the Organization space unless you chose another when you created it. The skill's Spaces tab is where you move it or lend it to another space. To narrow it inside that space, use its Access tab (admins only) to grant specific people, spaces or service accounts. See Access Control for the full model. As soon as a skill has at least one access grant, only the granted principals 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 it to everyone in its space.

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: pick a curated preset; it fills in the steps below and you can change any of it
4. Work through the four steps:
   • Details: a Name (e.g., "Code Review"), a Description that says what the skill does and when to use it (agents read it to decide when to activate the skill), and optional Tags
   • Content: write or paste the instructions in the markdown editor, and add any attachments
   • Access: everyone in its home, chosen people, or only me. New skills default to Only me, which makes them personal. Sharing a skill with other people needs an admin.
   • Review: check the summary, then click Create skill

Nothing is saved until the last step.

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 spaces (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. A repository with many skills can take a few minutes to scan; the wizard shows how many are done and moves on when all of them are.
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 (everyone in its home, chosen people, or only me, which keeps them personal) that applies to every skill in the import. A restricted import must name at least one person or space: one that names only service accounts is refused, because a service account's grant adds access for that bot without restricting anyone else, so every imported skill would stay open to everyone in its home space.

From an AI client

You can do the same from Claude, ChatGPT or any connected AI client. Ask it to sync a repository, for example: "Sync https://github.com/acme/skills as airlock skills."

1. The agent calls get_skill_sync_preview. airlock parses the repository and security-scans every skill it finds. Nothing is written. When the scans take longer than one call allows, they finish in the background and the agent asks again a minute later.
2. The agent shows you each skill and what the scan found. When the repository holds more than one skill, it asks which ones to import.
3. The agent calls create_skill_sync with the skills you chose. The skills you did not choose are excluded, and later syncs leave them out.

A connect without a choice of skills is refused. The first import then runs in the background, so the agent answers straight away; ask it to list your skill syncs to see how the import went. Including or excluding a path waits until that first import has finished.

A connect from an AI client goes through the same checks, the same security scan and the same quarantine as the wizard. The same agent can sync on demand, include or exclude a path, release a quarantined skill and disconnect a repository, with the same permissions as in the Control Room. No approval is asked by default; an admin can require one through the organization's rules.

The owner of a space can connect and manage repositories whose skills are homed in that space. A private repository is open to them only when it is selected on an airlock Code integration homed in the same space, because airlock reads private repositories through your organization's GitHub App, which can see more than the space should. If an admin later takes the repository off that integration, its syncs pause and the skills already imported stay as they are. A repository a space owner connects brings in its skills only, never its Copilot instructions, which would reach your whole organization. Importing skills as personal stays with admins.

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:

• Name, Description and Tags are edited on the Content tab, next to the instructions.
• Who can use it, including making it personal, is chosen on the Access tab. See Choosing who can use a skill above.
• The Settings tab holds Delete Skill.

License and compatibility values that a skill already carries are kept, and agents can still set them through the skill management tools.

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.