Documentation Skill

Soliplex publishes its full documentation as a filesystem Agent Skill, so any skills-compatible agent (Claude Code, Claude, and many others) can answer questions about installing, configuring, and operating Soliplex straight from the official docs.

Unlike the RAG database, this skill needs no embeddings, vector database, or GPU. It is plain Markdown: a SKILL.md router plus a verbatim copy of this documentation under references/, which the agent reads on demand via progressive disclosure.

How it is published

Two kinds of build are published, both as release assets named soliplex-docs-skill.tar.gz (and .zip):

Rolling builds track the docs. Every change to docs/ on main publishes an immutable, prerelease build tagged docs-YYYY.MM.DD-<sha>. Old rolling builds are pruned automatically.
Release snapshots track the software. Each software release carries a copy of the skill pinned to that version.

A rolling docs-latest pointer is always updated to the newest rolling build. It hosts the skill directly (a stable download URL) plus a small latest.json manifest naming the immutable build it points at:

# Always the newest rolling build:
https://github.com/soliplex/soliplex/releases/download/docs-latest/soliplex-docs-skill.tar.gz

# Machine-readable pointer (tag, source_commit, generated, sha256, asset_url):
https://github.com/soliplex/soliplex/releases/download/docs-latest/latest.json

To pin a specific version instead, download from its immutable tag (a docs-YYYY.MM.DD-<sha> rolling build, or a software-release tag).

Installing the skill

Download and unpack it wherever your agent discovers skills:

# Example: install the latest build into a Claude Code skills directory
mkdir -p ~/.claude/skills
curl -fsSL \
  https://github.com/soliplex/soliplex/releases/download/docs-latest/soliplex-docs-skill.tar.gz \
  | tar xz -C ~/.claude/skills

This unpacks a soliplex-docs/ directory. Consult your agent's documentation for the exact location it scans for skills.

What it contains

soliplex-docs/
├── SKILL.md          # metadata + a navigable map of the documentation
├── scripts/
│   └── skill_versions.py   # list / diff / upgrade published versions
└── references/       # this documentation tree, verbatim
    ├── config/...
    ├── server/...
    └── ...

The SKILL.md metadata block records the version, source_commit, and generation date, so you can tell which build a given copy came from.

Listing versions and checking for updates

The skill bundles scripts/skill_versions.py, a PEP 723 script that delegates to the soliplex-skills library. Run it with uv from inside the installed skill directory — the first run fetches the library; set GITHUB_TOKEN / GH_TOKEN for higher API rate limits:

# List published versions (rolling builds + release snapshots), newest
# first, marking the installed copy and the current 'latest' pointer.
uv run scripts/skill_versions.py list

# Show what changed upstream since this copy was built (the whole skill
# tree, including the documentation map; the build stamp is ignored).
uv run scripts/skill_versions.py diff latest

# Just the changed-file names, or a diff between two published versions.
uv run scripts/skill_versions.py diff latest --name-only
uv run scripts/skill_versions.py diff docs-2026.05.20-abc1234 docs-2026.05.29-def5678

diff exits non-zero when there are differences, so it composes in scripts.

To refresh, let the helper upgrade the installed copy in place. It downloads the requested version (default: the newest rolling build), verifies its checksum, and replaces the skill's files so documents deleted upstream do not linger:

# Upgrade to the newest published build.
uv run scripts/skill_versions.py upgrade

# Preview the change first, or pin a specific tag (see 'list' for tags).
uv run scripts/skill_versions.py upgrade --dry-run
uv run scripts/skill_versions.py upgrade docs-2026.05.29-def5678

# Reinstall even when the installed copy is already current.
uv run scripts/skill_versions.py upgrade --force

upgrade no-ops when the installed source_commit already matches the target. Equivalently, you can re-download by hand after removing the old copy:

rm -rf ~/.claude/skills/soliplex-docs
curl -fsSL https://github.com/soliplex/soliplex/releases/download/docs-latest/soliplex-docs-skill.tar.gz \
  | tar xz -C ~/.claude/skills

Building it yourself

The skill is built by scripts/build_skill.py. The dev dependency group provides skills-ref, which the script uses to validate the result against the Agent Skills spec:

uv run --group dev python scripts/build_skill.py --out dist/

The output lands in dist/soliplex-docs/. Continuous integration runs the same command (see .github/workflows/build-docs-skill.yaml) and publishes the packaged skill as described above.

Trying it in the example installations

The bundled example configurations discover filesystem skills under their ./skills directory (see filesystem_skills_paths in example/minimal.yaml). Generate the skill straight into that directory so agents launched from the examples can use it:

uv run --group dev python scripts/build_skill.py --out example/skills/

This creates example/skills/soliplex-docs/, which sits alongside the checked-in example skills and is picked up automatically. That path is git-ignored, so generating it here will not accidentally commit the skill (or the whole documentation tree) into the repository.