dgml
Use when the user wants to manage a DGML workspace from the shell — initialize a workspace, add PDFs or Office documents (docx/xlsx/pptx, when a converter is configured) single or bulk from a directory, create or manage DocSets, assign files to DocSets, convert PDFs to DGML XML (grounded in place wi…
Install / Use
npx skills add dgml-io/dgml --skill dgmlInstalls into whichever agent you are using.
Gemini Rules
Gemini CLI config
Quality Score
Category
Content & MediaSupported Platforms
Our assessment of dgml
dgml scores 72/100 on our quality scale, 1054th of 1,153 Content & Media skills we index.
Its Gemini Rules is 76 KB long, well organised into 120 sections with 34 code examples: long enough that it reads more like full documentation than a focused instruction file, which agents can find harder to follow.
It has no GitHub stars yet, so there is no community track record; judge it on its content.
Maintenance, license and trust
- The repository was last updated 7 days ago, so dgml is actively maintained.
- No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
- Its trust signals score 80/100, with 2 cautions from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
dgml compared with similar skills
All 4 of these similar skills score higher than dgml; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| dgml (this skill)by dgml-io | 72 | 0 | 7d ago | Gemini Rules |
| siyuanby siyuan-note | 100 | 47.3k | today | MCP Server |
| changelog-videoby heygen-com | 100 | 83.8k | 3d ago | SKILL.md |
| content-research-writerby ComposioHQ | 100 | 79.4k | 2mo ago | SKILL.md |
| ad-creativeby coreyhaines31 | 100 | 60.1k | 5d ago | SKILL.md |
Frequently asked questions
- How do I install dgml?
- Run
npx skills add dgml-io/dgml. The install tabs above show the steps for each supported agent. - Which AI agents does dgml work with?
- It is written for Gemini CLI, as a Gemini Rules file. Other agents that read the same format can often use it too.
- Is dgml safe to use?
- It declares no license and scores 80/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is dgml still maintained?
- The repository was last updated 7 days ago, so dgml is actively maintained.
Skill content
View source on GitHubname: dgml description: Use when the user wants to manage a DGML workspace from the shell — initialize a workspace, add PDFs or Office documents (docx/xlsx/pptx, when a converter is configured) single or bulk from a directory, create or manage DocSets, assign files to DocSets, convert PDFs to DGML XML (grounded in place with dg:origin bounding boxes as part of generation), extract structured values against a schema (RNC schema generation, grounded value extraction to DGML), or run a consistency check. Triggers on phrases like "add these PDFs", "ingest these Word/Excel docs", "create a docset", "import documents into DGML", "ingest a folder of PDFs", "ground the DGML", "add bounding boxes", "extract values", "extraction schema", "generate a schema", "pull fields from these docs", "dgml workspace", "check the workspace".
Using the dgml CLI
The dgml CLI manages a workspace of Files (PDFs copied in, hashed, page-rendered) and DocSets (named groupings of Files). It is JSON-default and non-interactive — built to be scripted.
Authoritative references in this repo:
- docs/cli-reference.md — full command surface
- docs/storage-layout.md — on-disk format
- packages/dgml/src/dgml/cli.py — implementation
When in doubt about a flag or response shape, read those first.
Invocation
From inside this repo, use uv run dgml … (the venv is managed by uv sync). In an environment where the dgml distribution is installed normally, plain dgml … works. Examples below use uv run dgml; substitute as appropriate.
Workspace resolution
The workspace root is picked in this order:
--workspace <path-or-id>flag — a filesystem path or a workspace id fromdgml workspace list$DGML_HOME— also either form./dgml-workspace, relative to cwd — the last resort, and note that nothing creates it by default any more:dgml workspace createwith no path puts the workspace in the store of workspaces instead. It is what keeps a workspace made by an older dgml (or bycreate <path>) working, not a directory to expect.
--workspace and $DGML_HOME each take a path or a workspace id (3–40 chars from
lowercase letters, digits, hyphens and underscores, starting with a letter or digit — a generated ws_… or a chosen
my-workspace). Since an id can also be a directory name, they are told apart by
looking: a value the machine's store of workspaces holds is that workspace, an
existing directory of that name is a path, and a value that is neither fails with
WORKSPACE_NOT_FOUND rather than being treated as a path to create. A listed id wins
over a same-named directory — address the directory as ./name.
The workspace's config.toml is required — it names the storage backend — and lives
either in the workspace's own directory (a workspace addressed by path) or in the store
of workspaces (one addressed by id). There is no flag for pointing at one kept elsewhere:
--workspace-config and $DGML_CONFIG are removed and now fail with
INVALID_ARGUMENT. To start a workspace from a config you authored, use
dgml workspace create --from-config <path>, which copies it in.
Setup — the minimum is a single command:
dgml init [--provider <anthropic|anthropic_google|google|openai>]— run once per machine. Writes the user-level~/.config/dgml/config.tomlwith a[models]block naming one provider family (family = "anthropic_google"), which dgml expands into its recommended four tiers at runtime; an explicit tier ([models] advanced = "...") in the same or a higher config layer overrides its family default, and a family overrides tiers set in lower layers. Omit--providerto auto-detect from the API-key env vars that are set (ANTHROPIC_API_KEY/GEMINI_API_KEY/OPENAI_API_KEY, checked in that order — an OpenAI key never overrides a provider the other two resolve); pass--forceto overwrite an existing file (backs it up first). Without a family or explicit tier there are no default models — an unconfigured model is a hard error, never a silent paid call.dgml workspace create [path] --organization <org>— creates the workspace — writing itsconfig.toml(the storage binding plus a machine-managed[workspace]identity block), records its identity inworkspace.json, and generates a stableworkspace_id(echoed in the payload). Where it goes depends on whether you name a place for it: with nopath, no--workspaceand no$DGML_HOME, the workspace is created in the machine's store of workspaces and is listed bydgml workspace list("listed": true); give apath(dgml workspace create ./ws …) and you get a detached workspace in that directory, addressed by path and not listed. Prefer the listed form for new work —--workspace <id>then opens it from any directory. It does not touch the user config; if the config is missing it still creates the workspace and warns on stderr to rundgml init. Safe to re-run — an existing[storage.<name>]is never overwritten and the recorded id, name andcreated_atare reused.--organizationis required for a new workspace and is embedded in its docset namespace URIs (http://dgml.io/<org>/<DocSetSlug>); it becomes optional once the config records one (passing a different value re-organizes the workspace and warns on stderr).--nameis an optional human-readable label.--id <workspace_id>sets the stable handle instead of generating one (3 to 40 characters using only lowercase letters, digits, hyphens and underscores, starting with a letter or digit, e.g.--id my-workspace) — use it when the id is decided elsewhere or a workspace is being re-created deterministically; an id the store already holds fails withCONFLICT(if it is the workspace you mean, re-run addressed to it:dgml --workspace <id> workspace create …), an--idmatching the workspace's existing id is a no-op, and one that differs from it fails withINVALID_ARGUMENT(createnever re-identifies a workspace). Use--storage <name>to materialize a named service defined as[storage.<name>]in the user config into this workspace's own config (omit for the bundled local-disk default);--from-config <path>starts from a config you authored, copied in verbatim (a template — the source is not tracked, and later edits to it do nothing). A seed only initializes a workspace with no config; re-running with the same seed is a no-op, and one that differs from the existing config fails withINVALID_ARGUMENT. Acreatethat fails (badprovider =, missing--organization, …) leaves no listed row behind, so fix the cause and retry the same command. The two compose:--from-configsupplies the config,--storagesays which[storage.<name>]table in it to bind to — a config declaring[storage.acme]needs--storage acme, or create fails withINVALID_ARGUMENTrather than silently using local disk.
Per-workspace config overrides need a config that is a file. workspace_config_path (from workspace create or dgml status) is the path to append a section like [ocr] or [generation] to — and it is null when the store of workspaces does not keep configs as files (the Mongo backend does not; config_location names where it is instead). In that case put the section in the user config, which every workspace layers over, or supply it at create time with --from-config. Recipes below guard on this rather than appending blindly: jq -r renders a JSON null as the string null, so an unguarded cat >> "$cfg" silently writes a file called null and the setting never takes effect.
A workspace's config.toml is required and must travel with it — it is the only record of which storage backend holds the data. A workspace whose config is missing fails with WORKSPACE_NOT_INITIALIZED — having a config is what being a workspace means; do not delete it, and copy it along when moving a detached workspace's directory.
A workspace id is not visible in the filesystem the way a path is, so in a new shell recover it with dgml workspace list rather than guessing (unless you set it yourself with workspace create --id, which is the reason to). The recipes below pass --workspace "$wid" on every command, which is what works when each command runs in its own shell (as agents usually run them); at an interactive prompt export DGML_HOME=<id> once is equivalent and shorter. dgml never sets that variable for you.
Managing multiple workspaces: dgml workspace list prints every workspace the store of workspaces holds ({workspace_id, name, organization, storage_service, root, created_at}), and any workspace_id opens it from anywhere — e.g. id=$(dgml workspace create --organization Acme | jq -r .workspace_id) then dgml --workspace "$id" file list. Every field is derived from each workspace's own config, so a row cannot disagree with the workspace it describes. A detached workspace is not in the store of workspaces and so not listed; dgml workspace import <path> adds one, and dgml workspace import with no arguments sweeps every workspace an older dgml left in ~/.config/dgml/workspaces.json (data never moves — the existing directory is recorded as workspace_path, which does not re-seal the workspace). A workspace whose config.toml is missing gets one reconstructed: from the legacy row's storage snapshot when it has one, else local disk is assumed and reported (assumed_local_storage). A directory with no workspace identity, or a hand-edited malformed workspace_id, is refused with the fix named — the legacy index is never deleted, so nothing is lost. (dgml workspace register has been removed.)
Sharing one list across machines: set [workspaces] in the user config to dgml_storage_mongo:MongoWorkspacesStore with mongo_database, and two machines pointed at that database open the same workspaces by id with no config file passed between them. The default is one folder per workspace under ~/dgml-workspaces/ (or $DGML_WORKSPACES).
Changing a workspace's storage: edit [storage] in its config.toml, then run dgml workspace reseal [path] to accept the change (--check reports drift and exits 1 without writing). Until you do, commands fail with STORAGE_BACKEND_MISMATCH — the guard against silently opening a different backend than the one holding your data. Resealing records the new configuration; it does not move data.
Configure once per machine: every workspace inherits ~/.config/dgml/config.toml. Models are set via [models] — a family and/or explicit tiers (light/standard/advanced/expert); per-task sections override a tier. A workspace can override per key via its own <workspace>/config.toml, and env vars (DGML_MODELS__ADVANCED=…) override on top. Exception: [storage] does not merge — a service the workspace defines is used whole. Any command other than init / workspace create on an uninitialized workspace fails with WORKSPACE_NOT_INITIALIZED.
Output contract — parse it with jq
- stdout: JSON success payload
- stderr: JSON error envelope
{ "error": { "code": "...", "message": "..." } } - exit codes:
0success,1error,2checkran but found issues
Capture IDs from JSON with jq, never by string-munging text output:
ds=$(uv run dgml docset create --name "Q2 contracts" | jq -r .id)
fid=$(uv run dgml file add /tmp/contract.pdf | jq -r .file.id)
Use --format text only when a human asked for readable output directly; do not parse it.
Common workflows
Add a single PDF and assign it to a DocSet
# Once: create the workspace and keep its id — that is the handle for every command
# below. `create` prints it, and `dgml workspace list` shows it again in a new shell.
wid=$(uv run dgml workspace create --organiza
Truncated for display — read the full file on GitHub.
Related Skills
siyuan
47.3kAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间,让人与智能体在此协作
changelog-video
83.8kTurn a weekly changelog .md into a finished branded changelog video (square 1080, ~45-60s, Annie VO, animated brand background, mock-UI visualizations, lowkey captions)
content-research-writer
79.4kAssists in writing high-quality content by conducting research, adding citations, improving hooks, iterating on outlines, and providing real-time feedback on each section. Transforms your writing process from solo effort to collaborative partnership.
ad-creative
60.1kWhen the user wants to write or judge ad creative, or asks which ad, hook, or angle to run or kill: headlines, primary text, and variations for Google, Meta, LinkedIn, and TikTok, fresh angles when creative fatigues. Test hypotheses name the metric, comparison, and expected direction.
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
