Interface

The tools-registry skill

src/treg/web/skill.md is the product skill that ships to consumers — the agent's whole interface to the registry (distinct from .claude/skills/tools-registry-context/, which maintains these design docs). Its frontmatter name: treg + description make it loadable by a coding agent.

The feedback section encourages proactive reports of small annoyances and concrete friction and workarounds even when a task succeeds, asks for observations rather than a proven bug, and names MCP call_ids / CLI --call-id. The Review section, between Feedback and Rules, asks agents to rate an invited catalog call after use, names the four usefulness choices and CLI/MCP forms, and directs problems to feedback.

One skill, three personas:

• consumer — discover + call tools with no credentials locally. Teaches the agent-native URL-passthrough first: take the real upstream URL and prefix it with {BASE}/call/
  • the X-Treg-Token header; treg call <tool> <path> is the CLI shorthand. Its "generate a video or an image" task teaches the async shape: --await for the CLI, the X-Treg-Async descriptor and lazy 30-60 s polling for MCP agents, the shell-timeout warning (video takes 1-5 minutes), reserve-then-settle money with refunds on failure, and expiring result URLs that treg never stores.
• creator — turn a local skill into a shared tool: treg secret add, treg tool add (single-key or --bind multi-credential), the treg skill scaffold → push bundle flow, and treg oauth connect for browser-consent tokens. Documents the two OAuth modes (auto-refresh vs manual) and the four auth shapes.
• admin — inventory + monitor: treg tool/secret/skill ls, treg calls, and treg health [--run] (with the per-tool health_check probe).

Distribution: the file is {BASE}-templated and served at GET /skill.md (routers.web.skill_md, via _serve_md), and install.sh best-effort drops it into ~/.claude/skills/treg/SKILL.md right after installing the CLI — so curl {BASE}/install.sh | sh gives a machine both the treg command AND the skill that teaches an agent to use it. It restates the invariants (secrets are write-only, use-without-hold, the proxy relays the upstream's truth) and links {BASE}/llms.txt + {BASE}/tutorial. It mirrors the surfaces in api.md + cli.md; keep the three in sync when the API/CLI change.

Four doors, one source

The same file reaches agents six ways. Only the first is hand-written; the rest are generated or served, because a second copy of the product's most-read page is a copy that rots.

scripts/build_plugin.py renders every plugin copy from the one source and --check fails if any is stale (tests/test_plugin.py). The variants differ only in their prepended bootstrap, because they arrive in opposite worlds: the Codex plugin ships an MCP connector, so its bootstrap says use the tools, not the terminal; the Claude plugin declares no connector in its manifest — so it installs with no token and nothing waits on a directory review — and its bootstrap does the opposite, walking the agent through install.sh → treg login → treg mcp install so the first run ends with the CLI and the tools. Skills-only is a property of the manifest, not of the end state; the order in that bootstrap is load-bearing, because treg mcp install exits without writing when it runs before there is a token. The Claude copy also gets a version: stamped into its frontmatter, which ClawHub requires and Claude Code ignores; that stamp is what lets one file satisfy both registries.

DeepSeek Harness is the odd one out, and the only door that ships the connector and the CLI path in one zero-config install. dsh reads no manifest: it installs an npm package whose package.json declares dsh.bundle, pointing at a config layer that composes into the user's profile. That layer carries a treg MCP row whose disabled expression is evaluated at boot, so it stays off until TREG_TOKEN is in the environment — the same "no always-on tools that 401" stance as the Claude manifest, but expressible as a row rather than an omission. Its bootstrap is its own for two reasons the others do not have: the tools are namespaced (mcp__treg__call, not call), and treg mcp install cannot help here (it writes Claude Code / Cursor / opencode configs, never a dsh profile), so mcp_install.py reports dsh as a MANUAL agent pointing at the bundle. See docs/DSH-PLUGIN.md.

The Claude variant sits at the repo root, not under plugin/, because that single path is simultaneously what Claude Code's loader auto-discovers, what npx skills add resolves, and what clawhub skill publish takes. See docs/CLAUDE-PLUGIN.md for the per-registry submission runbook.

mcp_install._write_json_agent merges Cursor and opencode entries without disturbing unrelated configuration, then atomically replaces the config from a random same-directory temporary file. That temporary file is created through tempfile.mkstemp before any token bytes are written and is set to mode 0600 through its open fd on POSIX regardless of umask; failures remove it and leave the original config intact. Windows relies on the config directory's inherited ACL rather than claiming POSIX mode semantics.

Feedback

The consumer skill also names feedback as a loading trigger and links to {BASE}/feedback.md. Its short feedback paragraph asks callers to report concrete problems when they have enough evidence, distinguish observations from suspected causes, and report each issue once per task. It also asks callers to retain call IDs when practical and omit private information. Detailed instructions live in web/feedback.md; the HTTP, CLI and two MCP entry points share the contract in feedback.

/integrate.md - the BUILDER skill

A second, separate skill for the other side of the relationship. skill.md teaches an agent to use treg; integrate.md is pasted into a builder's own repo and pointed at their coding agent so they can embed treg and bill their own customers for it.

It leads with the per-customer billing model rather than the call syntax, deliberately: tagging has to happen at the one place your backend already sets Authorization, and a builder who writes the plumbing first writes it in a shape that has to be torn out.

The things it insists on, each because getting them wrong is expensive and silent:

• Tag from the backend, never as a model-supplied argument — a model omits it mid-chain and the spend leaves the invoice.
• Invoice from usage/by-tag (the ledger), never from /calls — audit rows are shed under load.
• Assert attributed + unattributed == total, and drive unattributed_micro to zero; anything left is a call site that forgot to tag.
• Branch on X-Treg-Error, not the status code — a provider's own 4xx is relayed verbatim.
• Never forward a team-level 402/429 to an end user — those carry the builder's balance and a top-up link. The tag-scoped refusals are safe to surface and carry nothing about the team.
• Per-customer caps are advisory, so they must not be sold to end users as exact.

tests/test_tag_billing.py pins the header and route names the skill teaches, so a rename that would silently turn it into wrong instructions fails the suite instead.