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.
In this repository16 other files it gives its agents.
- architecture-decision-recordsSkill
- atlas-add-toolSkill
- atlas-ci-releaseSkill
- atlas-optimization-patternsSkill
- atlas-rag-evaluationSkill
- embedding-strategiesSkill
- hybrid-search-implementationSkill
- mcp-builderSkill
- python-code-styleSkill
- python-observabilitySkill
- python-resilienceSkill
- python-testing-patternsSkill
- python-type-safetySkill
- readme-maintenanceSkill
- skill-creatorSkill
- uv-package-managerSkill
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
- Very specific: line 25
Always run atlas-doctor first to confirm the environment is ready:
- Very specific: line 64
After a successful build, the output is <BUNDLE_DIR>/atlas-bundle.tar.zst.
- Very specific: line 103
Add the publication folder to data/servicenow-docs/ (git submodule update or fresh clone).
- Very specific: line 105
Update manifest.json will include the new publication.
- Distinctive: line 106
If CI builds are triggered by tags, create a new tag.
≈ “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.
Files
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-doctorThis 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 100Full local build (all publications, MLX backend — use for production):
uv run atlas-buildSingle publication (iterate on one docs section):
uv run atlas-build --publication it-service-managementCI-matching build (reproduce CI conditions — slow on 2 cores):
uv run atlas-build --model Xenova/bge-small-en-v1.5 --backend onnx-cpu3. 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.zstExpected structure:
manifest.json
chunks/00000000.parquet
chunks/00000001.parquet
...
embeddings/00000000.parquet
embeddings/00000001.parquet
...4. Run the smoke test
uv run atlas-smokeThis 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
| Flag | Purpose |
--model | Override the HF model ID (default: TransformersPseudoImpact/bge-base-en-v1.5) |
--backend | mlx, onnx-cpu, onnx-gpu (default: auto-detect) |
--limit | File limit for smoke/development builds |
--publication | Single publication folder |
--no-cache | Force re-download of docs |
--bundle-dir | Output directory (default: data/bundles/<timestamp>) |
Adding a new publication
- Add the publication folder to
data/servicenow-docs/(git submodule update or fresh clone). - Rebuild the bundle — the chunker auto-discovers publications.
- Update
manifest.jsonwill include the new publication. - If CI builds are triggered by tags, create a new tag.
Troubleshooting
| Symptom | Likely cause | Fix |
atlas-doctor fails on "HF cache" | Model not downloaded | uv run atlas-doctor --fix or download manually |
| Build crashes during chunking | Corrupted docs clone | git -C data/servicenow-docs stash && git -C data/servicenow-docs pull |
| Build crashes during embedding | OOM | Reduce batch size or use onnx-cpu |
| Smoke test returns non-zero | Extraction/missing files | Check the temporary directory and manifest |
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
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.

