Using rlat with Anthropic Skills

The integration in one line

A skill body uses Anthropic's dynamic-context primitive — a shell command that runs when the skill loads, whose output is spliced into the model's context:

!`rlat skill-context fabric-docs.rlat --query "$user_question" --top-k 5`

The shell command runs before the model sees the skill, and its stdout replaces the placeholder in context. The output is markdown with citation anchors, drift status, and confidence metrics — ready for the model to ground on.

That's the entire integration. No new YAML, no hooks, no config. The skill body calls rlat as a normal !command block.

A complete example

A .claude/skills/fabric-helper/SKILL.md file:

---
name: fabric-helper
description: Answer Microsoft Fabric questions with grounded citations
arguments:
  - user_query: "what the user is asking about Fabric"
---

# Fabric Helper

You answer Microsoft Fabric questions. The context blocks below are
grounded passages from the official docs. **Cite every claim using the
[file:offset] anchors. If no passage covers the question, say so — do
not invent details.**

## Foundational context (preset queries — always loaded)
!`rlat skill-context fabric-docs.rlat \
   --query "Microsoft Fabric workspace fundamentals" \
   --query "lakehouse vs warehouse decision criteria" \
   --top-k 3`

## Query-specific context (the user's actual question)
!`rlat skill-context fabric-docs.rlat --query "$user_query" --top-k 5`

When the user invokes this skill, three things happen:

1. Preset queries always run. "Workspace fundamentals" and "lakehouse vs warehouse" passages get pulled — the foundational concepts the skill needs to reason well.
2. The user's query gets dynamically retrieved. $user_query interpolates via Anthropic's skill-argument substitution; rlat searches the corpus for that specific question.
3. Both blocks land in the model's context with citations and drift status. The model sees passages tagged [verified] (current) or [drifted] (source has changed since build) and can self-judge whether to make strong claims.

What gets injected

rlat skill-context outputs markdown that looks like this:

<!-- rlat-mode: augment -->
> **Grounding mode: augment.** Use the passages below as primary context
> for this corpus's domain. Cite them when answering; prefer them over
> your training knowledge when the two conflict.

<!-- rlat skill-context query='lakehouse vs warehouse' band=base mode=augment
     top1_score=0.812 top1_top2_gap=0.124 source_diversity=0.83 drift_fraction=0.00 -->
## Context for: "lakehouse vs warehouse"

> **source: `docs/fabric/lakehouse-overview.md:1247+512`** — score 0.812 `[verified]`
>
> A lakehouse is a unified data store that combines the flexibility of a
> data lake with the performance characteristics of a data warehouse...

> **source: `docs/fabric/warehouse-decision.md:0+847`** — score 0.778 `[verified]`
>
> Choose a warehouse when you need...

Four things to notice:

• The grounding-mode header is the consumer LLM's directive. augment (the default) tells the model to treat the passages as primary context for this corpus's domain and prefer them over training when they conflict. See Grounding modes below.
• The per-query comment carries the confidence metrics from the retrieval. The model can read these: low source_diversity means answer cautiously (only one source backs the claim); high drift_fraction means flag the answer as potentially stale.
• Each passage carries a [source_file:char_offset+length] anchor. The skill can instruct the model to cite using exactly this format, and any consumer can quote-verify by reading the file at that offset.
• [verified] means the source file's content hash still matches what was hashed at build time. The other values are [drifted] (source moved) and [missing] (source file gone).

Trust features

The integration enforces three trust contracts as the output format itself, not as opt-in flags.

Citations are always on

Every passage carries its source anchor. There is no --no-citations flag — a skill that uses rlat skill-context is structurally incapable of grounding on uncited content.

Drift detection is always on

If any passage in the result has stale or missing source, the output begins with a warning banner:

> DRIFT WARNING: at least one passage below has stale or missing source.
> Treat content as advisory; refresh with `rlat refresh fabric-docs.rlat`
> for canonical results.

The model sees this banner. Skill instructions can tell it how to react — for example, "if you see a DRIFT WARNING, prepend your answer with 'Note: this answer may not reflect recent corpus changes.'"

Strict mode for hard requirements

Pass --strict and any drifted or missing source aborts the command non-zero:

!`rlat skill-context fabric-docs.rlat --strict --query "$user_query"`

