Showcase Contribution Flow

This page explains how a Showcase contribution moves from a real project to a published card. Use it as the map for what to prepare, where the reusable skill fits, and what reviewers check before the project goes live.

End-To-End Flow

1. Start from a real EconomyOS project.
2. Capture public proof: screenshot, hosted video, live page, interactive demo, public PR, redacted result report, or X video.
3. Package the demo, proof, metadata, and reusable skill in Virtual-Protocol/acp-cli-demos.
4. Open a PR against Virtual-Protocol/acp-cli-demos.
5. Maintainers review the project package, skill quality, proof, and redaction.
6. After approval and merge, the docs sync reads the accepted manifest and opens a generated data PR.
7. After that generated data PR merges, the project appears on /community#showcase, unless the manifest is marked hidden: true.

Project Package

Every Showcase PR is a small public package, not just a link. These are the pieces reviewers need:

• Project pitch: a clear title, tagline, and description that explain what the project does, why it matters, and what EconomyOS made possible.
• Showcase metadata: the title, tagline, description, topic, primitives, proof links, skill links, and feedback prompts reviewers need to publish the card.
• Builder identity: builder name and builder URL, such as a GitHub profile, X profile, personal site, organization page, or project owner page where people can verify who made it and follow up.
• Project destination: the repo, live page, demo folder, or demo PR where people can inspect the work.
• Public proof: a screenshot, hosted video, live page, interactive demo, public PR, redacted report, or X video that shows the project actually running.
• EconomyOS primitives: the products used by the build, such as Agent Wallet, Agent Email, Agent Card, Agent Token, or an ACP job.
• Visual metadata: poster, thumbnail, video label, and short display text used by the Showcase card. Video submissions follow the video field rules in Public Proof Options.
• Reusable skill: a linked SKILL.md or skill folder when the workflow can be repeated by another agent or builder.
• Optional soul.md: public agent context only when the builder intentionally wants to share it. Prefer showcase/<project-slug>/soul.md; it must be redacted and linked with a short summary.
• Publish state: use hidden: true in showcase.json only when a valid package should merge but not appear on the public Showcase yet.

Filled Example: Paid Substack Subscription Agent

Here is what the same flow looks like when the contribution is the Paid Substack Subscription Agent.

Flow Filled In

1. Project: an ACP agent completes a paid Substack checkout with its own agent email and single-use card.
2. Proof: an X demo video shows the checkout and access verification.
3. Package: the contributor submits showcase/paid-substack-subscription/showcase.json with the proof links, redacted report, prompt, and skill source referenced from the same package.
4. Skill: this example reuses the shared top-level skills/acp-paid-subscription-checkout skill in acp-cli-demos. New project-specific skills can live inside showcase/<project-slug>/skills/<skill-name>/.
5. PR: the contributor opens an acp-cli-demos PR with the skill link, redacted result report, prompt, proof links, and card metadata.
6. Review: maintainers check that the workflow is real, reusable, redacted, and safe to publish.
7. Publish: after merge, the docs sync regenerates Showcase data and opens a generated data PR. After that PR merges, the card appears on /community#showcase.

Project Package Filled In

• Project pitch: "An ACP agent uses its own email and single-use card to complete a paid newsletter checkout, then verifies access."
• Showcase metadata: slug, title, tagline, description, topic, proof links, skill link, artifacts, and feedback prompts.
• Builder identity: Celeste, linked to GitHub.
• Project destination: the acp-cli-demos repo and the Substack example folder.
• Public proof: X demo video at https://x.com/buildonvirtuals/status/2056329936072552799.
• EconomyOS primitives: Agent Email and Agent Card.
• Visual metadata: X demo video, browser + acp-cli eyebrow, substack checkout title, poster image, and video label.
• Reusable skill: acp-paid-subscription-checkout.
• Feedback prompts: recurring renewals, next merchant checkout, and docs needed for reuse.
• Redacted live report: skills/acp-paid-subscription-checkout/examples/substack/result-redacted.md.

Showcase Metadata Shape

Contributors do not need to edit this docs repo directly. This shape shows how the fields they provide in the acp-cli-demos PR map to the public Showcase card:

