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

> Learn how to configure the AutoResearchClaw skills library and load custom skills efficiently. Inject domain-specific knowledge into LLM prompts programmatically.

- Repository: [AIMING Lab/AutoResearchClaw](https://github.com/aiming-lab/AutoResearchClaw)
- Tags: how-to-guide
- Published: 2026-05-28

---

**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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/researchclaw/skills/registry.py). This registry aggregates skills from multiple sources through a hierarchical loading mechanism implemented in [`researchclaw/pipeline/_helpers.py`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/config.researchclaw.yaml) |

### Core Components

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

## Configuring Custom Skills Directories

To add external skill repositories, edit your [`config.researchclaw.yaml`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/config.researchclaw.yaml) file and define the `skills` section:

```yaml
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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/SKILL.md) file inside:

```

my-awesome-skill/
  SKILL.md

```

The [`SKILL.md`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/SKILL.md) file contains YAML front-matter followed by a markdown body:

```markdown
---
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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/researchclaw/skills/loader.py) automatically prioritizes [`SKILL.md`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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:

```python
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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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:

```python
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:

```python
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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/researchclaw/cli.py).

List all available skills:

```bash
researchclaw skills list

```

Install a skill from a local directory:

```bash
researchclaw skills install /tmp/my-skill

```

Validate a skill file before installation:

```bash
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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/config.researchclaw.yaml).
- Use [`SKILL.md`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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.