open-design/plugins/spec/AGENT-DEVELOPMENT.md

Agent Development Handoff

Language: English | 简体中文

Give this file to a coding agent when you want it to create or improve an OpenDesign plugin.

Mission

Create a portable OpenDesign plugin that can:

1. Run as a normal Agent Skill through SKILL.md.
2. Install into OpenDesign through open-design.json.
3. Be validated locally.
4. Be published as an independent open source repo or submitted as a PR to OpenDesign.

Required Reading

Read these files before editing:

• plugins/spec/SPEC.md
• docs/schemas/open-design.plugin.v1.json
• docs/plugins-spec.md when you need deeper product semantics
• plugins/spec/PUBLISHING-REGISTRIES.md when the user asks to publish outside OpenDesign
• A nearby example under plugins/spec/examples/

Build Procedure

1. Choose a lowercase plugin id, for example import-screenshot-to-prototype.
2. Create a folder with at least:

<plugin-id>/
  SKILL.md
  open-design.json
  README.md

3. Keep the SKILL.md portable. It may mention OpenDesign behavior, but the core workflow must still make sense in any Agent Skills compatible agent.
4. Put OD-specific display, specVersion, plugin version, inputs, preview, pipeline, atoms, connectors, and capabilities in open-design.json.
5. Add examples/, preview/, assets/, or references/ only when they materially help the agent produce better results.
6. Add evals/evals.json when the plugin has enough behavior to regress.
7. If publishing externally, prepare registry-safe README sections for skills.sh, ClawHub, and canonical GitHub source.
8. For an HTML-backed visual artifact, ship the real sample as example.html and declare od.preview.type: "html" with entry: "./example.html". Keep od.useCase.exampleOutputs and od.context.assets aligned with that file. A poster image may be secondary, but it must not replace the HTML preview. When template.json carries referenceHtml, materialize the sample from that source (or the same deterministic generator) and keep them in sync.

Quality Bar

The plugin is not done until:

• SKILL.md has a clear "Use this plugin when..." description.
• The workflow states the expected output files or handoff result.
• open-design.json validates against the v1 shape and carries explicit specVersion plus plugin version.
• The declared atoms are known first-party atoms or clearly marked future work.
• The declared capabilities are the minimum needed.
• Visual plugins include a preview or concrete example output.
• HTML-backed previews load from the declared entry as 200 text/html; a preview-baker skip (status 404) is a failure for that plugin, even when the overall bake job remains green.
• Share, deploy, connector, and network plugins require explicit confirmation before externally visible actions.

Validation Commands

Run what is available in this environment:

pnpm guard
pnpm --filter @open-design/plugin-runtime typecheck

If the daemon CLI is built:

od plugin validate ./<plugin-id>
od plugin install ./<plugin-id>
od plugin apply <plugin-id> --input key=value

PR Output

When opening or preparing a PR, include:

• Plugin id, spec version, plugin version, and lane.
• What user request should trigger it.
• Files changed.
• Validation commands and results.
• Capabilities requested.
• Screenshots, preview URLs, or example artifacts for visual plugins.
• Registry links and dry-run output when publishing to skills.sh, ClawHub, or another skill registry.