# Interface > The `tools-registry` skill - Skill: `superdesigndev/interface` (Agent Skill, multi-file: 12 files) - Install (CLI): `npx skillmds@latest add superdesigndev/interface` - Raw SKILL.md: https://api.skillmd.com/api/skills/superdesigndev/interface/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: superdesigndev (https://skillmd.com/u/superdesigndev) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/superdesigndev/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 ` 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](api.md) + [cli.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. | door | artifact | who reaches it | |---|---|---| | the installer | `install.sh` → `treg skill bootstrap` → every detected agent's skills dir | people who ran the curl one-liner | | Claude Code plugin | `.claude-plugin/` + generated `skills/treg/SKILL.md` (repo root) | `/plugin marketplace add superdesigndev/treg` | | Codex/ChatGPT plugin | `plugin/.codex-plugin/` + generated `plugin/skills/treg/SKILL.md` | the directory ChatGPT and Codex share | | Cursor plugin | `.cursor-plugin/marketplace.json` + generated `plugins/treg/skills/treg/SKILL.md` | the Cursor marketplace (plugin root is never the repo root) | | DeepSeek Harness bundle | root `package.json` (`dsh.bundle`) + `dsh/cordis.patch.yml` + generated `dsh/skills/treg/SKILL.md` | `dsh plugin --profile add github:superdesigndev/treg` | | MiniMax plugin | `plugins/minimax/.minimax-plugin/plugin.json` + generated `plugins/minimax/skills/treg/SKILL.md`; `scripts/minimax_plugin.py` pre-runs their validator and builds the ZIP | the MiniMax Plugin Marketplace (MiniMax Code + MiniMax Agent), submitted by form as GitHub subdir `plugins/minimax`; skills-only because the package may hold no credential and the bootstrap omits `treg mcp install`, which cannot write a MiniMax config. See [docs/MINIMAX-PLUGIN.md](../../MINIMAX-PLUGIN.md) | | the domain itself | `GET /.well-known/skills/index.json` + `/.well-known/skills/treg/SKILL.md` | anything speaking the agentskills.io convention (Hermes reads this directly) | `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](../../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](../../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](../architecture/feedback.md). ## `/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.