Skip to content

graph-skills.md

Latest commit

 

History

History
139 lines (100 loc) · 4.48 KB

graph-skills.md

File metadata and controls

139 lines (100 loc) · 4.48 KB

SkillGraph

Files: src/graphs/skill.ts, src/graphs/skill-types.ts

Reusable recipes, procedures, and troubleshooting guides with steps, triggers, usage tracking, and cross-graph links. CRUD-only graph — not populated by the indexer.

Data model

Node attributes

Field Type Description
title string Skill title
description string Skill description (markdown)
steps string[] Ordered steps to execute
triggers string[] Phrases/conditions that trigger this skill
inputHints string[] Expected inputs or prerequisites
filePatterns string[] Glob patterns for files this skill applies to
source SkillSource Origin: user or learned
confidence number 0–1 score indicating reliability (default: 1)
tags string[] Free-form tags
usageCount number How many times this skill has been used
lastUsedAt number | null Epoch ms of last usage
version number Incremented on every mutation (starts at 1)
embedding number[] L2-normalized vector
createdAt number Epoch ms
updatedAt number Epoch ms
createdBy string Author
updatedBy string Author
proxyFor object Present only on phantom proxy nodes

Source types

type SkillSource = 'user' | 'learned';
  • user — manually created by a human or by an LLM on request (default)
  • learned — generated by an AI that discovered a pattern

Node ID format

Slug from title: "add-rest-endpoint". Duplicates get "add-rest-endpoint::2".

Edge types (skill-to-skill)

Kind Description
depends_on skill → prerequisite skill
related_to free-form relation
variant_of skill → alternate version

Cross-graph links

skills_create_link supports targetGraph: "docs" | "code" | "files" | "knowledge" | "tasks".

Usage tracking

  • skills_bump_usage(skillId) — increments usageCount and sets lastUsedAt
  • Usage data helps surface frequently used recipes

Recall

skills_recall(query) uses a lower minScore (0.3 vs default 0.5) for higher recall in task contexts. Designed for "what recipes might be relevant here?" queries.

BM25 text extraction

The BM25 keyword index includes triggers alongside title and description, so skills can be found by their trigger phrases.

Enriched skills_get

skills_get returns additional enrichment:

  • dependsOn — skills this skill depends on
  • dependedBy — skills that depend on this skill
  • related — skills with related_to edges
  • variants — skills that are variants of this skill

Attachments

Skills support file attachments stored in .skills/{id}/ alongside the skill.md mirror file.

File mirror

Every mutation writes .skills/{id}/skill.md:

---
id: add-rest-endpoint
source: user
tags: [api]
triggers: [new endpoint, new API route]
createdAt: 2026-03-16T10:00:00.000Z
updatedAt: 2026-03-16T10:05:00.000Z
relations:
  - to: debug-authentication-issues
    kind: related_to
---

# Add REST Endpoint

Description here...

See File Mirror for details.

Manager: SkillGraphManager

CRUD operations

Method Description
createSkill(fields) Create skill, embed, mirror to file
updateSkill(skillId, fields) Partial update, re-embed, re-mirror
deleteSkill(skillId) Delete skill, relations, proxies, mirror dir
getSkill(skillId) Fetch with enrichment (deps, related, variants)
listSkills(opts) List with filters (source, tag, text)
searchSkills(query, opts) Hybrid search with BFS expansion
recallSkills(query, opts) Search with lower minScore for higher recall
bumpUsage(skillId) Increment usageCount + set lastUsedAt

Link operations

Method Description
linkSkill(fromId, toId, kind) Create skill-to-skill relation
createSkillLink(skillId, targetId, targetGraph) Cross-graph link
deleteSkillLink(skillId, targetId, targetGraph) Remove cross-graph link
findLinkedSkills(targetId, targetGraph) Reverse lookup

Attachment operations

Method Description
addAttachment(skillId, filename, content) Add file attachment
removeAttachment(skillId, filename) Remove file attachment

Persistence

Stored as skills.json in the graphMemory directory. In workspaces, shared across member projects.