Current state

Reasonix already reads Claude-format skills from .claude/skills/<name>/SKILL.md and ~/.claude/skills/ — this is documented and works great for simple skills like OpenSpec workflows.

The config guide confirms the folder layout is supported:

"Two equivalent shapes: a flat <name>.md, or a <name>/SKILL.md folder when you want to colocate attachments."

The gap: references/ on-demand loading

The full Anthropic Skills spec supports a references/ subdirectory with on-demand loading via [[references/xxx]] wikilinks in SKILL.md. This is critical for skills that ship depth material — the SKILL.md stays lean (reducing per-trigger token cost), and the agent loads references only when needed.

A typical Anthropic Skill layout:

my-skill/
├── SKILL.md                    # short: frontmatter + when-to-use + approach
└── references/                 # depth material, loaded on demand
    ├── methodology.md
    ├── decision-rules.md
    └── examples.md

Today, Reasonix reads SKILL.md but does not appear to resolve [[references/xxx]] links — the agent sees dead wikilinks instead of loading the referenced files. This means skills from the Anthropic ecosystem that rely on references/ lose their depth material when used with Reasonix.

Concrete use case: OpenKB → Reasonix

OpenKB is an open-source tool that compiles documents into a structured wiki and distills them into redistributable Anthropic Skills. A user who runs:

openkb skill new my-expert "Reason about attention mechanisms in transformer architectures"

...gets a skill at output/skills/my-expert/ with SKILL.md + 2–5 reference files. Installing it into Reasonix should be one copy:

cp -r output/skills/my-expert ~/.claude/skills/

Today, the SKILL.md loads but the references/ are inert — the Core Decision Rules and depth examples that make the skill valuable are invisible to Reasonix.

Proposed behavior

When Reasonix loads a Claude-format skill from a directory that contains references/, and the SKILL.md body contains [[references/<slug>]] wikilinks:

1. The SKILL.md body is loaded as the skill prompt (already works)
2. When the agent encounters [[references/<slug>]], it resolves to references/<slug>.md relative to the skill directory
3. The referenced file is read and its content made available to the agent on demand (same semantics as Claude Code)

This is purely additive — single-file skills and skills without references/ are unaffected.

Alternatives / partial workarounds

If full references/ on-demand support is not feasible short-term, even a simpler approach would help:

• Option A: At skill load time, detect references/ and append all reference files to the SKILL.md body (with ## References: <slug> headers). This trades per-trigger token cost for completeness.
• Option B: Add a CLI helper: reasonix skill import <path-to-anthropic-skill> that converts the Anthropic format to Reasonix native format (inlining references, mapping frontmatter fields).

Related

• OpenKB Skill Factory produces skills following the Anthropic Skills spec exactly
• OpenSpec already works on Reasonix (documented in README) but uses flat SKILL.md without references/
• Claude Code, Codex CLI, Gemini CLI, and Cursor all support references/ on-demand loading natively