feat(wren): serve agent skills and reference docs from the CLI

[PaulChen79]

Summary

Move the source of truth for agent workflow guides, reference docs, and prompt templates into the wren CLI. Replace the previous "five fat skills installed into the agent's skill directory" model with a single ~50-line discovery stub plus three new content-delivery commands: wren skills get/list, wren docs get/list, wren ask --guided/--direct.

Why: The old model installed ~/.claude/skills/wren-* markdown directly. That bundle drifted from the installed CLI (the markdown referenced commands and flags that didn't always match the user's pip install-ed version), and the agent loaded all five skills at session start whether it needed them or not. The new model ships the content inside the wrenai wheel itself, so the version an agent reads always matches the installed CLI, and the agent only pays for what it fetches.

Design discussion: .tmp/prds/2026-05-17-agent-cli-additive-refactor-zh.md (and English mirror). Modeled after vercel-labs/agent-browser's single-stub pattern.

What's new

CLI surfaces

# Workflow guides (5 bundled skills)
wren skills list
wren skills get onboarding              # entry point: setup + first query
wren skills get usage                   # day-to-day querying
wren skills get generate-mdl            # generate MDL from a DB schema
wren skills get dlt-connector           # SaaS via dlt → DuckDB → Wren project
wren skills get enrich-context          # business context (units, enums, cubes)
wren skills get <name> --full           # inline the skill's references/
wren skills get dlt-connector --script introspect_dlt   # fetch bundled script

# Reference docs (15 mirrored from docs/core/)
wren docs list
wren docs get <reference>               # connect, mdl, cubes, installation, quickstart, ...

# Prompt shaping (no execution — just renders to stdout)
wren ask "<question>" --guided          # strict task flow for weaker LLMs
wren ask "<question>" --direct          # minimal wrapping for stronger LLMs

wren ask has no default mode — the user must pick --guided or --direct (silently changing a default would alter agent behavior across an upgrade).

Discovery stub

skills/wren/SKILL.md is now a ~50-line stub that teaches the agent to fetch everything else from the CLI. npx skills add Canner/WrenAI installs it.

The five previously-shipped fat skill directories (skills/wren-onboarding, wren-usage, wren-generate-mdl, wren-enrich-context, wren-dlt-connector) have been deleted as part of this PR. They were briefly retained as 10-line redirect stubs during the migration; once the discovery stub + CLI delivery were validated, the redirects were dropped (commit 820b1f07). tests/unit/test_skill_stubs.py::test_deprecated_dirs_removed guards against regenerating them.

Reference docs mirror

