git clone --depth 1 https://github.com/superdesigndev/treg /tmp/interface && cp -r /tmp/interface/docs/context/interface ~/.claude/skills/interfaceskill.md
# 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.
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.
- **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 <name> 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.
## `/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 cAdd a provider to treg's OAuth registry (the ones treg holds its own approved app for). Use when asked to "add YouTube/Notion/Meta OAuth", "support connecting X", "add a new OAuth provider", or when a connect flow, capability picker, channel/account picker, or provider health probe needs building. Covers the code changes, the platform-side approval steps, and the pitfalls that don't announce themselves.
Use when setting up, changing or debugging treg's own conversion tracking — the ad-click capture, the AdConversion outbox, or the Data Manager uploader — and whenever asked whether conversions are "working", "live" or "verified". Also use before claiming any part of the pipeline is proven.
One-command local dev stack for tools-registry. Use when asked to "start the dev server", "run treg locally", "test login locally", "bring the stack up", or before any manual/browser test against localhost.
Traps when running Google Ads through treg — the API requirements and cleanup semantics that cost round-trips or money. Use whenever asked to analyse ad performance, audit spend, create or change campaigns, adjust budgets or bids, or do media buying.
Traps to avoid when querying Google Analytics 4 through treg — cases where the GA4 Data API returns a confident wrong answer instead of an error. Use whenever answering questions about site traffic, visitors, pageviews, channels, conversions, or revenue from GA4.
Traps to avoid when querying Google Search Console through treg — cases where the API returns a confident wrong answer instead of an error, especially around totals and recent-date trends. Use whenever answering questions about organic search clicks, impressions, rankings, or index status.
tools-registry context + doc upkeep. Use to warm up a fresh session (orient on the architecture + recent commits) or when working on tools-registry — changing code, rules, content, data, or process (proxy · auth/secrets · API · CLI · the registry skill) — loads the relevant fragment(s) from docs/context so you act with accurate, cited context. Accepts an optional focus query (e.g. `/tools-registry-context <area>`). Also runs `/tools-registry-context sync` to update the doc fragments after changes (show → approve → apply). Mention it whenever a push to the main branch is near.
Write a treg.to agent page (/agents/<client>) or use-case page (/use-cases/<category>/<job>). Researches the real problem on Reddit and X with agent-reach BEFORE writing, so the page targets the words buyers actually use and quotes their own questions. Use when adding a page from marketing/pseo-ship-plan.md, or when asked to "write the <job> page" / "add the <agent> page".