Instructions

Instructions are reusable pieces of content — guidelines, rules, or prompts — that admins author once for the whole organization. When an agent connects to your organization's MCP endpoint, every published, system-mode instruction is delivered automatically through the MCP protocol, ensuring consistent behavior across your organization.

Delivery Modes

Each instruction has a delivery mode that controls how agents receive its content:

Instruction Lifecycle

Instructions follow a three-stage status lifecycle:

DRAFT  ──→  PUBLISHED  ──→  ARCHIVED

• Draft: Work-in-progress. Visible in the UI but not delivered to agents.
• Published: Active. System-mode instructions are delivered to every agent connected to the organization.
• Archived: Retired. No longer delivered to agents but preserved for history.

Only published instructions reach agents. Changing an instruction back to draft or archiving it immediately stops delivery.

Creating an Instruction

1. Open Settings → Organization → Instructions (admin only)
2. Click New Instruction
3. Fill in the details:
   • Name: A descriptive title (e.g., "Code Review Guidelines")
   • Description: Brief explanation of the instruction's purpose
   • Delivery Mode: Choose System or Prompt
   • Tags: Optional comma-separated tags for organization (e.g., "security, compliance")
4. Write or paste the instruction content using the markdown editor — use the write/preview toggle to preview the rendered markdown
5. Click Create Instruction

The instruction is created in Draft status with an initial version (v1) created automatically.

Publishing

To make an instruction available to agents:

1. Open the instruction's detail page
2. Click the Publish button, or go to the Settings tab and change the status to Published
3. Confirm the action

The initial version is created automatically when you first create the instruction. Publishing changes the status so agents start receiving the content.

Versioning

Instructions support versioning so you can track changes over time.

Creating a New Version

1. Open a published instruction's detail page
2. Edit the content
3. Click Save as New Version
4. Add a change message describing what changed

Each version is an immutable snapshot. The instruction's current content always reflects the latest version unless an assignment pins to a specific version.

Version History

View all versions of an instruction in the Versions tab on the instruction detail page. Each entry shows the version number, change message, and timestamp.

Assigning to Integrations

Note: Assignments do not currently gate delivery. On the organization-wide MCP endpoint, every published system-mode instruction is delivered to every connecting agent, whether or not it is assigned to an integration. Instructions take effect as soon as they are published — no assignment step is required. Assignments are an organizational record (which instructions relate to which integrations); the version pinning they support is likewise stored metadata only and has no effect on what agents receive today.

To record an assignment:

1. Open the instruction's detail page
2. Go to the Assignments tab
3. Select the integration from the dropdown
4. Click Assign
5. The assignment tracks the latest version by default

Version Pinning

• Track latest (default): The assignment always references the instruction's current content.
• Pin to version (API only): Via the API, assignments can record a pin to a specific version. The UI currently assigns in track-latest mode only. Because assignments don't gate delivery today, a pin is stored metadata — it does not change what agents receive.

Importing instructions from GitHub

If you connect a GitHub repository for skills, airlock also imports that repository's Copilot instructions — the .github/copilot-instructions.md file — as an organization instruction in System delivery mode. No separate connection or setup is needed; it happens on the same sync.

Imported instructions arrive as Draft and are never delivered until an admin publishes them. That is deliberate: a published system instruction reaches every agent session in your organization, so text landing in a repository must never reach agents by itself. Editing the file upstream returns a published instruction to Draft, so a change is reviewed before it goes back out.

The imported instruction is named after its repository (for example, Copilot instructions (acme/platform)), so two connected repositories don't collide.

Security review. Imported content is scanned like skills are. An instruction with findings is quarantined: it cannot be published, is not delivered to agents, and is not readable over MCP. Its detail page shows the findings with an Approve & release action, which applies only while the file upstream still matches the content that was reviewed.

Path-scoped rules are not imported. Files under .github/instructions/ are recognized and reported, but deliberately not imported: they apply only to certain file paths, whereas an airlock instruction is delivered org-wide with no file context. Importing one would silently turn "in src/api, use zod" into "always, everywhere, use zod". If a rule like that should apply to your whole organization, author it as an instruction by hand.

Deleting the file upstream returns the instruction to Draft and stops it syncing, so a rule you removed from the repository stops being delivered. The instruction itself is kept so you can decide whether to keep it by hand.

Disconnecting the repository stops future updates but does not delete the instructions.

Managing Instructions

Settings

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

• Name and Description
• Status (Draft, Published, or Archived)
• Delivery Mode (System or Prompt)
• Tags

Deleting an Instruction

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

Deleting an instruction permanently removes the instruction along with all its versions and assignments. This action cannot be undone.

How Agents Receive Instructions

System Mode

System instructions are concatenated and included in the MCP server's initialization. When an agent connects, it receives the combined instructions automatically — similar to a system prompt. No action is needed from the agent.

Prompt Mode

Prompt instructions are not delivered to agents automatically — only System mode is auto-delivered today. Their content is still stored and versioned, and an agent connected to your organization's management endpoint can retrieve it on demand:

1. Find the instruction with list_instructions or search_instructions
2. Call get_instruction with the instruction ID to retrieve its current content

Programmatic Management

Instructions can also be managed programmatically through the organization-wide MCP endpoint. Read tools are available to any organization member; every tool that changes an instruction requires the connected member to be an organization admin — an agent connected with a regular member's credentials gets a permission error. Service accounts — and service tokens bound to one, or created with the MEMBER access role — resolve to the member role, so they can read instructions but not mutate them. An unbound org-wide service token left at the default admin access role resolves to admin and can mutate instructions.

These tools enable automation workflows — for example, an agent connected as an admin could create and publish instructions based on a team's documentation, or assign instructions to newly created integrations automatically.

Best Practices

• Keep instructions focused. One instruction per topic makes assignment and versioning easier to manage.
• Use system mode for always-on guidance. Compliance rules, coding standards, and safety guidelines work best as system instructions since agents receive them automatically.
• Use prompts for on-demand references. Templates, checklists, and detailed procedures that agents only need occasionally are better as prompt instructions.
• Version before major changes. Create a new version before significant edits so you can roll back by re-creating a version from earlier content if needed.
• Archive instead of deleting when retiring guidance. Archiving stops delivery immediately (only published instructions reach agents) while preserving the version history.