TDMCPSkills

# TDMCPSkills Portable Agent Skills for TouchDesigner. Teaches AI coding agents how to build TouchDesigner networks effectively using the [TDMCP](https://github.com/TouchDesigner/TDMCP) server. 19 skills cover TOPs, CHOPs, POPs, SOPs, GLSL, materials, components, UI, and end-to-end workflow. See [SKILLS.md](SKILLS.md) for the full list. > **The `td-` prefix is reserved.** Installing skills — via the in-TD component, the plugin, or `install.py` — **manages the entire `td-` namespace** in the target skill directory: any `td-*` skill the current release no longer ships is removed on update. Author your own skills under your **own prefix** (e.g. `mystudio-foo`); anything named `td-*` is owned by this system and may be replaced or deleted without warning. Three separate pieces work together: - **Skills** — reusable TouchDesigner workflow instructions (this repo) - **MCP** — the live TDMCP connection to TouchDesigner (configured per host, see below) - **Plugins/extensions** — provider-specific packaging (currently Claude Code only) ## Supported hosts | Host | Skills location | MCP config | | --- | --- | --- | | Claude Code | `~/.claude/skills/` · `.claude/skills/` | `.mcp.json` / `~/.claude.json` (plugin auto-registers) | | Codex | `~/.codex/skills/` · `.agents/skills/` | `~/.codex/config.toml` | | Gemini CLI | `~/.gemini/skills/` · `.gemini/skills/` | `.gemini/settings.json` | | Antigravity (`agy`) | `~/.gemini/antigravity-cli/skills/` · `.agents/skills/` | `~/.gemini/config/mcp_config.json` | | OpenCode | not located | `opencode.json` | Each row is the global path followed by the project path. Codex and Antigravity share `<project>/.agents/skills/`, so one project install serves both. There is no single portable directory that all hosts read — `~/.agents/skills/` was tried and no host was found to read it. ## Requirements - One of the supported agent CLIs above - [TDMCP](https://github.com/TouchDesigner/TDMCP) installed and running in TouchDesigner - Python 3.7+ (only for the script install path) ## Quick install ```bash git clone https://github.com/TouchDesigner/TDMCPSkills.git cd TDMCPSkills python install.py install --target claude ``` Pick the target that matches your CLI (see **Install targets** below). Project-local instead of global: ```bash python install.py install --target codex --project /path/to/your/project ``` Installing skills does **not** configure the MCP connection — do that once per host (next section). ## TDMCP MCP configuration TDMCP serves MCP over HTTP at `http://localhost:13316/mcp`. Start it inside TouchDesigner before using any agent. **Claude Code** — project `.mcp.json` (or `~/.claude.json`): ```json { "mcpServers": { "tdmcp": { "type": "http", "url": "http://localhost:13316/mcp" } } } ``` **Codex** — `~/.codex/config.toml`: ```toml [mcp_servers.touchdesigner] url = "http://localhost:13316/mcp" ``` **Gemini CLI** — project `.gemini/settings.json` (or `~/.gemini/settings.json`): ```json { "mcpServers": { "tdmcp": { "httpUrl": "http://localhost:13316/mcp" } } } ``` **OpenCode** — project `opencode.json` (or `~/.config/opencode/opencode.json`): ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "tdmcp": { "type": "remote", "url": "http://localhost:13316/mcp", "enabled": true } } } ``` ## Install — Claude Code plugin (recommended for Claude Code) In Claude Code: ``` /plugin marketplace add TouchDesigner/TDMCPSkills /plugin install tdmcp-skills@touchdesigner ``` This installs the 19 distributed skills and auto-registers the TDMCP MCP connection. Update with `/plugin marketplace update touchdesigner`; uninstall with `/plugin uninstall tdmcp-skills`. Script alternative for Claude Code: ```bash python install.py install --target claude ``` ## Install targets ```bash python install.py install --target claude # ~/.claude/skills/ (Claude Code) python install.py install --target gemini # ~/.gemini/skills/ (Gemini CLI) python install.py install --target agy # ~/.gemini/antigravity-cli/skills/ (Antigravity) python install.py install --target all # the verified default set (currently: claude) python install.py install --target codex # ~/.codex/skills/ (Codex; project scope is .agents/skills/) python install.py status --target claude # install status + update check python install.py uninstall --target claude ``` Notes: - Each target keeps its own manifest; install/status/uninstall never touch another target. - The installer only ever removes skill directories recorded in its own manifest. Conflicting `td-*` directories it doesn't own stop the install with an error (override with `--replace`). - Pick **one primary target per host** — installing the same skills in multiple discovery locations can produce duplicates. `status` reports other known installs. - Running `install.py` with no `--target` defaults to `claude`. - **One project install can serve two hosts.** Codex and Antigravity both read `<project>/.agents/skills/`, so a single project-scope install covers both. Their global paths differ (`~/.codex/skills/` vs `~/.gemini/antigravity-cli/skills/`), so user-scope installs stay separate. - **Gemini needs a trusted folder.** Skills copied into `~/.gemini/skills/` are discovered with no CLI step, but Gemini disables MCP servers — and suppresses user-level ones — in an untrusted folder, so trust the project folder or nothing connects. `gemini skills link <path>` is an alternative that symlinks a checkout into the same directory, so edits show up live. - If no local repo is detected, `install.py install` fetches the latest from GitHub directly. ### Migrating an existing `~/.claude/skills` install Nothing breaks: `--target claude` preserves the previous behavior exactly. To also use another host, run that host's target as well (e.g. `--target codex`). Each target keeps its own manifest, so the installs are independent. ## Validation ```bash python validate.py ``` Checks every distributed skill against the portable contract: frontmatter (`name` + `description`), name/directory match, naming rules, resolvable references, and no provider-specific commands or paths in shared content. ## For Contributors ### Fork workflow Fork the repo, work on a branch: ```bash git clone https://github.com/YOUR_USERNAME/TDMCPSkills.git cd TDMCPSkills git checkout -b my-custom-skills ``` Edit any skill under `skills/`, run `python validate.py`, then pick a testing loop: **Via the script** — reinstalls globally, available in every project: ```bash python install.py install --target claude # or codex / gemini / agy ``` **Via the plugin (Claude Code)** — install this working tree as a local marketplace (fastest iteration; no push needed): ``` /plugin marketplace add "/absolute/path/to/TDMCPSkills" /plugin install tdmcp-skills@touchdesigner ``` After edits, pick up changes with `/plugin marketplace update touchdesigner`. Stay current with upstream: ```bash git fetch upstream git merge upstream/main ``` ### Contributor skills Contributor-only skills live in this repo's `.claude/skills/` and auto-load only when Claude Code is working inside a clone of TDMCPSkills. They are **not** distributed via the plugin or `install.py`. **`/td-skills-local`** — legacy helper for installing skills into a specific project's `.claude/skills/`. Mostly superseded by the plugin install path. ## Compatibility notes - Shared skill content is provider-neutral: MCP tool names are unqualified (`get_help`, not a host-prefixed name) because each host namespaces tools differently. - Skill discovery and activation behavior varies by host; if a host doesn't auto-activate a skill, ask the agent to read the relevant `SKILL.md` explicitly. - Smaller/local models (tested: qwen3:14b via OpenCode + Ollama) discover and load skills but tend to skip the cross-cutting `td-general` skill and jump straight to a builder skill, losing naming and get-help-first conventions. Mitigate by instructing "load `td-general` first" explicitly in the project's agent instructions (`AGENTS.md`). - LM Studio is out of scope. ## Contributors - Jarrett Smith (Derivative) - Tim Gerritsen (y=f(x) Lab)