The skill load fails. Use this when stale grounding is unacceptable — for example, a skill that answers questions where wrong-but-confident is worse than no answer.

Grounding modes

--mode controls how the consumer LLM should treat the retrieved passages. It's a directive stamped at the top of the markdown output, paired with a confidence gate that suppresses the dynamic body on weak retrieval. Three modes:

augment (default) — passages are primary context

!`rlat skill-context fabric-docs.rlat --query "$user_query"`   # mode=augment is the default

The header tells the LLM: "Use these passages as primary context. Cite them when answering. Prefer them over your training knowledge when the two conflict." The gate fires when top1_score < 0.30 (retrieval has genuinely failed for this query) or drift_fraction > 0.30 — on weak retrieval the body is replaced with a no confident evidence marker so the LLM falls back to training instead of grounding on noise.

Default mode. On the Microsoft Fabric corpus, single-shot with Sonnet 4.6 (a model that partially knows the domain): 76.5% answerable accuracy at 3.9% hallucination, versus 56.9% / 19.6% for the LLM alone — augment adds 19.6 percentage points of correct answers while cutting hallucination by 5×. The right shape for broad domain corpora where the LLM already has solid prior knowledge.

constrain — passages are the only source of truth

!`rlat skill-context compliance-rules.rlat --mode constrain --query "$user_query"`

The header tells the LLM: "Answer ONLY from these passages. If they do not cover the question, refuse explicitly — do not draw on training knowledge." There is no gate — the body always ships, and refusal on thin evidence is the LLM's job.

Single-shot on the Fabric corpus: 66.7% accuracy, 2.0% hallucination, 91.7% distractor refusal — it trades 10 points of answerable accuracy for halving the hallucination rate versus the default, and posts the highest distractor refusal in the suite. Pair with --strict so drifted source aborts the skill load entirely:

!`rlat skill-context compliance-rules.rlat --strict --mode constrain --query "$user_query"`

The right mode for compliance, regulatory, or audit work — any context where wrong-but-confident is worse than no answer.

knowledge — passages supplement training

!`rlat skill-context fabric-docs.rlat --mode knowledge --query "$user_query"`

The header tells the LLM: "These passages supplement your existing knowledge. Ground claims about this corpus's domain in them; you may draw on general knowledge for surrounding context." A lighter gate — it only suppresses on very weak retrieval (top1_score < 0.15); drift is allowed.

Use it when the corpus is partial coverage of a domain the LLM already knows reasonably well — for example, a project's bespoke conventions layered on top of general programming knowledge, where you want the LLM to use both.

Picking a mode

Token budget

rlat skill-context caps the per-query block portion of the output via --token-budget (default 4000). When multiple --query flags add up to more than the budget, later query blocks are dropped first — so the skill author's preset queries always survive, and the user's dynamic query gets truncated last. The grounding-mode directive header and the drift banner ship outside the budget; the directive is a small, fixed-size instruction the consumer LLM must always see.

!`rlat skill-context fabric-docs.rlat \
   --query "preset 1" --query "preset 2" --query "$user_query" \
   --top-k 5 --token-budget 2000`

If the budget overflows, the user-query block goes first, then preset 2, then preset 1. The first preset is always preserved — even if it alone overflows the budget. That's the skill author's bug to fix, not rlat's to silently drop.

Patterns

Preset + user (most common)

Two !command blocks, or one with multiple --query flags:

## Foundations
!`rlat skill-context fabric-docs.rlat --query "core concepts" --top-k 3`

## Query
!`rlat skill-context fabric-docs.rlat --query "$user_question"`

Decomposed user query

If the skill body extracts sub-questions from the user's input, each can hit the corpus separately:

!`rlat skill-context fabric-docs.rlat \
   --query "$entity" --query "$action" --query "$context" --top-k 3`

Strict + cross-corpus

A skill that pulls from two .rlat files runs two !command blocks, both --strict:

## Fabric context
!`rlat skill-context fabric-docs.rlat --strict --query "$user_query"`

## Power BI context
!`rlat skill-context powerbi-developer.rlat --strict --query "$user_query"`

If either is drifted, the skill load fails — refresh both before grounding.

Name-aliasing protection

