Skip to content

AGENTS.md

Latest commit

 

History

History
95 lines (57 loc) · 5.88 KB

AGENTS.md

File metadata and controls

95 lines (57 loc) · 5.88 KB
Raw

descript-plugin

Purpose

A Claude Code plugin giving full programmatic access to the Descript API. The plugin ships a Node/TypeScript CLI (descript) covering all 11 documented API endpoints plus polling, the three-step signed-URL upload, a bulk pipeline runner, and an MP4 + SRT + Markdown export workflow. Around the CLI sit nine skills and an optional in-process MCP shim. The CLI is the single source of truth, every skill and the MCP shim are thin wrappers that shell out to it, no API logic is duplicated.

Key Files

File Description
package.json NPM manifest. Type=module, zero runtime deps, devDeps TypeScript + @types/node, engines node>=24, scripts build/test/clean/smoke.
tsconfig.json Strict TS targeting ES2023 + nodenext, src + tests + scripts compiled to dist/.
.mcp.json MCP server declaration. Uses ${CLAUDE_PLUGIN_ROOT}/dist/src/mcp/server.js. No absolute paths.
.gitignore Excludes node_modules/, *.log, scripts/smoke/results/* (keeps .gitkeep).
CHANGELOG.md SemVer history. Current 0.3.0 (export + download-published, 2026-05-20).
CLAUDE.md Plugin's own short context-for-Claude file. Cost and risk gates. Layout invariants.
README.md User-facing install, setup, CLI surface, dev workflow.
LICENSE MIT.

Subdirectories

Directory Purpose
.claude-plugin/ Plugin manifest and standalone marketplace metadata (see .claude-plugin/AGENTS.md).
bin/ Thin shell entrypoint for the compiled CLI (see bin/AGENTS.md).
src/ TypeScript sources for the CLI, HTTP client, config, MCP shim, workflows (see src/AGENTS.md).
dist/ Compiled JS, committed for zero-install. Mirrors src/ and tests/ and scripts/ shape. Not documented (regenerated by npm run build).
skills/ Nine model-facing skills wrapping CLI commands (see skills/AGENTS.md).
tests/ Hermetic node:test suite, no live network (see tests/AGENTS.md).
scripts/ Dev-only smoke scripts (see scripts/AGENTS.md).
docs/ Field reports, help docs from Descript, plans, design specs (see docs/AGENTS.md).

For AI Agents

Working In This Directory

  • The CLI is the single source of truth. Skills shell out to descript ..., the MCP shim re-imports runCli in-process. Never duplicate API logic in either wrapper.

  • Plugin component directories live at the root (skills/, bin/, src/, dist/). The .claude-plugin/ folder holds only plugin.json and marketplace.json, do not move anything else inside.

  • All paths inside .mcp.json and skill scripts must use ${CLAUDE_PLUGIN_ROOT}, never absolute paths.

  • Zero runtime dependencies is a hard rule. Only devDependencies may grow. The runtime uses native Node 24 features (node:fetch, node:fs, node:test).

  • dist/ is committed so the plugin installs zero-install. After any change in src/ or tests/ or scripts/, rebuild with npm run build before committing.

Cost and Risk Gates

Only the Descript agent operation is billable on standard plans (AI credits and media seconds). Publish, batch, and export are gated for risk reasons not cost reasons. The gates (post v0.3.3, see docs/specs/2026-05-20-model-invocation-policy.md):

  • descript-batch carries disable-model-invocation: true. Operator only. The CLI's descript batch plan then descript batch run --confirm dance is the load-bearing safety mechanism; the skill flag is the honest signal of categorical risk class (bulk-write blast radius, possible AI-credit billing via agent_prompt items).

  • descript-edit, descript-publish, and descript-export are all model-invocable WITHOUT disable-model-invocation. Each is gated by a mandatory in-skill confirmation step so Claude can run them conversationally. descript-publish additionally defaults the access-level confirmation to private per the v0.3.3 ADR.

  • descript-download-published is read-only and unrestricted.

  • The batch dry-run gate is mandatory regardless of whether a manifest includes agent_prompt items.

  • Always report ai_credits_used and media_seconds_used when the agent runs (zero is expected for publish-only and import-only flows).

Rule of thumb for future contributors - Operator-gate any skill whose blast radius extends beyond a single composition, or that can spend AI credits transitively via agent_prompt items. Otherwise default to model-invocable with the in-skill confirmation pattern (matching descript-edit, descript-export, descript-publish).

Build and Test

  • npm install once after clone (only dev deps).

  • npm run build compiles src/ + tests/ + scripts/ to dist/.

  • npm test rebuilds then runs node --test "dist/tests/**/*.test.js". All tests are hermetic (no live API).

  • npm run smoke:concurrency runs a live read-mode smoke against the Descript API to empirically discover the rate-limit ceiling. Excluded from npm test. Requires a real token. Writes to scripts/smoke/results/ (gitignored).

Versioning

SemVer in both plugin.json and package.json. Keep them aligned. Tag vX.Y.Z. Update CHANGELOG.md with the user-visible delta. Per the user's global preferences, present a scope review before tagging or pushing any version bump.

Distribution

Dual marketplace shape. The plugin is installable directly from this repo (.claude-plugin/marketplace.json declares it as a one-plugin standalone marketplace) and is also expected to be aggregated into Julian's broader marketplace.

Dependencies

External (devDependencies only)

  • typescript ^5.6.0 - compiler.

  • @types/node ^24.0.0 - Node type definitions.

Runtime (none)

  • Uses only Node 24 builtins (node:fetch, node:fs, node:os, node:path, node:url, node:test, node:assert, node:child_process).