vndangkhoa/open-design
1
0
Fork 0
mirror of https://github.com/nexu-io/open-design.git synced 2026-06-01 03:14:35 +07:00
Code Issues Projects Releases Packages Wiki Activity Actions 1
open-design/plugins/spec/AGENT-DEVELOPMENT.md
pftom 0edbf38171 feat(plugins): add specVersion and version fields to plugin and marketplace schemas 
- Introduced `specVersion` and `version` fields to the plugin and marketplace schemas, ensuring better versioning and compatibility tracking.
- Updated various components and functions to handle the new fields, including database migrations, plugin snapshots, and marketplace management.
- Enhanced tests to validate the presence and correctness of the new fields in plugin manifests and marketplace entries.
- Improved documentation to reflect the changes in schema requirements and provide guidance on the new versioning system.

This update strengthens the plugin ecosystem by providing clear versioning, enhancing the reliability and maintainability of plugins and marketplaces.
2026-05-13 22:24:50 +08:00

2.8 KiB
Raw Permalink Blame History

Agent Development Handoff

Language: English | 简体中文

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

Mission

Create a portable Open Design plugin that can:

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

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 Open Design
  • 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
  1. Keep the SKILL.md portable. It may mention Open Design behavior, but the core workflow must still make sense in any Agent Skills compatible agent.
  2. Put OD-specific display, specVersion, plugin version, inputs, preview, pipeline, atoms, connectors, and capabilities in open-design.json.
  3. Add examples/, preview/, assets/, or references/ only when they materially help the agent produce better results.
  4. Add evals/evals.json when the plugin has enough behavior to regress.
  5. If publishing externally, prepare registry-safe README sections for skills.sh, ClawHub, and canonical GitHub source.

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.
  • 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.