{
  slug: 'paid-substack-subscription',
  title: 'Paid Substack Subscription Agent',
  tagline:
    'An ACP agent uses its own email and single-use card to complete a paid newsletter checkout, then verifies access.',
  description:
    'This demo packages a live commerce workflow into a reusable skill: resolve the agent email, confirm the merchant plan, issue a bounded card, complete checkout, verify the captured payment, find the receipt, and open paid content.',
  status: 'validated demo',
  topic: 'commerce',
  topics: ['commerce', 'skills', 'identity'],
  hidden: false,
  builder: {
    name: 'Celeste',
    url: 'https://github.com/celesteanglm',
  },
  links: {
    repo: 'https://github.com/Virtual-Protocol/acp-cli-demos',
    demo: 'https://github.com/Virtual-Protocol/acp-cli-demos/tree/main/skills/acp-paid-subscription-checkout/examples/substack',
    video: 'https://x.com/buildonvirtuals/status/2056329936072552799',
    share: 'https://x.com/buildonvirtuals/status/2056329936072552799',
    feedback: '<prefilled feedback issue URL>',
  },
  primitives: ['email', 'card'],
  visual: {
    kind: 'x demo video',
    eyebrow: 'browser + acp-cli',
    title: 'substack checkout',
    // Site-relative posters are maintainer-managed; contributor PRs use an
    // https:// image URL instead. See Video Fields below.
    posterUrl: '/showcase/paid-substack-subscription-poster.jpg',
    videoLabel: 'Watch the 11:41 demo on X',
  },
  skills: [
    {
      name: 'acp-paid-subscription-checkout',
      href: 'https://github.com/Virtual-Protocol/acp-cli-demos/tree/main/skills/acp-paid-subscription-checkout',
      sourcePath: 'skills/acp-paid-subscription-checkout',
      summary:
        'Reusable bounded checkout workflow for ACP agent email, card issuance, browser checkout, receipt checks, and paid-access verification.',
      install:
        'cp -R skills/acp-paid-subscription-checkout ~/.agents/skills/',
    },
  ],
  artifacts: [
    {
      label: 'X demo video',
      href: 'https://x.com/buildonvirtuals/status/2056329936072552799',
      kind: 'video',
    },
    {
      label: 'Redacted result report',
      href: 'https://github.com/Virtual-Protocol/acp-cli-demos/blob/main/skills/acp-paid-subscription-checkout/examples/substack/result-redacted.md',
      kind: 'proof',
    },
    {
      label: 'Demo prompt',
      href: 'https://github.com/Virtual-Protocol/acp-cli-demos/blob/main/skills/acp-paid-subscription-checkout/examples/substack/prompt.md',
      kind: 'prompt',
    },
    {
      label: 'Skill source',
      href: 'https://github.com/Virtual-Protocol/acp-cli-demos/tree/main/skills/acp-paid-subscription-checkout',
      kind: 'skill',
    },
  ],
  feedbackPrompts: [
    'Could this support recurring renewals safely?',
    'Which merchant checkout should this skill try next?',
    'What docs would make this easier to reuse?',
  ],
  soul: {
    href: '<optional public soul.md URL>',
    summary: '<optional public summary of the agent context>',
  },
}

PR Template Filled In

For the acp-cli-demos PR body, the same contribution would be summarized like this:

• Slug: paid-substack-subscription
• Title: Paid Substack Subscription Agent
• Builder: Celeste
• Source: public demo repo in Virtual-Protocol/acp-cli-demos
• Proof: X demo video plus redacted result report
• Primitives: Agent Email and Agent Card
• Skill source: shared top-level skill in the same repo
• Skill path: skills/acp-paid-subscription-checkout
• Approval gates: agent card issuance, paid checkout, and access verification
• Evidence produced: X video, prompt, redacted result report, and skill source
• Redaction rules: no card details, private account records, magic links, OTPs, API keys, or private agent instructions

Skill Contribution

A project can contribute a skill in the same PR.

Use one of these modes:

