Skip to content

concepts-skills.md

Latest commit

 

History

History
187 lines (132 loc) · 6.21 KB

concepts-skills.md

File metadata and controls

187 lines (132 loc) · 6.21 KB

Skills — Purpose and Design

What are skills?

Skills are reusable recipes, procedures, and troubleshooting guides that persist across conversations. They capture the "how" — step-by-step processes that would otherwise be lost when an LLM conversation ends.

Think of them as runbooks for AI assistants: instead of re-explaining how to add a new API endpoint every time, you save it as a skill once, and any future conversation can recall and follow it.

Why skills exist

Problem

LLMs are stateless between conversations. Every new chat starts from scratch. If you taught Claude how to deploy your specific project last week, it doesn't remember that today.

Solution

Skills turn procedural knowledge into a queryable, reusable format:

skills_create({
  title: "Add REST endpoint",
  description: "Steps to add a new REST endpoint to this project",
  steps: [
    "Create route file in src/api/rest/",
    "Add Zod validation schema in validation.ts",
    "Register route in index.ts",
    "Add tests in src/tests/rest-api.test.ts",
    "Update REST API docs"
  ],
  triggers: ["new endpoint", "new API route", "add route"],
  tags: ["api", "rest"]
})

Next time someone (or an AI) asks "how do I add a new API endpoint?", skills_recall finds this recipe and returns the exact steps.

Anatomy of a skill

Field Purpose
title Short name — becomes the node ID slug
description Full explanation in markdown
steps Ordered list of concrete actions
triggers Phrases or conditions that should activate this skill
inputHints Expected inputs or prerequisites (e.g. "endpoint name", "HTTP method")
filePatterns Glob patterns for files this skill typically touches
source user (manually created) or learned (generated by AI)
confidence 0–1 score indicating reliability (default: 1)
tags Free-form tags for filtering and organization
usageCount How many times this skill has been applied
lastUsedAt When it was last used

Two types of skills

User skills (source: user)

Created explicitly by a human or by an LLM on request. These are deliberate, verified procedures:

  • "How to deploy to staging"
  • "How to add a new database migration"
  • "How to debug authentication issues"
  • "How to onboard a new team member"

Learned skills (source: learned)

Generated by an AI that discovered a pattern worth remembering:

  • "When tests fail with 'connection refused', check if Docker is running"
  • "To refactor a class, first check docs_cross_references for all usages"

The confidence field lets you express trust: a learned skill with confidence: 0.7 might need verification, while a user skill with confidence: 1.0 is trusted.

Search vs. recall

Two search modes optimized for different scenarios:

skills_search — precise lookup

Default minScore: 0.5. Best for: "do we have a skill for X?"

skills_recall — broad discovery

Default minScore: 0.3. Best for: "what skills might be relevant before I start this task?"

The lower threshold casts a wider net, surfacing loosely related skills that might contain useful context. This is the recommended tool to call at the start of a complex task.

Triggers and BM25

Triggers are special — they're included in the BM25 keyword index alongside title and description. This means:

triggers: ["new endpoint", "add route", "REST API"]

A keyword search for "add route" will find this skill even if those exact words don't appear in the title or description. Triggers act as search aliases.

Usage tracking

skills_bump_usage({ skillId: "add-rest-endpoint" })

Increments usageCount and sets lastUsedAt. This is meant to be called after successfully applying a skill, so:

  • Frequently used skills surface higher in listings
  • Stale skills (high count but old lastUsedAt) might need updating
  • Never-used skills might need better triggers or should be retired

Skill relationships

Skills connect to other skills:

Relation Purpose
depends_on This skill requires another skill first
related_to These skills are about similar topics
variant_of Alternative approach for the same goal

And to external nodes via cross-graph links:

skills_create_link({
  skillId: "add-rest-endpoint",
  targetId: "src/api/rest/index.ts",
  targetGraph: "code",
  kind: "references"
})

Now the skill is connected to the actual code it operates on. An LLM can follow the link to read the current code before applying the skill's steps.

File mirror

Skills are mirrored to .skills/{id}/skill.md:

---
id: add-rest-endpoint
source: user
tags: [api, rest]
triggers: [new endpoint, add route]
confidence: 1
---

# Add REST Endpoint

Steps to add a new REST endpoint to this project...

Like tasks and notes, skill files:

  • Are version-controlled with git
  • Can be edited in an IDE (changes sync back)
  • Support file attachments (diagrams, templates, etc.)

The prompt generator connection

The web UI includes a Prompts page that generates AI system prompts with skill awareness. Generated prompts can be exported as skills — closing the loop between prompt engineering and reusable recipes.

Real-world examples

Development recipes

  • "Add a new MCP tool" — steps for creating tool file, adding to registration, writing tests
  • "Create a new graph type" — pattern for types, graph class, manager, tests

Debugging procedures

  • "Debug embedding mismatch" — check model fingerprint, force re-index, verify dimensions
  • "Fix WebSocket disconnection" — check CORS, verify WS path, check proxy headers

Operational runbooks

  • "Deploy to production" — build, test, tag, push, verify
  • "Rotate API keys" — generate new keys, update config, reload server

Architecture patterns

  • "Add pagination to REST endpoint" — Zod schema, query params, response format
  • "Add file attachments to a graph" — scanAttachments, mirror, REST upload handler

Configuration

projects:
  my-app:
    projectDir: "/path/to/my-app"
    graphs:
      skills:
        enabled: true
        access:
          intern: r    # interns can read skills but not modify