docs/core/ is the source of truth; core/wren/src/wren/docs_content/refs/ is a synced mirror packaged into the wheel. scripts/sync_docs_content.py keeps them in lockstep: --check flags drift (including orphan files), sync rewrites the mirror. A new docs-sync-check CI job runs --check on every PR, and docs/core/** is part of the workflow's trigger paths so source-doc edits actually fire the check.

Commits

#	Commit	Scope
1	5008f0b1 feat(wren): add wren skills content delivery (get/list) with bundled usage skill	Tracer bullet: end-to-end content delivery infra + first lifted skill (usage)
2	30266608 feat(wren): complete wren skills — 4 more skills + --full + --script	Lift the remaining 4 skills, add --full/--script flags
3	e7c479b3 feat(wren): add wren docs get/list reference delivery + docs sync	wren docs get/list + 15 reference mirrors + sync_docs_content.py
4	ad8ce56a feat(wren): add wren ask <prompt> --guided|--direct prompt shaping	wren ask with two template modes; no default
5	5782a334 feat(skills): single discovery stub + deprecate the five fat skills	New skills/wren/SKILL.md stub + temporary redirect stubs + marketplace.json/install.sh rewritten
6	9ba96f6f test(wren): guard that every wren <cmd> in served content is real	CI guard — validates ~440 wren <cmd> invocations across served content against the real Typer command tree
7	2ab0842d docs: align README + docs/core with new CLI-served skills model	README quickstart + docs/core/reference/{cli,skills}.md brought in sync
8	854965d1 fix(ci): drop obsolete versions.json check and lint lifted dlt script	Remove .github/workflows/skills-check.yml (skill version-pinning is gone); ruff-fix the lifted introspect_dlt.py
9	1a3cd6ad fix(wren): served-content guard now catches unknown subcommands	Close a false-negative in the guard (CodeRabbit major finding); fix one prose typo it caught
10	820b1f07 chore(skills): remove deprecated redirect-stub directories	Close the redirect window; delete the 5 deprecated dirs; add test_deprecated_dirs_removed regression guard
11	66ca64c3 fix(ci): wire new tests into CI; harden served-content guard; declare .py artifacts	goldmedal review follow-ups: pytestmark + discovery-stub scan + docs-sync CI gate + explicit .py artifact + version-stable cmd.commands walk

Each commit was independently code-reviewed before landing. Findings from review (regex over-trim, missing orphan detection, PyPI rename regression, multi-line backslash-continuation gap, unknown-subcommand false-negative) were folded back into the same commit via --amend while the branch was unpushed; review surfaced after the PR opened landed as new follow-up commits.

File layout

core/wren/src/wren/
├── skills_cli.py              # `wren skills` Typer subapp
├── skills_delivery.py         # importlib.resources helpers (get_skill, get_script, ...)
├── skills_content/            # bundled skills, packaged via hatch artifacts glob
│   ├── onboarding/SKILL.md
│   ├── usage/{SKILL.md, references/{memory,wren-sql}.md}
│   ├── generate-mdl/SKILL.md
│   ├── enrich-context/{SKILL.md, references/{gap_catalog,cube_proposals}.md}
│   └── dlt-connector/{SKILL.md, references/dlt_sources.md, scripts/introspect_dlt.py}
├── docs_cli.py                # `wren docs` extracted from cli.py + extended with get/list
├── docs_delivery.py
├── docs_content/refs/         # 15 mirrored reference docs
├── ask.py                     # render(template, prompt) — pure string substitution
├── ask_cli.py                 # `wren ask` Typer command (mutually-exclusive flags)
└── ask_templates/{guided,direct}.md.tmpl

scripts/sync_docs_content.py   # bidirectional sync + drift detector (CI gate)
skills/wren/SKILL.md           # discovery stub (sole entry point)

pyproject.toml extends the wheel artifacts glob to include src/wren/skills_content/**/*.md, src/wren/skills_content/**/*.py, src/wren/docs_content/refs/*.md, and src/wren/ask_templates/*.tmpl. Verified via unzip -l dist/wrenai-*.whl that every served file ships.

Migration

Before	After
npx skills add Canner/WrenAI --skill '*'	npx skills add Canner/WrenAI (single discovery stub)
/wren-onboarding slash command	Agent runs wren skills get onboarding
~/.claude/skills/wren-usage/SKILL.md (installed locally)	wren skills get usage (fetched from wheel)
wren-engine (PyPI)	wrenai (renamed in parent commit; all install commands updated)
skills/wren-{onboarding,usage,…}/ directories in this repo	Deleted — agents fetch via wren skills get

Verification

• uv run pytest tests/unit/ -m unit (the exact CI invocation) — 325 passed, 38 skipped. The new 44 tests are now collected (previously deselected by -m unit).
• tests/unit/test_cube_cli.py carries 5 pre-existing failures locally — traced to a missing cube_query_to_sql symbol in the locally installed wren-core-py==0.1.0 PyPI wheel; CI builds the wheel from source so they pass there.
• New test suites: tests/unit/test_skills_cli.py, test_docs_cli_get.py, test_ask_cli.py, test_skill_stubs.py, test_served_content_guard.py (the CI guard).
• The served-content guard introspects the real Typer command tree (via stable cmd.commands API) and walks every wren <cmd> snippet in skills_content/, docs_content/, ask_templates/, and the discovery stub at skills/wren/SKILL.md — any forward reference to a non-existent command, flag, or subcommand fails the build.
• Verified wren skills get usage works both in editable install (uv sync) and from a freshly built wheel (uv pip install dist/wrenai-*.whl).
• uv build produces a wheel that bundles every .md / .py / .tmpl referenced above, via explicit artifacts globs.
• python core/wren/scripts/sync_docs_content.py --check → docs_content in sync (15 references)., now wired into CI as the docs-sync-check job.

Test plan

• CI: full pytest matrix (linux + macos)
• CI: test_served_content_guard.py passes on the published wheel
• CI: docs-sync-check job runs (and stays green) on PRs that touch docs/core/**
• Downstream: pip install wrenai in a fresh venv, then wren skills list && wren skills get usage — should print the workflow guide
• Downstream: npx skills add Canner/WrenAI installs skills/wren/SKILL.md (the new stub) into Claude Code's skill directory, and the agent successfully fetches wren skills get onboarding on prompt

🤖 Generated with Claude Code

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

This PR replaces the prior on-disk skill bundle with a CLI-served discovery-stub model, adds prompt templating for wren ask, bundles reference docs/skills into the wheel, provides a sync/check script, wires new wren docs and wren skills subcommands, and adds tests validating served content and CLI references.

Changes

CLI-Served Skill & Docs Distribution System

Layer / File(s)	Summary
Ask prompt system core/wren/src/wren/ask.py, core/wren/src/wren/ask_cli.py, core/wren/src/wren/ask_templates/*.md.tmpl	wren ask with required single-mode --guided/--direct, template-based render(mode, prompt), and placeholder substitution.
Reference docs delivery core/wren/src/wren/docs_delivery.py, core/wren/src/wren/docs_cli.py, core/wren/scripts/sync_docs_content.py	Curated REFERENCE_SOURCES mapping, list_references()/get_reference(), wren docs CLI (connection-info, list, get), and sync/check script to mirror docs into wheel package data.
Skills delivery system core/wren/src/wren/skills_delivery.py, core/wren/src/wren/skills_cli.py, core/wren/src/wren/skills_content/*/SKILL.md	Wheel-packaged skill content serving: list_skills(), get_skill(full), get_script(), and wren skills CLI with --full/--script. Includes skill guides for onboarding, usage, generate-mdl, enrich-context, dlt-connector.
CLI wiring core/wren/src/wren/cli.py	Mounts docs_app, registers ask and skills_app, centralizing CLI subapps.
Reference documentation core/wren/src/wren/docs_content/refs/*.md	Adds many reference docs (architecture, MDL, context, memory, quickstart, connect, dbt-integration, manage-project, operational, refine, cubes, etc.).

Skill Distribution Model and Wheel Configuration

Layer / File(s)	Summary
Discovery stub & distribution metadata skills/wren/SKILL.md, skills/index.json, skills/install.sh, skills/.claude-plugin/marketplace.json	Introduces wren discovery stub, updates index.json to discovery + deprecated redirect stubs, simplifies install script to install only stub, updates marketplace metadata, removes versions.json and check-versions.sh.
Wheel build configuration core/wren/pyproject.toml	Includes skill/docs Markdown and ask templates in wheel artifacts globs for packaging.

Testing and Quality Gates

Layer / File(s)	Summary
Ask and docs tests core/wren/tests/unit/test_ask_cli.py, core/wren/tests/unit/test_docs_cli_get.py	Unit tests for wren ask rendering/flags and wren docs list/get behavior, content matching, and CI sync gate.
Skills tests core/wren/tests/unit/test_skills_cli.py	Tests for wren skills list/get, --full inlining, script retrieval, and negative paths.
Served-content guard & stub tests core/wren/tests/unit/test_served_content_guard.py, core/wren/tests/unit/test_skill_stubs.py	Scans served content for wren ... invocations, validates command-paths and long flags against the live CLI, and asserts distribution stub expectations.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• Canner/WrenAI#1102: README Quickstart/branding edits overlap.
• Canner/WrenAI#2234: Related README framing updates.
• Canner/WrenAI#2262: Related skills/index.json and distribution changes.

Suggested reviewers

• goldmedal
• douenergy
• chilijung

"🐰
I taught the CLI to fetch and sing,
Docs bundled tight, prompts trimmed with spring.
One stub to rule the agent's gentle quest,
Hop in, install, and let the skills do the rest."

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/refactor-cli

[coderabbitai]

Actionable comments posted: 4

🧹 Nitpick comments (1)

core/wren/src/wren/docs_content/refs/quickstart.md (1)

180-187: ⚡ Quick win

Add language specifiers to fenced code blocks.

Several code blocks are missing language identifiers, which can affect syntax highlighting and rendering. Consider adding appropriate language specifiers:

• Lines 180-187, 298-317: directory tree structures → add text or plaintext
• Lines 220-223, 249-259: user prompts/natural language queries → add text if highlighting is desired, or leave plain if the unmarked style is intentional

📝 Proposed fix for language specifiers

-```
+```text
 ~/jaffle-wren/
 ├── wren_project.yml        # project metadata
 ...

For user prompts at lines 220, 249, 253, 257:

-```
+```text
 Use the wren-generate-mdl skill to explore the jaffle_shop database
 ...

Also applies to: 220-223, 249-259, 298-317

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@core/wren/src/wren/docs_content/refs/quickstart.md` around lines 180 - 187,
Add language specifiers to the fenced code blocks that currently lack them: for
the directory-tree block that begins with "~/jaffle-wren/" (the tree listing
wren_project.yml, models/, views/, relationships.yml, instructions.md) and for
the natural-language prompt blocks such as the ones that start with "Use the
wren-generate-mdl skill to explore the jaffle_shop database" and other user
prompt examples; update each opening fence from ``` to ```text (or ```plaintext)
so these blocks are explicitly marked as plain text for proper syntax
highlighting and rendering.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@core/wren/src/wren/docs_content/refs/manage-project.md`:
- Line 173: In manage-project.md fix the broken link by replacing the current
'./osi.md' target with the correct OSI guide location: update the markdown link
in the table row containing "OSI `semantic_model.yaml`" so it points to the
actual OSI guide file in the repository (replace the './osi.md' href with the
repo's OSI guide path) ensuring the link resolves from manage-project.md; locate
the link by searching for the literal './osi.md' in the file.

In `@core/wren/src/wren/docs_content/refs/mdl.md`:
- Line 237: The table row for `properties` in mdl.md is missing the Type column,
breaking the 4-column table; update the row for the `properties` entry to
include the missing Type cell (e.g., add a Type like `object` or the correct
type) so the row has four pipe-separated cells matching the header and restoring
proper table alignment for the `properties` row.

In `@core/wren/src/wren/skills_delivery.py`:
- Around line 72-79: get_script currently picks the first match from
scripts_dir.iterdir() and is non-deterministic when multiple files share the
same stem; modify get_script(name: str, script: str) to collect all matching
files whose stem equals script, and then: if none found raise
ScriptNotFoundError, if more than one found raise a new ScriptAmbiguousError
(include candidate filenames in the message) so callers get a deterministic
error instead of unpredictable behavior; additionally update _script_stems() to
return a sorted list of unique stems (deduplicate with a set and sort) so
listings are stable and don't show duplicates.

---

Nitpick comments:
In `@core/wren/src/wren/docs_content/refs/quickstart.md`:
- Around line 180-187: Add language specifiers to the fenced code blocks that
currently lack them: for the directory-tree block that begins with
"~/jaffle-wren/" (the tree listing wren_project.yml, models/, views/,
relationships.yml, instructions.md) and for the natural-language prompt blocks
such as the ones that start with "Use the wren-generate-mdl skill to explore the
jaffle_shop database" and other user prompt examples; update each opening fence
from ``` to ```text (or ```plaintext) so these blocks are explicitly marked as
plain text for proper syntax highlighting and rendering.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: d461247b-94c9-4365-b9a8-44607dfabbe6

📥 Commits

Reviewing files that changed from the base of the PR and between d43582c and 854965d.

📒 Files selected for processing (61)

• .github/workflows/skills-check.yml
• README.md
• core/wren/pyproject.toml
• core/wren/scripts/sync_docs_content.py
• core/wren/src/wren/ask.py
• core/wren/src/wren/ask_cli.py
• core/wren/src/wren/ask_templates/direct.md.tmpl
• core/wren/src/wren/ask_templates/guided.md.tmpl
• core/wren/src/wren/cli.py
• core/wren/src/wren/docs_cli.py
• core/wren/src/wren/docs_content/refs/architecture.md
• core/wren/src/wren/docs_content/refs/connect.md
• core/wren/src/wren/docs_content/refs/correctness.md
• core/wren/src/wren/docs_content/refs/cubes.md
• core/wren/src/wren/docs_content/refs/dbt-integration.md
• core/wren/src/wren/docs_content/refs/installation.md
• core/wren/src/wren/docs_content/refs/manage-project.md
• core/wren/src/wren/docs_content/refs/mdl.md
• core/wren/src/wren/docs_content/refs/memory-system.md
• core/wren/src/wren/docs_content/refs/model.md
• core/wren/src/wren/docs_content/refs/operational.md
• core/wren/src/wren/docs_content/refs/quickstart.md
• core/wren/src/wren/docs_content/refs/refine.md
• core/wren/src/wren/docs_content/refs/what-is-context.md
• core/wren/src/wren/docs_content/refs/what-is-mdl.md
• core/wren/src/wren/docs_delivery.py
• core/wren/src/wren/skills_cli.py
• core/wren/src/wren/skills_content/dlt-connector/SKILL.md
• core/wren/src/wren/skills_content/dlt-connector/references/dlt_sources.md
• core/wren/src/wren/skills_content/dlt-connector/scripts/introspect_dlt.py
• core/wren/src/wren/skills_content/enrich-context/SKILL.md
• core/wren/src/wren/skills_content/enrich-context/references/cube_proposals.md
• core/wren/src/wren/skills_content/enrich-context/references/gap_catalog.md
• core/wren/src/wren/skills_content/generate-mdl/SKILL.md
• core/wren/src/wren/skills_content/onboarding/SKILL.md
• core/wren/src/wren/skills_content/usage/SKILL.md
• core/wren/src/wren/skills_content/usage/references/memory.md
• core/wren/src/wren/skills_content/usage/references/wren-sql.md
• core/wren/src/wren/skills_delivery.py
• core/wren/tests/unit/test_ask_cli.py
• core/wren/tests/unit/test_docs_cli_get.py
• core/wren/tests/unit/test_served_content_guard.py
• core/wren/tests/unit/test_skill_stubs.py
• core/wren/tests/unit/test_skills_cli.py
• docs/core/reference/cli.md
• docs/core/reference/skills.md
• skills/.claude-plugin/marketplace.json
• skills/AUTHORING.md
• skills/README.md
• skills/SKILLS.md
• skills/check-versions.sh
• skills/index.json
• skills/install.sh
• skills/versions.json
• skills/wren-dlt-connector/SKILL.md
• skills/wren-dlt-connector/evals/evals.json
• skills/wren-enrich-context/SKILL.md
• skills/wren-generate-mdl/SKILL.md
• skills/wren-onboarding/SKILL.md
• skills/wren-usage/SKILL.md
• skills/wren/SKILL.md

💤 Files with no reviewable changes (4)

• skills/wren-dlt-connector/evals/evals.json
• .github/workflows/skills-check.yml
• skills/versions.json
• skills/check-versions.sh

[goldmedal]

Review findings

Functionally solid and low-risk (no Rust / ibis-server / PyO3 / MDL-schema surface touched). Findings below in severity order.

🔴 High — the new tests (incl. the served-content guard) don't run in CI

CI runs uv run pytest tests/unit/ -v -m unit (wren-ci.yml). The unit marker is opt-in via module-level pytestmark = pytest.mark.unit (e.g. tests/unit/test_config.py); conftest.py only registers the marker, there's no path-based auto-marking. None of the 5 new test modules declare it:

• test_served_content_guard.py, test_skills_cli.py, test_docs_cli_get.py, test_ask_cli.py, test_skill_stubs.py

Verified against the built wheel: pytest <those 5 files> -m unit → 44 deselected. They pass only when run without the filter — which masks the gap. So the served-content guard and all new CLI tests are silently skipped in CI.
Fix: add pytestmark = pytest.mark.unit to each of the 5 modules.

🟡 Medium — drift hole: the discovery stub is shipped to users but not guarded

npx skills add installs skills/wren/SKILL.md to users' local skill dirs (~/.claude/skills/wren/). The stub hard-codes top-level CLI command references (wren profile switch, wren context build, wren memory recall, …) that can drift from the installed CLI after an upgrade. But the served-content guard (test_served_content_guard.py) scans only skills_content/, docs_content/, and ask_templates/ — not skills/wren/SKILL.md. So the one file that actually lands on users' machines has zero CI validation; its commands are all valid today only by luck.
Fix: add skills/wren/SKILL.md to the guard's scan roots (and ideally the command references in install.sh / marketplace.json).

🟡 Medium — docs drift --check gate isn't wired into CI

scripts/sync_docs_content.py advertises a --check CI gate, but no workflow invokes it. Worse, wren-ci.yml's path filter excludes docs/core/**, so editing a source doc triggers neither the sync check nor wren-ci, and the mirror can drift silently. (All 15 mirrors are byte-identical to source today.)
Fix: add a sync_docs_content.py --check step to wren-ci and/or add docs/core/** to the trigger paths.

🟡 Medium — PR description is stale on redirect stubs

The body says the five fat skill dirs are kept as redirect stubs; the final state deletes all of them, and test_skill_stubs.py::test_deprecated_dirs_removed enforces that they stay gone. Code/tests are self-consistent — please update the PR narrative (and the Migration table / test-plan bullet).

🟢 Low — artifacts glob doesn't declare the bundled .py script

pyproject.toml artifacts list *.md / docs_content/**/*.md / ask_templates/*.tmpl but not src/wren/skills_content/**/*.py. I built the wheel and confirmed skills_content/dlt-connector/scripts/introspect_dlt.py does ship — but only via hatchling's implicit .py inclusion, not the declared glob.
Fix: add "src/wren/skills_content/**/*.py" so intent is explicit and robust to tooling changes.

🟢 Low — guard's command-tree walk is version-fragile

test_served_content_guard.py's _walk uses cmd.list_commands(ctx=None). Under the lockfile pins (typer 0.24.1 / click 8.3.1) this works; I reproduced that under typer 0.26.3 / click 8.4.1 it returns [], collapsing COMMANDS to the root and silently neutering the guard. pyproject.toml pins only typer>=0.12 (no upper bound). test_command_tree_loaded would catch the regression loudly — but only if it runs (see High finding).
Fix: iterate cmd.commands directly, or set a typer upper bound.

---

Verified locally: wheel builds and bundles all 17 docs/skills/ask files + the script; delivery modules import and work from the installed wheel; all 15 docs mirrors match source; all 44 new tests pass under the lockfile-pinned typer/click; commits follow conventional format.

[goldmedal]

Thanks @PaulChen79 look great 👍