For AI agents

dol ships artifacts for coding agents alongside its code. This page lists them, says where each lives in the repository, and points at the machine-readable copies of this documentation.

Skills

Skills are folders holding a SKILL.md (the Agent Skills format): a description that tells an agent when to use it and a body with the procedure. Install one into your agent with gh skill (any host: --agent claude-code, copilot, cursor, codex, gemini), or use the copy bundled in the wheel.

dol-dev-portability

Keep dol working on Windows as well as Linux/macOS. Use when touching dol’s path/key machinery (filesys.py, naming.py, paths.py, util.py), compiling regexes from templates/paths, mapping keys<->filesystem paths, or when a dol test/doctest passes on Linux/macOS but fails on the Windows CI job. Covers dol’s specific landmines: safe_compile is path-only (never compile a regex with it), escape template LITERALS not the whole pattern, os.sep consistency in prefix/affix codecs, empty-prefix handling, POSIX-only os calls, and dol’s native-separator key convention. For general cross-platform Python principles, see the global cross-platform-python skill.

Source: .claude/skills/dol-dev-portability.

dol-dev-wrap-kvs

Understand and safely modify dol’s core wrapping machinery — wrap_kvs, store_decorator, Store.wrap, and how transforms are applied. Use when touching dol/trans.py or dol/base.py; when changing how key/value transforms (key_of_id, id_of_key, obj_of_data, data_of_obj, postget, preset) are called; when a transform passed to wrap_kvs behaves unexpectedly (called with/without the store as first arg); when working Issues #9/#12/#18/#6/#5; or when a wrap_kvs change could ripple through the ~32 ecosystem packages that use it. Covers the signature-conditioning rule (name AND arity), the FirstArgIsMapping marker, the delegation (has-a) architecture and its ‘self is unwrapped’ trap, the subclass-signature-freeze trap, and the mandatory dependents test-gate. For end-user store-building, see the consumer skills; for Windows path issues, see dol-dev-portability.

Source: .claude/skills/dol-dev-wrap-kvs.

dol-facade-authoring

Author a dol facade over a new storage system: the backend itself, not codecs on top of one. Use when asked to ‘write a dol store for X’, start a ‘new dol package’, ‘make X a MutableMapping’, build a ‘dol facade/backend/adapter for ’, or ‘wrap this DB/API/file format as a dict’; also when adding a read-only reader for a file format or service to an existing dol package. Covers where the code should live (a module bridged into an existing package’s seam vs its own dol package), the layering (connection, raw base store, codecs, one-call factory, malls), the Mapping contract each of the five methods must honour, error translation, why leaf capabilities are free functions or sibling stores and not methods (dol#83), optional backends and system dependencies with check_requirements, and offline testing with a fake source and a tiny generated fixture. For codecs, wrap_kvs, Pipe, filt_iter and caching on an existing backend, see dol-store-building; for dol’s wrapping internals, see dol-dev-wrap-kvs.

Source: .claude/skills/dol-facade-authoring.

dol-store-building

Build a dol store: wrap any storage backend (files, S3, DB, dict, an API) behind a uniform dict-like (MutableMapping) interface, adding key and value transforms/serialization. Use when a user wants to give a backend a dict interface, add JSON/pickle/gzip (or custom) serialization to a store, transform or filter keys, compose codecs, cache a slow store, or asks ‘how do I use dol to …’. Covers wrap_kvs (the core), the ValueCodecs/KeyCodecs namespaces, Pipe composition, the ready-made file stores (Files/TextFiles/JsonFiles/PickleFiles), filt_iter, the test-with-dict-then-swap-backend workflow, and self-aware transforms via FirstArgIsMapping. For authoring interactive scaffolds see the /new-store, /add-codec, /explain-store commands; for modifying dol’s internals see dol-dev-wrap-kvs.

Source: .claude/skills/dol-store-building.

Instruction files

Files agents read before working in this repository.

Machine-readable documentation

This site publishes the same documentation in forms that fit an agent’s context window:

  • llms.txt: an index of every page with a one-line description (llms.txt format)

  • dol.md: the whole documentation as one Markdown file

  • <page>.html.md: a rendered Markdown twin of every page, advertised from each page’s <head> with <link rel="alternate" type="text/markdown">

  • objects.inv: the Sphinx inventory: a symbol-to-URL index (sphobjinv convert plain objects.inv -)