--strict-names adds a second safety check: distinctive proper nouns, acronyms, and alphanumeric IDs from the query are presence-checked against the rendered passages. Default behaviour prepends a refusal directive when a token is missing; --strict-names aborts non-zero. Pair it with --strict for compliance work where wrong-named entities must never silently slide through:

!`rlat skill-context fabric-docs.rlat --strict --strict-names --query "$user_query"`

This catches the failure mode where the user's question mentions a fake or adjacent product (for example MaterializedViewExpress (MVE)) but the corpus only describes a similarly-named real entity (MaterializedLakeView (MLV)). Score-based gating cannot tell these apart on a paraphrase-rich corpus — the name check can.

Multi-hop research

For hard questions that need cross-file synthesis ("why did we pick X over Y?", "summarise the trade-offs", "what's the full history of …"), rlat ships two surfaces that run the same plan → retrieve → refine → synthesize loop:

• The deep-research skill drives the loop natively in your Claude Code session. No API key needed — your Claude subscription covers the LLM hops. This is the right pick for nearly every Claude Code user.
• The rlat deep-search CLI verb runs the same loop, exposed as a CLI command for non-Claude-Code agents, CI pipelines, and batch jobs. It requires an Anthropic API key (about $0.009–0.025 per question). Bench-validated headline: 92.2% accuracy at 0% hallucination on the Microsoft Fabric corpus; the same numbers apply to the skill version because it's the same loop.

If you're in a Claude Code session, just ask the research question; the deep-research skill triggers automatically on cross-file synthesis questions. If you're authoring a skill that runs in a non-Claude-Code agent, or you need a programmatic surface, use the CLI:

## Hard question (CLI surface — API key required)
!`rlat deep-search fabric-docs.rlat "$user_question" --format markdown`

See the API keys page for when each surface is the right pick.

rlat's skills

rlat does not ship a fixed pair of skills — several skills live under .claude/skills/, each handling a discrete capability. The table lists the skills rlat scaffolds or ships for users; a project may carry its own additional skills alongside them. The ones most relevant to working with a knowledge model:

The skills don't overlap: rlat orchestrates CLI workflows; deep-research orchestrates the multi-hop research loop in conversation; rlat-learn owns in-session capture (the subscription path to teaching the file its world). A single-hop fact question goes to rlat search; a multi-file synthesis question goes to deep-research. The CLI verb rlat deep-search — the programmatic surface for the same loop, which requires an API key — is documented inside the rlat skill, not as a separate skill, because it's just one more workflow on the rlat surface.

This design follows Anthropic's published guidance on composite workflow skills: one skill per discrete capability, positive trigger specificity, and decision-gate-driven bodies that orchestrate sub-workflows internally rather than fragmenting into many narrow-trigger skills. Sources: code.claude.com/docs/en/skills and platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices.

Performance

!command blocks run synchronously every time the skill loads. Component-level numbers, measured locally (end-to-end speed receipts are on the benchmarks page):

• Warm encoder: 12 ms per query.
• Search (FAISS HNSW): under 50 ms for corpora up to roughly 500K passages.
• Format and I/O: about 10 ms.

Two queries against a 50K-passage corpus is roughly 120 ms total — well inside the budget for an interactive skill load.

If you see slow loads, the most likely culprit is encoder cold-start (about 942 ms versus 12 ms warm). The encoder warms on first use within a session and stays warm; the second and later skill invocations are fast.

Frequently asked

Do I need to add knowledge: frontmatter?

No. The integration uses Anthropic's existing !command primitive — frontmatter additions are silently ignored by Claude Code (verified safe), but they don't drive any rlat behaviour. The !command blocks are the source of truth.

What if the corpus doesn't cover the question?

rlat returns the closest passages anyway. The model sees them with their (low) scores in the header line, and skill instructions should tell it to say "I don't know" when scores are weak.

Does this work outside Claude Code?

Yes. The Claude Agent SDK supports skills the same way. The skill body calls rlat skill-context as a !command block — same retrieval, same trust contracts.

What about static reference files?

A skill can mix !command blocks for dynamic context with relative-link references to static guides. Use rlat for anything that benefits from query-relevant retrieval; use static files for stable how-to material.

See also

• Storage modes — choosing bundled, local, or remote for your .rlat.
• CLI reference — the full rlat skill-context reference.

Where next