agentleFS
sagar-shirwalkarsagar-shirwalkar/servicenow-atlas/.agents/skills/atlas-build-bundle/SKILL.md

atlas-build-bundle

Skill2 starsChanged 5 months agoApache-2.0View on GitHub

Build the portable RAG bundle: clone docs, chunk, embed, package tarball. Use when the task involves building a bundle locally (`atlas-build`), smoke testing a bundle (`atlas-smoke`), or adding a new publication.

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Always run atlas-doctor first to confirm the environment is ready:

    line 25
  2. Very specific:

    After a successful build, the output is <BUNDLE_DIR>/atlas-bundle.tar.zst.

    line 64
  3. Very specific:

    Add the publication folder to data/servicenow-docs/ (git submodule update or fresh clone).

    line 103
  4. Very specific:

    Update manifest.json will include the new publication.

    line 105
  5. Distinctive:

    If CI builds are triggered by tags, create a new tag.

    line 106

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

When to use

  • User asks to "build the bundle", "run atlas-build", "create a release bundle", "generate embeddings"
  • User needs a local bundle for development (--max-files 100, --publication it-service-management)
  • User asks to "add a new publication" to the repo and rebuild
  • User is troubleshooting a failed CI bundle build

Not for

  • Deploying or releasing the bundle (use atlas-ci-release)
  • Evaluating RAG quality (use atlas-rag-evaluation)

Workflow

1. Pre-flight check

Always run atlas-doctor first to confirm the environment is ready:

uv run atlas-doctor

This checks:

  • Git is installed and the docs repo is accessible
  • Python version is >= 3.11
  • Required packages (mcp, numpy, pyyaml, etc.) are installed
  • HF model cache has the selected model (or can fetch it)
  • Disk space is sufficient for the expected bundle size

Fix any failures before proceeding.

2. Choose your build mode

Smoke build (fast, for development — use first):

uv run atlas-build --limit 100

Full local build (all publications, MLX backend — use for production):

uv run atlas-build

Single publication (iterate on one docs section):

uv run atlas-build --publication it-service-management

CI-matching build (reproduce CI conditions — slow on 2 cores):

uv run atlas-build --model Xenova/bge-small-en-v1.5 --backend onnx-cpu

3. Verify the artifacts

After a successful build, the output is <BUNDLE_DIR>/atlas-bundle.tar.zst.

List contents without extracting:

tar --zstd -tf <BUNDLE_DIR>/atlas-bundle.tar.zst

Expected structure:

manifest.json
chunks/00000000.parquet
chunks/00000001.parquet
...
embeddings/00000000.parquet
embeddings/00000001.parquet
...

4. Run the smoke test

uv run atlas-smoke

This builds a 20-file bundle, fires a query, and returns exit code 0 on success. Run this before committing or considering any build successful.

Common flags

FlagPurpose
--modelOverride the HF model ID (default: TransformersPseudoImpact/bge-base-en-v1.5)
--backendmlx, onnx-cpu, onnx-gpu (default: auto-detect)
--limitFile limit for smoke/development builds
--publicationSingle publication folder
--no-cacheForce re-download of docs
--bundle-dirOutput directory (default: data/bundles/<timestamp>)

Adding a new publication

  1. Add the publication folder to data/servicenow-docs/ (git submodule update or fresh clone).
  2. Rebuild the bundle — the chunker auto-discovers publications.
  3. Update manifest.json will include the new publication.
  4. If CI builds are triggered by tags, create a new tag.

Troubleshooting

SymptomLikely causeFix
atlas-doctor fails on "HF cache"Model not downloadeduv run atlas-doctor --fix or download manually
Build crashes during chunkingCorrupted docs clonegit -C data/servicenow-docs stash && git -C data/servicenow-docs pull
Build crashes during embeddingOOMReduce batch size or use onnx-cpu
Smoke test returns non-zeroExtraction/missing filesCheck the temporary directory and manifest

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.