zymtrace-skills: Instructions file for Claude Code

zymtrace-skills — Development Guide

Claude Code skills for installing, upgrading, exposing, troubleshooting, and analyzing zymtrace — continuous CPU/GPU profiling. This guide is for people developing the skills; end-user docs live in README.md.

Repository structure

A single plugin at zymtrace/ that installs into Claude Code, OpenAI Codex, and Cursor from one canonical source, plus repo-root marketplace manifests (one per tool) and the test suite.

.claude-plugin/marketplace.json   # Claude Code marketplace manifest
.agents/plugins/marketplace.json  # Codex (and generic) marketplace manifest
.cursor-plugin/marketplace.json   # Cursor marketplace manifest
zymtrace/                         # Plugin root  (== ${CLAUDE_PLUGIN_ROOT} at runtime)
  .claude-plugin/plugin.json      # Claude Code plugin manifest
  .codex-plugin/plugin.json       # Codex plugin manifest  (declares "skills": "./skills/")
  .cursor-plugin/plugin.json      # Cursor plugin manifest (declares "skills": "./skills/")
  shared/                         # Cross-skill docs (conventions.md, references.md)
  skills/<skill-name>/            # THE canonical source — every tool reads these
    SKILL.md                      # Required. Frontmatter + workflow.
    reference.md                  # Optional. Deep details for progressive disclosure.
    scripts/*.sh                  # Optional. Verify/diagnose helpers (executable).
    values/*.yaml                 # Optional. Helm values templates.
tests/                           # Structural pytest suite (no API keys / cluster)

Key conventions

• Versions stay in sync — the repo-root VERSION file is the single source of truth. The plugin is the versioned unit; skills carry no version. All three product plugin.json files (.claude-plugin/, .codex-plugin/, .cursor-plugin/) and the Claude marketplace.json plugin entry must match VERSION. Don't hand-edit them — run ./scripts/sync-version.sh (or ./scripts/sync-version.sh <new> to bump) to propagate, then make test to enforce it (test_version_file_is_source_of_truth).
• Multi-platform manifests are hand-written, not generated. One canonical source (zymtrace/skills/); each tool gets its own plugin.json (inside zymtrace/) and a repo-root marketplace file, all pointing at the same skills/. They differ only in per-tool metadata and field names. zymtrace bundles no MCP server, no hooks, no commands — the MCP is connected separately via configure-zymtrace-mcp and the gateway URL is per-deployment, so Codex install authentication is NONE. The product maps PRODUCT_PLUGIN_JSONS / PRODUCT_MARKETPLACE_JSONS in tests/conftest.py drive the structural tests that catch drift. Codex reads .agents/plugins/marketplace.json; Cursor reads .cursor-plugin/marketplace.json.
• Intra-plugin paths use ${CLAUDE_PLUGIN_ROOT}, never bare relative paths. Skills run with the user's working directory, not the skill directory, as cwd. Any script the skill runs or reference file it reads must be addressed as ${CLAUDE_PLUGIN_ROOT}/skills/<skill>/scripts/<x>.sh / ${CLAUDE_PLUGIN_ROOT}/skills/<skill>/reference.md. Enforced by tests/structural/test_paths.py. (Markdown navigation links between skills, e.g. [expose-zymtrace-backend](../expose-zymtrace-backend/SKILL.md), may stay relative — the agent resolves those when reading a known file.)
• Scripts are executable (chmod +x) and invoked as bash ${CLAUDE_PLUGIN_ROOT}/....
• Skill name == directory name.
• Frontmatter is just name and description (with Trigger phrases:) — the only fields skills use. No metadata block (author/repository/keywords live in plugin.json); no per-skill version (the plugin is the versioned unit).
• Secrets never touch disk or chat — see each skill's ## Security constraints.
• Helm conventions (namespace/release resolution, the single canonical values file, --reset-then-reuse-values, backups) are centralized in zymtrace/shared/conventions.md; skills link back to it rather than repeating it.