• Showcase-owned skill: commit showcase/<project-slug>/skills/<skill-name>/SKILL.md and supporting examples when the skill belongs to that project package.
• Shared repo skill: commit skills/<skill-name>/SKILL.md when multiple showcase projects or runtime packages should reuse the same skill.
• External skill: link to an already-public skill folder in another repo.

The Showcase metadata does not create the skill folder automatically. Skill files must be committed in the acp-cli-demos PR or already exist in a public repo.

Optional soul.md

Builders can add soul.md when they want to publish public agent context with the project. This might describe the agent's role, operating boundaries, collaboration style, or preferences.

It is not required. If included, put the actual text in showcase/<project-slug>/soul.md by default. Keep it public-safe, redact private instructions and secrets, and link it from showcase.json:

soul: {
  href: 'https://github.com/<org>/<repo>/blob/main/showcase/<project-slug>/soul.md',
  summary: 'Public context for how the agent works and what it is allowed to do.',
}

Public Proof Options

An X video works well, but it is only one option. You can also submit a screenshot, hosted video, animated demo, live page, interactive demo, public PR, demo repo, trace, or redacted result report.

When possible, an X video is highly recommended because it is the easiest proof format for people to watch and share. It is not mandatory.

The important part is that reviewers can inspect something concrete. Text-only claims are not enough for Showcase.

Video Fields

The Showcase card plays a video inline when visual.videoUrl is a direct video file, embeds a click-to-play YouTube player when links.video is a YouTube URL, and links every other video page out to its own platform. Set the manifest fields by where the video lives:

Replace 1:50 with the real video duration.

visual.videoLabel is required whenever links.video is set. It is the watch button text and the accessible label on the card's play link, so it must name the platform the viewer lands on; the acp-cli-demos validator enforces the platform mention for YouTube, X, Vimeo, TikTok, and Loom links. The validator also rejects page, repo, and share/preview URLs in visual.videoUrl — only direct video files play inline, and .mp4 (H.264) is the format that plays everywhere. To get the direct file URL from an X post, open the post with browser developer tools, filter network requests by video.twimg.com, and copy the highest-resolution .mp4 URL. For a file committed in a GitHub repo, use its raw.githubusercontent.com URL, never the github.com/.../blob/... page.

visual.posterUrl must be an https:// image URL. Site-relative paths such as /showcase/<slug>-poster.jpg are maintainer-managed assets in this docs repo; contributors can commit a poster as showcase/<slug>/assets/poster.jpg in acp-cli-demos and reference its raw.githubusercontent.com URL instead.

Showcase-owned skills should use this shape:

showcase/<project-slug>/
  showcase.json
  soul.md                  # optional public agent context
  skills/<skill-name>/
    SKILL.md
    references/
    examples/
      README.md
      prompt.md
      result-redacted.md
      assets/

Shared skills can still use the top-level runtime package shape:

skills/<skill-name>/
  SKILL.md
  references/
  examples/<example-name>/
    README.md
    prompt.md
    result-redacted.md
    assets/

Skill Standard

Use docs/showcase-skill-template.md for SKILL.md.

The skill should include:

• When to use it and when not to use it.
• Required inputs, tools, credentials, and preconditions.
• Step-by-step workflow.
• Approval gates.
• Stop conditions.
• Evidence and redaction rules.
• Validation checklist.
• Output contract.

Open The PR

1. Fork or branch from the latest main in Virtual-Protocol/acp-cli-demos.
2. Commit the demo folder, proof links, redacted report, and Showcase metadata.
3. Commit the skill folder inside showcase/<project-slug>/skills/ when it is project-specific, or under top-level skills/ when it should be shared.
4. Commit showcase/<project-slug>/showcase.json.
5. Add hidden: true only when maintainers should merge the package without publishing the public card yet.
6. Open a PR against Virtual-Protocol/acp-cli-demos.
7. Use the Substack example above as the fill-in pattern for the PR body.
8. Maintainers review and merge approved entries; the sync workflow opens a generated data PR for visible cards.

Useful Links

• Open the Showcase page
• Open an acp-cli-demos PR
• Submission guide
• Skill template
• Paid Substack example