Skip to main content
The SkillRegistry manages collections of markdown-based skills and provides search, discovery, and smart loading modes. It’s ideal for building prompt libraries that agents can draw from.

​
Quick Example

from definable.agent import Agent
from definable.model import OpenAIChat
from definable.skill import SkillRegistry

# Load built-in library (8 markdown skills)
registry = SkillRegistry()

# Auto mode: picks eager or lazy based on collection size
agent = Agent(
  model=OpenAIChat(id="gpt-4o"),
  skill_registry=registry,
)

​
Markdown Skills

A markdown skill is a .md file with YAML frontmatter that provides methodology and instructions — no tools, just expertise. 
---
name: code-review
description: Systematic code review with severity-ranked findings
version: 1.0.0
tags: [code, review, quality]
---

## When to Use
Use this skill when reviewing code changes.

## Steps
1. Understand the context and purpose of the change
2. Check for correctness and edge cases
3. Evaluate code style and maintainability
4. Rate findings by severity: critical > major > minor > nit

## Output Format
- Summary of changes
- Findings list with severity ratings
- Overall assessment

​
Frontmatter Fields

​
name
str
required
Unique identifier for the skill.
​
description
str
Short description shown in the skill catalog.
​
version
str
default:"1.0.0"
Semantic version.
​
tags
List[str]
Searchable tags for discovery.
​
requires_tools
List[str]
Tool names this skill expects to be available.
​
author
str
Skill author.
When loaded, the markdown body is wrapped in <skill name="..."> tags in the system prompt for clear delineation.

​
Loading Skills

​
From a File

from definable.skill import SkillLoader

skill = SkillLoader.load_file(Path("my-skill.md"))

​
From a String

skill = SkillLoader.parse("""
---
name: my-skill
description: A custom skill
tags: [custom]
---

## Instructions
Do the thing.
""")

​
From a Directory

skills = SkillLoader.load_directory(Path("./my-skills/"))
# Recursively loads all .md files; logs warnings and skips failures

​
SkillRegistry Constructor

from definable.skill import SkillRegistry

registry = SkillRegistry(
  skills=None,
  directories=None,
  include_library=True,
)
​
skills
List[MarkdownSkill]
Explicit skills to include (highest priority, overrides duplicates).
​
directories
List[Path]
Custom directories to load markdown skills from.
​
include_library
bool
default:true
Include the 8 built-in library skills (code-review, data-analysis, debug-code, explain-concept, plan-project, summarize-document, web-research, write-report).
Loading order (last wins for duplicate names): built-in library → custom directories → explicit skills.

​
Methods

MethodReturn TypeDescription
list_skills()List[MarkdownSkillMeta]All skill metadata, sorted by name
get_skill(name)Optional[MarkdownSkill]Look up a skill by name
search_skills(query)List[MarkdownSkill]Search by keyword/tag (scored: name=3, tag=2, desc=1)
as_eager()List[Skill]Return all skills as a list — all injected into system prompt
as_lazy()SkillReturn a single wrapper skill with catalog table + read_skill tool

​
Eager vs. Lazy Mode

The registry can provide skills in two modes:

​
Eager Mode

agent = Agent(model=model, skills=registry.as_eager())
All skill instructions are injected into the system prompt at once. Best for small collections (fewer than 15 skills) where the token overhead is acceptable.

​
Lazy Mode

agent = Agent(model=model, skills=[registry.as_lazy()])
Injects a catalog table listing all available skills, plus a read_skill(skill_name) tool. The model loads skills on demand. Best for large collections (15+ skills) to avoid bloating the prompt.

​
Auto Mode

When using skill_registry= on the Agent, the mode is chosen automatically: 
agent = Agent(model=model, skill_registry=registry)
# len(registry) <= 15 → eager
# len(registry) > 15  → lazy

​
Built-in Library Skills

NameDescriptionTags
code-reviewSystematic code review with severity-ranked findingscode, review, quality
data-analysisStructured data analysis with statistical reasoningdata, analysis, statistics
debug-codeMethodical debugging with hypothesis testingdebug, code, troubleshooting
explain-conceptClear explanation of technical conceptsexplain, concept, education
plan-projectProject planning with scope/timeline/risksplan, project, organization
summarize-documentDocument summarization with key insightssummarize, document, writing
web-researchDeep research using web search + source synthesisresearch, web, search
write-reportReport writing with structure/clarity/evidencewrite, report, documentation