A version-aware Hermes Agent skill for building, inspecting, automating, testing, migrating, and shipping applications with the public tldraw SDK.
The skill targets tldraw 5.2.5+ while treating the version installed in your project as authoritative. It routes Hermes to focused, source-backed guidance instead of loading one large documentation dump or guessing APIs from memory.
- Why this skill
- What it covers
- Requirements
- Install
- Quick start
- Example prompts
- How it works
- Helper scripts
- Repository layout
- Security model
- Known limitations
- Testing
- Troubleshooting
- Contributing
- Release and provenance
- License
Public tldraw work spans much more than mounting a canvas. A production change may touch Editor state, custom schemas, bindings, accessibility, .tldr serialization, assets, multiplayer, automation, migrations, licensing, and deployment security at the same time.
This skill gives Hermes a repeatable workflow:
- Inspect the project and exact installed package versions.
- Select the relevant public SDK guidance and official sources.
- Implement with version-matched APIs and schemas.
- Exercise the result with type, browser, visual, sync, or agent harnesses.
- Label anything that was not actually run as unverified.
It is designed to prevent common failures such as invented package names, hand-authored .tldr records, mixed @tldraw/* versions, private API usage, unsafe browser credentials, and demo sync infrastructure presented as production-ready.
| Area | Coverage |
|---|---|
| Application setup | Existing React apps, official starter kits, CSS and full-size container requirements |
| Editor and state | Editor, store, signals, history, events, camera, input, side effects, and @tldraw/driver |
| Extensibility | Custom shapes, tools, bindings, migrations, geometry, styles, rich text, and error boundaries |
| UI and accessibility | Components, overrides, themes, preferences, keyboard behavior, i18n, reduced motion, contrast, and ARIA |
| Files and data | Assets, IndexedDB persistence, snapshots, official .tldr parsing/serialization, clipboard, SVG/raster export, and Mermaid |
| Collaboration | @tldraw/sync, presence, room isolation, auth, persistence, CORS, uploads, and self-hosting order |
| AI and starters | Official agent/chat/workflow starters, prompt parts, allowlisted actions, sanitization, and credential boundaries |
| Production work | Performance, security, licensing, deployment, testing, debugging, version migration, and upstream repository workflows |
The detailed capability-to-reference index lives in skills/tldraw/references/capability-map.md.
- A working Hermes Agent installation.
- Python 3.10+ for the three optional standard-library helper scripts. CI exercises them on Python 3.12.
- An existing tldraw project or a request to create one. The skill inspects the project's package manager and installed versions before giving API-specific advice.
- Node.js 22.x and npm. GitHub Actions currently uses Node 22.
- Python 3.12 recommended.
- Playwright Chromium for browser, visual, and two-client sync verification.
- Network access for the optional current-source and upstream-drift checks.
The installed skill itself has no npm runtime dependency. Node and browser dependencies belong to the repository-owned evaluation harnesses.
Install the exact repository-relative skill path:
hermes skills install r0b0tlab/tldraw-skill/skills/tldrawHermes treats public community skills as untrusted until scanned. Review the scanner result before confirming installation. The release process requires a clean-profile installation and helper verification; RELEASING.md records the reproducible procedure. Trust the scanner output from your own installation rather than a repository claim.
Subscribe to the repository first if you want it listed as a custom tap:
hermes skills tap add r0b0tlab/tldraw-skill
hermes skills install r0b0tlab/tldraw-skill/skills/tldrawVerify the installed skill:
hermes skills list --source hubStart a new Hermes session after installation so skill discovery runs against the updated skill set.
git clone https://github.com/r0b0tlab/tldraw-skill.git
cd tldraw-skill
HERMES_HOME="${HERMES_HOME:-$HOME/.hermes}"
mkdir -p "$HERMES_HOME/skills/software-development"
ln -sfn "$(pwd)/skills/tldraw" \
"$HERMES_HOME/skills/software-development/tldraw"For a named profile, set HERMES_HOME to ~/.hermes/profiles/<profile> before creating the symlink. The canonical distributable root remains skills/tldraw/.
Hermes may place a hub-installed copy at a different internal location. Instructions inside the skill therefore use ${HERMES_SKILL_DIR} instead of assuming the development symlink path.
After installing the skill, open a new Hermes session in your project and ask:
/tldraw Inspect this project, report the installed tldraw package versions and
version skew, then tell me which public APIs and checks apply before changing code.
A normal tldraw task follows this sequence:
inspect_project.pyidentifies the package manager, lockfile, framework, tldraw packages, custom schema files, and feature signals.doctor.pychecks Node, package managers, CSS/container signals, version mismatch, and browser indicators without printing secret values.- Hermes reads the smallest relevant reference and verifies it against installed package declarations or current official sources.
- Hermes changes the project and runs the strongest available real checks.
- Browser, visual, sync, or provider behavior that was not exercised is reported as unverified.
You can also invoke the skill through natural language. Explicit references to tldraw, .tldr, @tldraw/driver, @tldraw/sync, the Editor, custom shape utilities, or official tldraw starters are positive activation signals.
Inspect this tldraw app before editing it. Find package-version skew, missing CSS
or container sizing, stale APIs, and custom schema files. Fix the issues and run
the project's real typecheck, tests, production build, and browser verification.
Add a custom tldraw shape with typed props, geometry, rich text, accessibility
descriptions, and a migration from the previous prop schema. Register it in the
app schema and prove a serialize/parse/reload round trip in a fresh Editor.
Build a real tldraw artifact using the Editor and official serializer. Parse it
with the same schema, load it into a clean store and fresh Editor, verify shape
and binding semantics, export SVG, and return the actual artifact paths.
Add self-hosted tldraw sync for this app. Use explicit authentication and allowed
origins, isolate rooms, persist state, constrain uploads, and verify convergence,
room isolation, rejection paths, and restart recovery with two clients.
Inspect this official tldraw agent starter. Add one prompt part and one allowlisted
action with schema validation and sanitization. Keep provider credentials out of
the browser bundle, scan the build, and clearly separate credential-free harness
results from provider-backed behavior.
Convert this Mermaid diagram through the installed @tldraw/mermaid API, preserve
editable semantic shapes and bindings, improve spacing and labels in the Editor,
and verify the result visually without overlapping nodes or unbound arrows.
skills/tldraw/SKILL.md is a progressive-disclosure router. It does not vendor llms-full.txt or treat a repository snapshot as universally correct.
Source precedence is:
- Installed package types and package-local documentation.
- Release notes between the installed and target versions.
- Current official tldraw documentation and LLM corpora.
- Official examples and starter kits for complex patterns.
- The upstream repository's main branch only for contribution work or when official docs explicitly point there.
The observed source baseline is tldraw@5.2.5 from 2026-07-17. Before applying API guidance, the skill inspects the current project and prefers its installed version. Provenance URLs, versions, retrieval dates, and hashes are recorded in source-manifest.json.
| Task | Primary reference |
|---|---|
| Setup and official starters | project-routing-and-starters.md |
| Version policy and stale APIs | source-and-version-policy.md |
| Editor, store, history, Driver | editor-store-state-driver.md |
| Shapes, tools, and bindings | shapes-tools-bindings.md |
| UI and accessibility | ui-accessibility-internationalization.md |
| Files, assets, export, Mermaid | data-files-assets-export-mermaid.md |
| Diagram quality | diagram-authoring.md |
| Sync and collaboration | sync-collaboration.md |
| AI and starter kits | ai-and-starter-kits.md |
| Performance, security, license, deployment | performance-security-licensing-deployment.md |
| Testing, migrations, upstream work | testing-debugging-migrations-upstream.md |
All helpers use only the Python standard library and support machine-readable JSON. The inspector and doctor are read-only. The documentation fetcher never mutates the inspected project; it writes only to its dedicated cache directory.
From a repository checkout:
SKILL_DIR="$(pwd)/skills/tldraw"Inside an active Hermes skill, the equivalent root is ${HERMES_SKILL_DIR}.
python3 "$SKILL_DIR/scripts/inspect_project.py" /path/to/project
python3 "$SKILL_DIR/scripts/inspect_project.py" /path/to/project --jsonThe report includes package manager, lockfile, framework, declared and resolved tldraw package versions, React and TypeScript versions, likely custom files, sync/Driver/Mermaid/agent signals, version skew, and warnings. It reports license-key presence as a boolean and never prints the value.
python3 "$SKILL_DIR/scripts/doctor.py" --project /path/to/project
python3 "$SKILL_DIR/scripts/doctor.py" --project /path/to/project --jsonThe doctor adds Node and package-manager availability, CSS import and full-size-container signals, browser-runtime indicators, and version mismatch checks. It performs no network access and writes nothing.
python3 "$SKILL_DIR/scripts/fetch_official_docs.py" --corpus index
python3 "$SKILL_DIR/scripts/fetch_official_docs.py" --corpus docs --refresh --json
python3 "$SKILL_DIR/scripts/fetch_official_docs.py" --corpus index --offline --jsonAvailable corpora are index, docs, examples, releases, and full. Cached text and SHA-256 metadata live under ${XDG_CACHE_HOME:-~/.cache}/hermes/tldraw/. Fetches are size-bounded, validate official/loopback URLs and redirects, write atomically, and retain the last valid cache after a failed refresh. Fetched text is treated as data, never executed.
.
├── skills/tldraw/ # distributable Hermes skill
│ ├── SKILL.md # activation, workflow, and task router
│ ├── references/ # focused, version-aware public SDK guidance
│ ├── scripts/ # stdlib inspector, doctor, and docs cache
│ └── templates/ # localhost-only development bridge template
├── tests/ # structural, source, activation, and release contracts
├── eval-app/ # real React/browser/.tldr/Driver/visual harness
├── integration/sync-eval/ # local two-client sync and security harness
├── integration/agent-eval/ # agent/starter, migration, and bundle-safety harness
│ ├── SECURITY.md # trust boundaries and AI SDK advisory inventory
│ └── workflow-starter/ # separately locked and audited workflow fixture
├── .github/workflows/ci.yml # complete CI gate and evidence upload
├── CONTRIBUTING.md
├── SECURITY.md
├── CHANGELOG.md
└── RELEASING.md
Generated screenshots, builds, databases, caches, dependencies, and machine-specific evidence are ignored. Durable, reviewable conclusions live under tests/reviews/.
| Boundary | Policy |
|---|---|
| Community installation | Inspect Hermes's community-skill scan before accepting installation. |
| Project inspection | The inspector and doctor are read-only, standard-library-only, and secret-value safe. The documentation fetcher writes only to its dedicated cache. |
| Development bridge | Development builds only, explicit opt-in, loopback hosts only, no arbitrary evaluation, shell, filesystem, or environment access. |
| Production bundle | CI builds the app and verifies that Hermes/Driver bridge code is absent from production output. |
| Imported data | .tldr, snapshots, SVG/HTML, assets, URLs, redirects, IDs, and metadata are untrusted and must be parsed, bounded, and sanitized. |
| Sync | Use authentication, explicit origins, room isolation, upload limits, MIME signature checks, safe persistence, and non-loopback bind controls. |
| AI | Provider credentials stay in server/worker environments. Model output is schema-validated, sanitized, and restricted to allowlisted actions. |
| Licensing | The skill's original content is MIT; the tldraw SDK remains source-available under its own license. |
The local sync and agent systems in this repository are evaluation harnesses, not hosted production services. Review SECURITY.md, integration/sync-eval/SECURITY.md, integration/agent-eval/SECURITY.md, and the deployment guidance before adapting them.
Report a vulnerability privately through a GitHub Security Advisory. Do not put API keys, license keys, private canvas contents, or user documents in a public issue.
- Scope is documented public SDK APIs, published packages, and official starters. It does not cover private tldraw.com internals, undocumented
@internalsymbols, or unrelated generic Canvas/WebGL work. - Provider-backed AI behavior is explicitly unverified because the release gate did not use provider credentials. Credential-free starter architecture, typecheck, build, sanitization, action, and secret-scan paths are verified; live model quality is not.
npm auditreports six low-severity affected package entries in the retained AI starter dependency tree, all rooted in one resource-consumption advisory. The advisory inventory records the GHSA, packages, ranges, and current remediation constraint. No moderate, high, or critical production dependency findings were observed in that harness.- The sync and agent servers are local evaluation harnesses, not production deployment templates or managed services.
- The observed documentation/package baseline is tldraw 5.2.5. Newer projects must be inspected and checked against their installed declarations and release notes.
- A machine-specific Chromium baseline exercises 3,999 shapes against tldraw's default 4,000-shape page limit. It is evidence from that environment, not a universal latency guarantee.
- Custom shapes and bindings are portable only to hosts that register the same utilities and schema. A custom
.tldrfile is not automatically portable to tldraw.com. hideUihides default chrome but is not a permission or security boundary. In the tested 5.2.5 runtime, built-in keyboard shortcuts remain mounted.- The tldraw SDK is not MIT. Production use requires compliance with the current tldraw license and a valid license key where applicable.
Run the validator before unit tests so invalid package content fails before Python can create bytecode caches:
export PYTHONDONTWRITEBYTECODE=1
python3 tests/validate_skill.py skills/tldraw
python3 -m unittest discover -s tests -p 'test_*.py'
python3 tests/verify_source_manifest.py
python3 tests/run_workflow_eval.pyThe browser installation command below matches the pinned Linux CI setup and may install operating-system packages. If those packages are already present, the package-local Playwright installer is sufficient for routine development.
export PYTHONDONTWRITEBYTECODE=1
python3 tests/validate_skill.py skills/tldraw
python3 -m unittest discover -s tests -p 'test_*.py'
python3 tests/verify_source_manifest.py
python3 tests/verify_source_manifest.py --network
python3 tests/verify_upstream_dry_run.py
python3 tests/verify_upstream_dry_run.py --network
python3 tests/check_capability_coverage.py \
--index https://tldraw.dev/llms.txt \
--map tests/capability-map.json \
--skill skills/tldraw
npx --yes playwright@1.61.1 install --with-deps chromium
npm ci --prefix eval-app
npm test --prefix eval-app
npm run verify --prefix eval-app
npm run benchmark --prefix eval-app
npm run visual:scenarios --prefix eval-app
npm ci --prefix integration/sync-eval
npm run typecheck --prefix integration/sync-eval
npm run build --prefix integration/sync-eval
npm run test:unit --prefix integration/sync-eval
npm run test:integration --prefix integration/sync-eval
npm ci --prefix integration/agent-eval
npm run eval --prefix integration/agent-eval
python3 tests/run_workflow_eval.py
python3 -m unittest -v tests.test_workflow_eval
npm audit --omit=dev --audit-level=high --prefix eval-app
npm audit --omit=dev --audit-level=high --prefix integration/sync-eval
npm audit --omit=dev --audit-level=high --prefix integration/agent-eval
npm audit --omit=dev --audit-level=high --prefix integration/agent-eval/workflow-starter
git diff --checkMachine-specific outputs go below tests/results/ and eval-app/artifacts/ and remain ignored. Stable independent-review summaries live in tests/reviews/. CI recreates the harness evidence and uploads it for each run.
Harness details:
Use the complete repository-relative identifier, including skills/tldraw:
hermes skills install r0b0tlab/tldraw-skill/skills/tldrawThe shorter r0b0tlab/tldraw-skill/tldraw form is not the supported path. Confirm that the public repository is reachable, list configured taps, and inspect the command's text output rather than relying only on its process exit code.
Start a new Hermes session, confirm tldraw is enabled with hermes skills list --source hub, and use /tldraw or mention tldraw explicitly. Generic requests such as “draw a diagram” intentionally do not force this skill when no tldraw preference is present.
Run inspect_project.py and check declared versus resolved versions. Prefer installed types and package-local documentation over this repository's 5.2.5 baseline. Keep tldraw and all @tldraw/* packages aligned unless the installed package declarations prove otherwise.
Ensure the app imports tldraw's CSS and that the canvas container has an explicit full-size layout. Run doctor.py; its css_container report checks both signals.
Use parseTldrawJsonFile with the same schema used by the app. Register matching custom shape and binding utilities, handle parser errors explicitly, load into a clean store, and verify semantics in a fresh Editor. Do not patch raw records or schema versions by hand.
Install the repository dependencies and Playwright Chromium:
npm ci --prefix eval-app
npm exec --prefix eval-app -- playwright install chromiumThe verification harness binds explicitly to 127.0.0.1 to avoid localhost IPv4/IPv6 mismatch in CI.
Check the room token and browser origin. The local harness accepts loopback origins by default, rejects arbitrary origins, enforces bounded image uploads, and refuses a non-loopback bind while using its demo token. See integration/sync-eval/README.md.
That status is intentional when no supported provider credential was used. Do not replace it with simulated success. Configure credentials only in the starter's server/worker environment, run the provider path, and preserve browser bundle and secret-scan checks.
Contributions are welcome. Start with CONTRIBUTING.md and follow these rules:
- Verify claims against installed tldraw packages, then current official documentation.
- Keep
SKILL.mdconcise and route detail into focused references. - Use the official TypeScript runtime for
.tldrgeneration, parsing, migration, and semantic verification. - Add a regression test for every behavior or documentation-contract change.
- Run the relevant harnesses and leave generated evidence untracked.
- Preserve licensing and provenance boundaries.
Repository-specific agent instructions are in AGENTS.md and skills/tldraw/AGENTS.md.
For bugs and feature requests, use GitHub Issues. For security reports, use a private GitHub Security Advisory instead.
- Current release: v1.0.0
- Changes:
CHANGELOG.md - Release procedure:
RELEASING.md - Source URLs, dates, versions, and hashes:
source-manifest.json - Machine capability map:
tests/capability-map.json - CI workflow:
.github/workflows/ci.yml
A release is not considered verified solely because it was committed. Follow RELEASING.md: run the documented gates and audits, verify a clean-profile Hermes installation, require green CI on main, and validate a clean public clone before tagging.
- Original skill content in this repository, including
SKILL.md, authored references, tests metadata, and authored scripts: MIT. SeeLICENSE. - The tldraw SDK, packages, examples, and many templates: source-available under the tldraw license. Production use requires compliance with the current license and a valid key where applicable.
- Official agent/workflow starter material retained under
integration/agent-eval/preserves its upstream MIT notice inintegration/agent-eval/LICENSE.md. That notice does not relicense the tldraw SDK dependency. - Starter application terms do not override the licenses of their dependencies.