Concepts

Concepts: Skills

Skills are reusable bundles of prompt content, REST tools, or MCP server bindings — installed once at the org level and attached to any agent or runner.

A skill is a reusable bundle you install once in your Flapjack organization and then attach to any number of agents or runners. Skills extend an agent without touching its base stable_preamble.

Three sources

Source	What it provides	What happens at runtime
`skill_md`	The body of a `SKILL.md` file in a GitHub repo	The body is appended to the agent's `stable_preamble` in `lib/agent-config.ts`
`openapi_action`	An OpenAPI 3.x spec	Each operation is registered as a callable tool, and the agent invokes them with structured arguments. The platform forwards the request to the spec's server.
`mcp_registry`	A remote MCP server URL from the MCP registry	A managed `mcp_servers` row is created. Tools are loaded over Streamable-HTTP/SSE on each turn (stdio MCPs are rejected).

A fourth source, custom, is reserved for skills you create directly in the dashboard with custom prompt content.

Lifecycle

            install              attach                 enable / disable
catalog ─────────────► org-wide ─────────► agent/runner ───────────────►
                       skill              binding         (per binding)

                       sync (on demand) ──► refresh upstream content

Install with POST /api/skills (or client.installSkill(...)). The skill is fetched, parsed, and stored in skill_definitions for the org.
Attach to an agent (agent_skills) or runner (runner_skills). The binding can carry a promptOverride and/or a stored credential.
Sync with POST /api/skills/{id}/sync to re-fetch source content. mcp_registry skills sync via the MCP tool cache automatically.
Uninstall removes the skill from the org and detaches it from all agents/runners.

Statuses on the skill itself: active (default, loaded into agents), disabled (admin paused — not loaded), error (a sync failed; visible in the dashboard).

How skills compose into the agent

When the runtime assembles an agent's config (see lib/agent-config.ts):

final preamble = [
  agent.stable_preamble,
  scheduled-tasks instructions (if enabled),
  ...skill_md prompt content for each enabled skill,
].join('\n\n')

final tools = [
  ...agent.custom tools,
  ...openapi_action tools (one per skill operation),
  ...scheduled-task tools (if enabled),
]

final mcps = [
  ...agent.attached MCP servers (mcp_registry skills surface here too),
]

Per-binding promptOverride replaces the skill's stored prompt for that one agent or runner only.

When to use a skill vs. raw config

Use a skill when the same prompt fragment, set of REST endpoints, or MCP server is shared across multiple agents or organizations.
Use the agent's stable_preamble when the instructions are unique to one agent's role.
Use a webhook tool when you have a single REST endpoint without a full OpenAPI spec.
Use a custom tool for fully client-side execution (onToolCall in the SDK).

Surface coverage

Skills are first-class on every Flapjack surface:

Surface	How
Dashboard	Skills sidebar entry, plus per-agent and per-runner Skills tabs
REST API	`/api/skills/*`, `/api/agents/{id}/skills`, `/api/runners/{id}/skills`
TypeScript SDK	`client.installSkill`, `client.attachSkillToAgent`, etc.
MCP server	`flapjack_browse_skills`, `flapjack_install_skill`, `flapjack_attach_skill_to_agent`, ...
Skill plugin	`flapjack-integration` SKILL.md documents end-to-end usage
Runtime	`lib/agent-config.ts` and `lib/runner-config.ts` compose enabled skills into the agent/runner config

authType on a skill describes how the underlying source is reached when the agent invokes a tool: none, api_key, oauth, or bearer. To bind a stored credential to a specific agent's attachment, pass credentialId to attachSkillToAgent / attachSkillToRunner. For BYOK key resolution at LLM call time, see Credential Resolution (BYOK).