Skills

Skills are markdown files with YAML frontmatter that customize how the agent behaves. A skill can be always-on (part of every prompt) or dynamic (loaded on demand when it’s relevant).

How a skill loads — loading-strategy

Every skill declares one loading strategy:

Strategy	Behavior
always	Always composed into the system prompt. For identity, voice, and durable cross-cutting rules. Keep it short — it costs context on every turn.
dynamic	Loaded on demand. For task / domain skills. Enters context through one of the activation signals below.

A dynamic skill activates through any of:

1. Its description — the model sees every skill’s name + description in a catalog and activates the relevant one. This is the default path, so write the description to say what the skill does and when to use it (include the words a user would say). Always available — no extra field needed.
2. tool-affinity — auto-activates when a tool in the active set matches one of its globs. For skills bound to specific tools.
3. triggers — auto-activates on an exact phrase, for deterministic “must-fire” cases (e.g. a compliance rule that must load whenever a regulated action is named).

A dynamic skill with no tool-affinity and no triggers loads only when the model activates it on its description.

Skill file format

A skill is a markdown file (.md) with YAML frontmatter. Standard fields are top-level; NimbleBrain configuration nests under metadata.nimblebrain:

---
name: meeting-notes
description: >
  Summarize and search meeting notes from Granola. Use when the user mentions
  meetings, notes, agendas, minutes, or standups.
allowed-tools: granola__search_meetings granola__get_meeting
metadata:
  author: mat
  version: "1.0"
  nimblebrain:
    loading-strategy: dynamic
    priority: 50
    tool-affinity:
      - granola__*
    triggers:
      - summarize my meetings
      - meeting notes
---

You are a meeting notes assistant. Use the Granola tools to search and
summarize meeting transcripts.

When asked about meetings:
1. Search with granola__search_meetings
2. Retrieve transcripts with granola__get_meeting
3. Summarize the key discussion points, decisions, and action items

Format action items as a checklist.

Frontmatter fields

Standard (top-level):

Field	Type	Required	Description
name	string	Yes	Lowercase letters, digits, and single hyphens (e.g. meeting-notes); ≤64 chars; matches the filename.
description	string	Yes	What the skill does and when to use it — the activation signal for dynamic skills, so include the words a user would say. ≤1024 chars.
license	string	No	License name or reference to a bundled license file.
allowed-tools	string	No	Space-separated globs for tools this skill may call (e.g. granola__*).
metadata.author / metadata.version	string	No	Conventional metadata.

NimbleBrain (metadata.nimblebrain.*):

Field	Type	Required	Description
loading-strategy	always | dynamic	Yes	How the skill loads (see above).
priority	number	No	Selection / ordering priority, 11–99 (0–10 reserved for core). Default 50.
status	active | disabled	No	Default active.
tool-affinity	string[]	No	Globs; a dynamic skill auto-loads when a matching tool is active (e.g. granola__*).
triggers	string[]	No	Exact phrases; a dynamic skill auto-loads on a case-insensitive substring match.

Note

tool-affinity (when a skill loads) is different from allowed-tools (which tools a skill may call).

Where skills are loaded from

Skills are loaded from multiple locations, in order:

1. Core skills (src/skills/core/) — shipped with the platform, always loaded
2. Built-in skills (src/skills/builtin/) — shipped with the package
3. Global skills (~/.nimblebrain/skills/) — user-created
4. Config directories — any paths listed in skillDirs in nimblebrain.json

{
  "skillDirs": [
    "./skills",
    "/home/user/custom-skills"
  ]
}

Files must have a .md extension.

Connector skill overlays

Installing a connector can automatically apply a short usage overlay — curated guidance for that connector’s tools (e.g. “confirm the recipient before sending mail”). Overlays target the connectors you don’t author yourself (Composio and other third-party MCP servers), so they’re sourced from a NimbleBrain-curated public overlay repo keyed by the connector’s flat slug (the Composio toolkit, e.g. gmail; otherwise the connector slug, e.g. notion) at a pinned version.

Overlays differ from authored skills in two ways:

• Surfaced once into the conversation, not the system prompt. An authored dynamic + tool-affinity skill composes into the system prompt for the turn. A connector overlay instead appears in the conversation history exactly once — on the first call to a matching tool — and then rides the (cached, append-only) history for the rest of the conversation. It’s relevant (only when the connector’s tools are actually used) and cache-friendly (it never re-varies the cached system prefix turn to turn). The tradeoff of this reactive model: the overlay surfaces after the first matching tool call and takes effect from the next turn, so guidance whose value is preemptive (e.g. “confirm before sending”) does not gate that very first call. For hard preconditions, prefer an authored always skill or a tool-side guard.
• Stored separately. Materialized overlays live in a connector-skills/ store, distinct from authored skills/. They don’t appear in the skills__list tool output; list them with the connector tool’s list_bound_skills action instead.

Resolution is always on and fail-soft: it fetches at a pinned repo version, records the fetched content hash, and treats a missing overlay (or any fetch error) as a no-op — a connector install never fails because its optional guidance couldn’t be fetched, and there’s nothing to enable (an overlay exists only if we’ve curated one). Override the repo / version with CONNECTOR_SKILLS_REPO and CONNECTOR_SKILLS_VERSION. When a connector has a curated overlay, the platform skips synthesizing the server’s own skill://<name>/SKILL.md guidance so the model sees one set of instructions, not two.

Uninstalling the connector removes its materialized overlays.

Listing skills

Ask the agent which skills are loaded — it uses the built-in skills__list tool to report each skill’s name, loading strategy, priority, and source file. To see one skill’s full definition, ask the agent for its details.

Creating a custom skill

1. Create a .md file in your skills directory:

   mkdir -p ~/.nimblebrain/skills

2. Write the skill file with frontmatter and body:

   cat > ~/.nimblebrain/skills/code-review.md << 'EOF'
   ---
   name: code-review
   description: >
     Review code for bugs, security issues, and style. Use when the user asks
     to review code, check a diff, or look for bugs.
   allowed-tools: bash__run
   metadata:
     nimblebrain:
       loading-strategy: dynamic
       priority: 50
       triggers:
         - review this code
         - code review
   ---
   
   You are a code reviewer. When asked to review code:
   1. Read the file using bash tools
   2. Identify bugs, security issues, and style problems
   3. Suggest specific improvements with code examples
   EOF

3. Restart the server to load the new skill. In development, bun run dev reloads on source changes.

4. Verify it loaded by asking the agent which skills are available (it uses the skills__list tool).

What’s next

• Chat — see skills in action during conversations
• Managing Apps — install the bundles a skill’s tools come from
• Configuration: nimblebrain.json — full config reference including skillDirs