Skip to main content
The skills API provides access to GenieHelper’s agent skill graph — 191 procedural knowledge modules organized across 11 categories in a DuckDB-backed graph. Skills are used by both the Genie chat agent and Goose CLI to select the most relevant expertise for a given task.

​
Endpoints

MethodPathDescription
GET/api/skillsList all skills with filtering and pagination
GET/api/skills/:idFetch a single skill by UUID or name
POST/api/skills/activateStimulus propagation: find best skills for a task
POST/api/skills/searchFull-text skill search
GET/api/skills/:id/relatedGet related skills for a given skill
Skills are stored in the agent_skills Directus collection and served via the serviceClient (MCP_SERVICE_TOKEN). No user auth is required to read skills — the collection is read-accessible to the service token.

​
GET /api/skills

Returns a paginated, filterable list of all agent skills. 
GET /api/skills?category=01-core-development&limit=20

​
Query parameters

​
category
string
Filter by skill category. See the categories table below for valid values.
​
tags
string
Comma-separated list of tags to filter by. Returns skills that have any of the listed tags. Example: tags=authentication,jwt,express
​
limit
number
Number of results to return. Default: 50. Maximum: 500.
​
offset
number
Pagination offset. Default: 0.
​
sort
string
Sort field. Default: -date_updated (most recently updated first).

​
Response

{
  "success": true,
  "data": [
    {
      "id": "7a3f2c1b-...",
      "name": "backend-developer",
      "category": "01-core-development",
      "description": "Expert in Express, Node.js, REST API design, and Prisma ORM",
      "tags": ["express", "node", "rest", "prisma"],
      "content": "You are a backend developer...",
      "activation_score": 0.92,
      "date_updated": "2026-03-13T10:22:00Z"
    }
  ],
  "meta": {
    "total_count": 191,
    "filter_count": 12
  }
}

​
GET /api/skills/:id

Returns a single skill by UUID or by name slug. 
GET /api/skills/backend-developer
GET /api/skills/7a3f2c1b-4d5e-6f78-90ab-cdef01234567

​
Query parameters

​
include_related
boolean
When true, the response includes a related_skills array with abbreviated records for each related skill. Default: false.

​
Response

{
  "success": true,
  "data": {
    "id": "7a3f2c1b-...",
    "name": "backend-developer",
    "category": "01-core-development",
    "description": "Expert in Express, Node.js, REST API design, and Prisma ORM",
    "tags": ["express", "node", "rest", "prisma"],
    "concepts": ["API design", "authentication", "database"],
    "content": "You are a backend developer with deep expertise...",
    "activation_score": 0.92,
    "related_skills": [
      {
        "id": "8b4c3d2e-...",
        "name": "security-auditor",
        "description": "Security review and vulnerability analysis",
        "category": "04-quality-security",
        "tags": ["security", "auth", "jwt"]
      }
    ]
  }
}

​
POST /api/skills/activate

Stimulus propagation: given a task description, finds and ranks the most relevant skills using a weighted scoring algorithm across tags, concepts, and description text. This is the primary method used by the Genie agent and Goose CLI at session start — it surfaces the most applicable skills for JIT hydration into the agent’s context. 
POST /api/skills/activate
Content-Type: application/json

​
Body

​
task
string
required
A natural-language description of the task to activate skills for. The endpoint scores all 191 skills against this description and returns the top matches.
​
limit
number
Maximum number of skills to return. Default: 5.
{
  "task": "Build a REST API endpoint with JWT authentication and Directus integration",
  "limit": 5
}

​
Scoring algorithm

Each skill receives a score based on three factors:
SignalWeightMethod
Tag match+0.3 per matching tagChecks if any skill tag appears in the task string
Concept match+0.4 per matching conceptChecks if any skill concept appears in the task string
Description overlap+0.5 per word overlapTokenizes both strings, scores shared terms
Skills are sorted by score descending. The top limit skills are returned.

​
Response

​
success
boolean
true when activation ran successfully.
​
activated_skills
array
Array of skill objects, sorted by relevance score descending.
{
  "success": true,
  "activated_skills": [
    {
      "id": "7a3f2c1b-...",
      "name": "backend-developer",
      "score": 1.4,
      "description": "Expert in Express, Node.js, REST API design, and Prisma ORM",
      "category": "01-core-development",
      "tags": ["express", "node", "rest", "prisma"]
    },
    {
      "id": "c9d8e7f6-...",
      "name": "security-auditor",
      "score": 0.9,
      "description": "Security review and vulnerability analysis",
      "category": "04-quality-security",
      "tags": ["security", "auth", "jwt"]
    }
  ]
}

​
Skill categories

Category keyDomain
01-core-developmentBackend, frontend, React, JavaScript, Python
02-language-specialistTypeScript, Node.js deep-dives
03-infrastructureDevOps, Docker, PM2, databases, deployment
04-quality-securitySecurity auditing, code review, QA, testing
05-data-aiLLM architecture, prompt engineering, NLP, ML
06-developer-experienceMCP development, documentation, Git, build tooling
07-specialized-domainsPer-task specialist roles
08-business-productContent marketing, SEO, legal
09-meta-orchestrationMulti-agent coordination, error rollup
10-research-analysisResearch, trend analysis, market intelligence
11-genie-user-skillsGenieHelper platform execution skills

​
Skill object fields

​
id
string
Directus UUID for the skill record.
​
name
string
Slug identifier. Used for lookup by name (e.g., backend-developer).
​
category
string
One of the 11 category keys above.
​
description
string
Short description of the skill’s domain and expertise.
​
content
string
The full skill prompt content injected into the agent’s context window during JIT hydration.
​
tags
array
Array of tag strings used for filtering and scoring.
​
concepts
array
Higher-level concept terms used by the stimulus propagation scorer.
​
activation_score
number
Baseline activation score (0–1). Used as a tie-breaker in stimulus propagation.

Build docs developers (and LLMs) love

Get started for freeTalk to us