How to Configure the Skills Library and Load Custom Skills in AutoResearchClaw

AutoResearchClaw loads skills from five hierarchical sources—built-in, user-level, project-level, MetaClaw, and config-specified directories—and merges them via the SkillRegistry class to inject domain-specific knowledge into LLM prompts.

The dynamic skills library in AutoResearchClaw allows you to augment the research pipeline with domain-specific prompts, code templates, and reference materials. When you configure the skills library and load custom skills in AutoResearchClaw, the system automatically matches relevant capabilities to each pipeline stage based on context keywords and stage applicability.

Understanding the Skills Library Architecture

AutoResearchClaw’s skill system is orchestrated by the SkillRegistry class in researchclaw/skills/registry.py. This registry aggregates skills from multiple sources through a hierarchical loading mechanism implemented in researchclaw/pipeline/_helpers.py.

The Five Load Order Sources

The _get_skill_registry() function gathers directories in the following priority order:

Load order	Source	Default location
1	Built-in skills	researchclaw/skills/builtin/
2	User-level skills	~/.researchclaw/skills/
3	Project-level skills	<repo-root>/.claude/skills/
4	MetaClaw cross-run skills	~/.metaclaw/skills/
5	Config-specified custom/external dirs	Paths listed under skills.custom_dirs or skills.external_dirs in config.researchclaw.yaml

Core Components

Component	Role	Source file
Skill	Dataclass storing name, description, body, and metadata	researchclaw/skills/schema.py
load_skill_from_skillmd()	Parses SKILL.md files (YAML front-matter + markdown body)	researchclaw/skills/loader.py
load_skill_file()	Parses legacy .yaml / .json skill files	researchclaw/skills/loader.py
load_skills_from_directory()	Recursively discovers both SKILL.md and legacy files	researchclaw/skills/loader.py
SkillRegistry	Registers, queries, matches, and formats skills for prompt injection	researchclaw/skills/registry.py
match_skills()	Ranks skills using trigger-keywords, stage applicability, and description fallback	researchclaw/skills/matcher.py

Configuring Custom Skills Directories

To add external skill repositories, edit your config.researchclaw.yaml file and define the skills section:

skills:
  enabled: true
  custom_dirs:
    - "/path/to/my/extra/skills"
    - "/another/skills/dir"
  external_dirs:
    - "/opt/third-party/skills"
  max_skills_per_stage: 5
  fallback_matching: true

Key configuration parameters:

• enabled – Boolean toggle to activate or deactivate the entire skills system (default: true).
• custom_dirs – List of absolute paths to directories containing skill definitions.
• external_dirs – Additional paths treated separately from custom directories but loaded identically.
• max_skills_per_stage – Integer limiting how many skills are injected per pipeline stage (default: 3).
• fallback_matching – Enables description-based matching when trigger keywords are absent (default: true).

Creating and Loading Custom Skills

AutoResearchClaw supports two skill formats. The modern agentskills.io format uses SKILL.md files, while legacy formats use standalone YAML or JSON files.

SKILL.md Format (Recommended)

Create a directory named after your skill and place a SKILL.md file inside:

my-awesome-skill/
  SKILL.md

The SKILL.md file contains YAML front-matter followed by a markdown body:

---
name: my-awesome-skill
description: Extracts domain-specific keyphrases using spaCy
category: domain
applicable_stages: [9, 10]
trigger_keywords: [nlp, keyphrase, extraction]
priority: 1.0
---

## Usage

Use this skill when analyzing natural language text...

Legacy Format

Alternatively, place .yaml or .json files directly in the skills directory. The loader in researchclaw/skills/loader.py automatically prioritizes SKILL.md over legacy files with identical base names.

How Skill Matching Works

During pipeline execution, the _get_skill_registry() helper constructs a context string combining the stage name and topic:

context = f"{stage_name} {topic}"
matched = registry.match(context, stage_name)
prompt_snippet = registry.export_for_prompt(matched)

The match_skills() function in researchclaw/skills/matcher.py scores each skill based on:

• Stage applicability – Skills with empty applicable_stages match all stages; otherwise, they match only specified stage numbers.
• Keyword overlap – Token overlap between trigger_keywords and the context string.
• Description fallback – Semantic matching using the skill description (weighted at 0.5×) when keywords are missing.
• Priority boost – Manual priority values in skill metadata override default rankings.

The registry returns up to max_skills_per_stage skills, which are then formatted into the LLM prompt via export_for_prompt().

Programmatic Usage Examples

Manual Registry Creation

Instantiate the SkillRegistry directly in Python to bypass the singleton pattern:

from researchclaw.skills.registry import SkillRegistry

registry = SkillRegistry(
    custom_dirs=[
        "/home/alice/.researchclaw/skills",
        "/my/project/.claude/skills",
        "/opt/third-party/skills",
    ],
    auto_match=True,
    max_skills_per_stage=5,
    fallback_matching=True,
)

print(f"Loaded {registry.count()} skills")
for skill in registry.list_all():
    print(f"- {skill.name} (category={skill.category})")

Matching and Prompt Injection

Inject matched skills into a specific pipeline stage:

stage = "experiment_design"
topic = "Learning rate schedules for transformer training"
context = f"{stage} {topic}"

matched = registry.match(context, stage)
prompt_text = registry.export_for_prompt(matched, max_chars=4000)

print("=== Injected Skills ===")
print(prompt_text)

Managing Skills via CLI

AutoResearchClaw provides a dedicated CLI interface for skill management defined in researchclaw/cli.py.

List all available skills:

researchclaw skills list

Install a skill from a local directory:

researchclaw skills install /tmp/my-skill

Validate a skill file before installation:

researchclaw skills validate /tmp/my-skill/SKILL.md

Summary

• AutoResearchClaw merges skills from five hierarchical sources: built-in, user (~/.researchclaw/skills/), project (.claude/skills/), MetaClaw (~/.metaclaw/skills/), and config-specified directories.
• The SkillRegistry class in researchclaw/skills/registry.py serves as the central hub for loading, matching, and exporting skills.
• Configure custom directories via skills.custom_dirs and skills.external_dirs in config.researchclaw.yaml.
• Use SKILL.md files with YAML front-matter for modern skill definitions, or legacy YAML/JSON for backward compatibility.
• The match_skills() algorithm ranks candidates by stage applicability, keyword overlap, description similarity, and priority metadata.
• Control injection limits with max_skills_per_stage and enable fuzzy matching with fallback_matching.

Frequently Asked Questions

How do I force the skills registry to reload after adding new files?

The registry is lazily instantiated by _get_skill_registry() in researchclaw/pipeline/_helpers.py. To reload skills without restarting the process, create a new SkillRegistry instance manually with updated custom_dirs, or restart the Python process to trigger the singleton refresh.

Can I override built-in skills with custom versions?

Yes. Because user-level and project-level directories load after the built-in directory, placing a skill with the same name in ~/.researchclaw/skills/ or .claude/skills/ will shadow the packaged default. The loader prioritizes skills found in later load-order directories.

What is the difference between custom_dirs and external_dirs in the configuration?

Both settings accept lists of directory paths and function identically during loading. The separation exists for organizational clarity: custom_dirs typically contains your personal skills, while external_dirs is intended for third-party or shared skill repositories. Both are merged into the registry’s search path.

How does the fallback_matching option affect skill selection?

When fallback_matching is enabled (default: true), the match_skills() function in researchclaw/skills/matcher.py uses the skill’s description text to calculate relevance scores at 0.5× weight when no trigger keywords match. This ensures skills without explicit keyword tags can still be selected based on semantic similarity to the pipeline context.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}