Develop Skills and Control Plane Plugins
For AI Agents: the Markdown version of this page is at https://ankole.agentbull.com/en-US/docs/writing-a-skill/index.md. The documentation index is at https://ankole.agentbull.com/en-US/llms.txt.
Skills and Control Plane Plugins extend Ankole at two very different boundaries—pick the mechanism that matches what you are building before writing code:
| Requirement | Use |
|---|---|
| Teach an Agent a repeatable workflow or operating procedure | Skill |
| Wrap an MCP server with domain selection and usage rules | Skill |
| Add a new Identity Provider, chat adapter, LLM Provider, or Worker provider kind | Control Plane Plugin |
Add site-scoped settings, supervised OTP services, hooks inside domain transactions, /api/v2 extension routes, or Web UI Slots |
Control Plane Plugin |
| Toggle runtime behavior dynamically without restarting the control plane | OpenFeature (Ankole.Features) |
A Skill is a directory of Markdown and helper files read by an Agent at runtime, requiring no control-plane rebuild. By contrast, a Control Plane Plugin is a site-scoped, first-party Elixir extension compiled into the release (never scoped to an individual tenant or Agent): :optional Plugins activate on the next control-plane start after a siteadmin enables them, while :always Plugins stay permanently active with the build.
Write a Skill
Every Skill is a directory containing SKILL.md, alongside optional reference docs, templates, and agents/openai.yaml:
my-skill/
├── SKILL.md
├── agents/
│ └── openai.yaml
├── reference.md
└── templates/
Use a tenant-unique slug of lowercase letters, digits, dots, hyphens or underscores, beginning with a letter or digit. Shipped first-party Skills live under app/library/skills/. Members create or import custom packages in Meta Ankole → Skills.
Write the frontmatter
YAML frontmatter at the top of SKILL.md governs discovery, defaults, and execution surface:
---
name: my-skill
description: "Use when the Agent must review a vendor contract."
default_enabled: true
category: productivity
tags: [Contracts]
ankole-runtime: background_job
platforms: [linux]
---
Write a concrete trigger condition in description, because the Agent scans descriptions in its catalog to decide when to load the full Skill. Set ankole-runtime: background_job whenever the workflow requires an isolated Background Agent Job workspace, and add platforms: [linux] only if the Skill invokes Linux-only binaries.
Complete Skill packages
Ankole stores each Skill as a required SKILL.md manifest plus its companion files. Frontmatter and the body are edited together; scripts, templates, binary assets and reference documents retain their relative paths. Official and Agent Plugin Skills share the same tenant-wide slug namespace.
Link companion files explicitly from SKILL.md and read them on demand. Main Agent runs use /drive/Skills/<slug>/; Background Agent Jobs receive the packages allowed for that Job. The enabled Agent can read the whole package. Put business data with a restricted audience in Brain or a separately shared collaboration page.
Write the body
Write SKILL.md for a capable Agent that has no prior context about your team’s local conventions, spelling out:
- when to trigger the Skill;
- which inputs and files to inspect first;
- the exact sequence of steps;
- the required output format and verification checks; and
- actions that are forbidden or require explicit human approval.
Link every companion reference file or template explicitly from SKILL.md—because the Agent reads companion files lazily on demand, any file left unmentioned in SKILL.md will go unused.
Declare MCP dependencies
Declare MCP server connections inside agents/openai.yaml:
dependencies:
tools:
- type: mcp
value: my-mcp-server
transport: streamable_http
url: https://mcp.example.com/mcp
bearer_token_env_var: MY_MCP_TOKEN
Agent Computer injects this dependency only while the Skill is enabled. In SKILL.md, list the relevant domain tools and selection rules, instruct the Agent to inspect only the chosen tool’s schema via mcporter list server.tool --schema --json, and pass JSON arguments over stdin. See MCP reference for the full openai.yaml schema.
Verify the Skill
Enable the Skill on a test Agent and run a realistic prompt end to end, verifying that the Agent picks the Skill, reads any linked reference files, and satisfies every completion check. If the Agent skips the Skill, sharpen description; if steps drift out of order, tighten the numbered procedure and constraints.
Verify package-relative references, executable scripts, compatible-runtime loading and routing for incompatible runtimes. With “Enable for all Agents” off, test a colleague binding and your assistant binding independently. Turning the global switch on and off must preserve those bindings. Disabling all applicable bindings or the parent Plugin must remove the Skill from the enabled catalog and prevent skill_view from loading it.
Develop a Control Plane Plugin
Build a Control Plane Plugin whenever you need site-scoped capabilities inside the Elixir control plane. Every plugin module implements Ankole.Plugins.Plugin; at minimum, it defines a stable lowercase slug ID:
defmodule Ankole.Plugins.MyPlugin do
@behaviour Ankole.Plugins.Plugin
@impl true
def plugin_id, do: "my-plugin"
end
Implement optional callbacks only for the extension points that your Plugin uses:
| Callback | Purpose |
|---|---|
activation/0 |
:optional (default, toggled via plugins.enabled_ids for the next boot) or :always (compiled active with no Console toggle) |
display_name/0, description/0 |
Localized title and summary displayed in the Site Admin Console |
adapter_declarations/0 |
Register IdP, chat, LLM Provider, Worker provider (agent_workers.provider_kind), or webhook handler adapters |
hooks/0 |
Register synchronous hooks inside domain transactions ([{hook_point, module}] implementing Ankole.Plugins.Hook) |
app_config_definitions/0 |
Register static AppConfigure keys |
app_config_patterns/0 |
Register parameterized AppConfigure key patterns |
children/0 |
Supervise long-lived connections, registries, or reconcilers under the Plugin supervisor |
Full-stack build extensions can additionally wrap the Phoenix router with an outer HTTP Plug, mount typed /api/v2/* JSON:API routes, and bind typed Web UI Slots (PodAppSlots, ConsoleAppSlots, AuthAppSlots) via overrides in entries.json.
Register the Plugin
List your module under :control_plane_plugin_modules in config/config.exs:
config :ankole, :control_plane_plugin_modules, [
Ankole.Plugins.MyPlugin
]
Once registered, the Plugin appears in the site-scoped catalog inside the Site Admin Console (/site-admin-console with scope set to Global defaults, backed by GET / PUT /api/v2/site/control-plane-plugins). After a siteadmin enables an :optional Plugin, the next control-plane boot freezes it into the :persistent_term snapshot and activates its AppConfigure fields, adapters, transaction hooks, and supervised processes (veto_disable blocks disabling a Plugin that provides Worker providers while any tenant references one of its Worker kinds). :always Plugins activate unconditionally on every boot. Because Control Plane Plugins never hot-load at runtime, use OpenFeature (Ankole.Features) for policies that must toggle dynamically without a restart.
Declare an adapter
Return adapter maps from adapter_declarations/0, using contract_id to target the owning subsystem:
@impl true
def adapter_declarations do
[
%{
contract_id: "signals.adapter",
id: "my-adapter",
plugin_id: plugin_id()
}
]
end
Each subsystem defines the extra fields required on its adapter map: chat adapters implement the Signals contract, while Identity Providers, LLM Providers, and Worker providers plug into their respective subsystem registries—never invent a parallel config store inside your Plugin.
Declare settings, hooks, and services
Expose operator-tunable runtime settings through app_config_definitions/0 or app_config_patterns/0, reserving OS environment variables strictly for bootstrap secrets needed before PostgreSQL is reachable.
Use hooks/0 to run synchronous admission or quota checks inside domain transactions (:create_agent, :create_invitation, :enable_signal_binding). Each hook module implements Ankole.Plugins.Hook.before_commit_in_tx/2, returning :ok or {:error, reason} inside the caller’s database transaction.
Return standard OTP child specs from children/0 to place long-lived sockets and reconcilers under the Plugin supervisor; Ankole starts them when the Plugin activates at boot and stops launching them on the next restart after disablement.
Verify the Plugin
Run the control-plane test suite and static analyzers. For an :optional Plugin, enable it in the Site Admin Console (/site-admin-console) and restart the control plane (:always Plugins start automatically on boot). Confirm that the Plugin reports Active now, its AppConfigure fields render cleanly, its transaction hooks enforce their invariants, and every declared adapter completes a live end-to-end check (including protocol integration tests for external services).
Continue
- See Agent Library for Skill enablement, inheritance, and installation.
- See Control Plane Plugins for discovery and activation.
- See Add a Provider for a new LLM Provider.