Skills

Skills are markdown files with YAML frontmatter that control how the agent responds. A skill can inject a system prompt, filter which tools are available, and require specific bundles to be installed.

How skills work

When you send a message, the skill matcher runs against it:

1. Phase 1: Triggers — substring match against trigger phrases. First hit wins.
2. Phase 2: Keywords — count keyword hits in your message. Minimum 2 hits to qualify. Highest count wins.
3. The matched skill’s markdown body is injected into the system prompt.
4. If the skill has allowed-tools, only those tools (plus system tools) are surfaced.

If no skill matches, the agent uses the default system prompt with all tools available.

Two types

Type	Behavior	Priority range
context	Always injected into the system prompt, regardless of matching. Sorted by priority (lower = first).	Typically 1-10
skill	Only injected when matched against the user’s message via triggers or keywords.	Typically 50

Context skills provide background knowledge. Skill-type skills provide task-specific instructions and tool scoping.

Skill file format

A skill file is a markdown file (.md) with YAML frontmatter:

---
name: meeting-notes
description: Summarize and search meeting notes from Granola
version: 1.0.0
type: skill
priority: 50
allowed-tools:
  - granola__*
requires-bundles:
  - "@nimblebraininc/granola"
metadata:
  keywords:
    - meeting
    - notes
    - agenda
    - minutes
    - standup
  triggers:
    - summarize my meetings
    - meeting notes
  category: productivity
  tags:
    - meetings
    - granola
  author: mat
---

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

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

Format action items as a checklist.

Frontmatter fields

Field	Type	Required	Description
name	string	Yes	Unique skill identifier
description	string	No	Human-readable description
version	string	No	Semantic version. Defaults to 0.0.0.
type	context | skill	No	Defaults to skill if omitted.
priority	number	No	Sort order for context skills (lower = first). Defaults to 50.
allowed-tools	string[]	No	Glob patterns for tools this skill can access (e.g., granola__*). When set, only matching tools plus nb__* system tools are surfaced.
requires-bundles	string[]	No	Bundle names that must be installed for this skill to work.
metadata.keywords	string[]	No	Words matched in phase 2 (case-insensitive substring). Minimum 2 must hit.
metadata.triggers	string[]	No	Phrases matched in phase 1 (case-insensitive substring). First hit wins.
metadata.category	string	No	Organizational category
metadata.tags	string[]	No	Organizational tags
metadata.author	string	No	Author name

The matching algorithm

The matcher operates in two phases on type: "skill" skills only (context skills are excluded from matching).

Phase 1 — Triggers: Loop through all skills. For each skill, check if any of its trigger phrases appear as a substring in the message (case-insensitive). The first trigger that matches wins. No further skills are checked.

Phase 2 — Keywords: If no trigger matched, loop through all skills. For each, count how many of its keywords appear as substrings in the message (case-insensitive). A skill needs at least 2 keyword hits to qualify. The skill with the most hits wins.

Note

The algorithm is deliberately simple — no weights, no ML, no normalization. A skill with 3 keywords hitting 2 qualifies the same way as a skill with 10 keywords hitting 3. The absolute hit count is what matters.

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. Loading is non-recursive (only top-level files in each directory).

Listing skills

nb skill list

NAME              TYPE      PRIORITY  SOURCE
bootstrap         context   1         src/skills/core/bootstrap.md
meeting-notes     skill     50        /home/user/.nimblebrain/skills/meeting-notes.md

For JSON output:

nb skill list --json

Get details on a specific skill:

nb skill info meeting-notes

Name: meeting-notes
Type: skill
Priority: 50
Description: Summarize and search meeting notes from Granola
Source: /home/user/.nimblebrain/skills/meeting-notes.md
Allowed tools: granola__*

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

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 and improvements
   type: skill
   priority: 50
   allowed-tools:
     - bash__*
   metadata:
     keywords:
       - review
       - code
       - bug
       - refactor
     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. Verify it loaded:

   nb skill list

4. If the runtime is already running, reload:

   nb reload

What’s next

• Chat — see skills in action during conversations
• Managing Apps — ensure required bundles are installed
• Configuration: nimblebrain.json — full config reference including skillDirs