Plans

Add a share-react skill to social-media-tools

High completed
2026-06-09 agentics feature High effort
Objective

Ship a share-react skill for social-media-tools that turns any React component into one dark-mode social card — a rendered static preview (up to three states), the implementation code, and a full typed props table — then wire it into the router, templates, reference docs, README, tests, and release metadata so it ships as a first-class share-* skill.

Implement Read and implement all steps in the plan at docs/plans/add-share-react-skill.md — Add a share-react skill to social-media-tools. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/add-share-react-skill.md — tick each step's [x] marker and each criterion's - [x], set status: completed — and re-render the HTML from the spec. If any check failed, leave status: in-progress and say which.
More ways to run this plan — goal & workflow prompts, file path
Pursue as goal — optimize for the outcome, in parallel
Achieve this goal: Add a share-react skill to social-media-tools. The plan at docs/plans/add-share-react-skill.md describes one approach — use it as reference, but optimize for the outcome. Fan out across parallel subagents where that serves the outcome. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/add-share-react-skill.md — tick each step's [x] marker and each criterion's - [x], set status: completed — and re-render the HTML from the spec. If any check failed, leave status: in-progress and say which.
Run as workflow — launch parallel subagents
Run a workflow to implement the plan at docs/plans/add-share-react-skill.md — Add a share-react skill to social-media-tools. Brief subagents with the plan file at docs/plans/add-share-react-skill.md. Reserve a final verification phase for the lead agent, not a subagent. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/add-share-react-skill.md — tick each step's [x] marker and each criterion's - [x], set status: completed — and re-render the HTML from the spec. If any check failed, leave status: in-progress and say which.
File add-share-react-skill.html
Path docs/plans/add-share-react-skill.html
Spec docs/plans/add-share-react-skill.md
Definition of done 9 / 9 done

Context

The story behind this plan — what prompted the work and why it matters now.

social-media-tools ships eleven share-* skills built on one skeleton: locate plugin assets, load SOCIAL.md , capture input, reuse-check, run the security-scrub gate , draft platform-aware copy, populate a {{VARIABLE}} card template, persistent-save to docs/media/social/ , Playwright-screenshot the card, and deliver. The closest siblings — share-github and share-selection — render code into snippet-card.html . None of them shows a component's rendered appearance or its API.

React developers want to share a component as three things at once: what it looks like, how it is built, and how to use it (its props). share-react fills that gap by combining a visual preview, the implementation, and a typed props table in a single card.

Design decisions locked during clarify and the alignment stress-test:

Preview = static mockup. Claude reads the component and hand-builds an HTML/CSS approximation of its rendered output (up to three states). There is no React or Babel runtime, so the existing static screenshot pipeline works unchanged. The two live-render approaches become Wish List flags.

Input = path or selection, equal footing. Accept a .tsx / .jsx file path argument or an IDE selection / pasted code block (mirroring share-selection 's capture).

Props = full API, types first. Parse the component's TypeScript Props interface / type alias or propTypes for name · type · required · default · description, falling back to inference from JSX usage when no explicit types exist.

Router = any React file. The social-share router sends any .tsx / .jsx selection to share-react . This intentionally makes share-react the default for React files, intercepting the generic snippet path; a plain non-React snippet still falls through to share-selection .

A new skill is not a single file: it touches the SKILL.md , a new card template, a props reference, the social-share router, references/variables.md , the README, the repo-root CLAUDE.md row, the CHANGELOG.md , plugin.json keywords, the marketplace.json version, and committed tests.

Files that change

Every file this plan touches, and what happens to each one.

agentics/
  • kit/plugins/social-media-tools/skills/share-react/SKILL.md new share-react skill workflow
  • references/props-extraction.md new props parsing + row rendering
  • kit/plugins/social-media-tools/templates/react-card.html new preview + code + props card
  • kit/plugins/social-media-tools/skills/social-share/SKILL.md modified add .tsx/.jsx router rule
  • kit/plugins/social-media-tools/references/variables.md modified document react-card variables
  • kit/plugins/social-media-tools/
    • README.md modified skill + card-type tables, tree
    • CHANGELOG.md modified v2.11.0 entry
  • kit/plugins/social-media-tools/.claude-plugin/plugin.json modified add react keywords
  • .claude-plugin/marketplace.json modified bump to 2.11.0 + tags
  • CLAUDE.md modified update plugin table row
  • tests/social-media-tools/
    • test-react-card-smoke.sh new objective smoke test
    • test-share-react-registration.sh new wiring / registration test
    • README.md new manual E2E run instructions

Steps

The step-by-step work, in order — each step says what to do, why it matters, and how to check it worked.

1
done Scaffold skills/share-react/SKILL.md with the full phase workflow
Why
SKILL.md is the only runtime artifact Claude loads; mirroring the shared share-* skeleton makes share-react behave like its siblings and keeps the scrub gate non-bypassable.
Verify
Create kit/plugins/social-media-tools/skills/share-react/SKILL.md with three-part frontmatter and the phases: Locate assets, load SOCIAL.md , capture (a .tsx / .jsx path or IDE selection/paste), reuse-check, security-scrub, extract props, build static preview (up to 3 states), draft takeaway-first copy, populate react-card.html , persistent-save, screenshot, deliver. Verify: head -6 SKILL.md shows valid frontmatter; the description is the three-part format ≤200 chars; allowed-tools lists AskUserQuestion, Read, Write, Bash, Glob, Grep, ToolSearch, ExitPlanMode, Skill, SendUserFile ; the body names every phase and the GATE RESULT scrub check.
2
done Create the templates/react-card.html card template
Why
The card is the visual deliverable; reusing snippet-card's proven CSS and CDN means the unchanged Playwright pipeline screenshots it correctly, and a four-zone layout delivers preview + implementation + props in one image. {{COPY_PANELS}} keeps its standard plugin semantics: the social post copy panel(s) rendered below the card — platform post text plus a copy button — populated per references/copy-panels.md , exactly as in snippet-card.html.
Verify
Build kit/plugins/social-media-tools/templates/react-card.html with four zones — header ( {{COMPONENT_NAME}} + {{FRAMEWORK_BADGE}} ), a preview pane that injects {{PREVIEW_MARKUP}} as raw skill-authored HTML, an implementation block ( {{COMPONENT_CODE}} , highlight.js language-tsx ), and a semantic props table ( {{PROPS_ROWS}} : name · type · required · default · description) — plus {{REPO_SLUG}} , {{SOURCE_PATH}} , and {{COPY_PANELS}} . Reuse snippet-card's dark-mode tokens, --card-width , and highlight.js CDN. Verify: open the file; all {{…}} variables present; the --card-width CSS custom property is declared in the template's :root ; the props table uses <th scope="col"> ; a header comment states that {{PREVIEW_MARKUP}} is injected raw while {{COMPONENT_CODE}} / {{PROPS_ROWS}} /name/path are HTML-escaped by the skill.
3
done Write the references/props-extraction.md reference
Why
Progressive disclosure keeps SKILL.md lean and gives the props-table logic one authoritative source the skill links to one level deep — matching how share-github offloads variable rules to references.
Verify
Write kit/plugins/social-media-tools/skills/share-react/references/props-extraction.md describing how to build the full-API props table: parse a TS interface / type Props or propTypes for name · type · required · default · description; fall back to inferring the list from JSX destructuring/usage when no types exist; emit HTML-escaped <tr> rows for {{PROPS_ROWS}} . Verify: file exists; documents both the typed path and the inference fallback; shows the <tr> row template and the mandatory ampersand-first &amp; &lt; &gt; &quot; escaping order; SKILL.md links to it by relative path.
4
done Register the skill in the social-share router
Why
The router is how passive "share this" intent reaches a skill; without a rule, share-react never auto-dispatches. Per the locked decision, React files default to share-react.
Verify
Modify kit/plugins/social-media-tools/skills/social-share/SKILL.md Phase 1 classification table: add a rule that routes any selected/open/path .tsx / .jsx React file to share-react , placed above the existing selection rule (#4) so React files prefer the component card. Verify: re-read the table; a .tsx / .jsx row targets share-react and sits above the share-selection row; renumber the rules and confirm first-match-wins still falls through to share-selection for non-React code.
5
done Document react-card.html in references/variables.md
Why
variables.md is the shared contract every card template documents; an undocumented template drifts and breaks future edits.
Verify
Add a react-card.html section to kit/plugins/social-media-tools/references/variables.md — a Contents link plus a variable table for {{COMPONENT_NAME}} , {{FRAMEWORK_BADGE}} , {{PREVIEW_MARKUP}} , {{COMPONENT_CODE}} , {{PROPS_ROWS}} , {{REPO_SLUG}} , {{SOURCE_PATH}} , {{COPY_PANELS}} , with an explicit escaped-vs-raw note. Verify: open variables.md; the Contents list links #react-cardhtml ; the table lists all eight variables and flags {{PREVIEW_MARKUP}} as raw and everything else as HTML-escaped.
6
done Update the human-facing docs (README + root CLAUDE.md )
Why
README and the root CLAUDE.md are how humans and Claude discover the plugin's surface; the marketplace conventions require docs to stay in sync with plugin changes.
Verify
Add share-react to the README's Features table, Skills activation table, and Card Types table, and add the new files to the Plugin Structure tree in kit/plugins/social-media-tools/README.md ; update the social-media-tools row in the repo-root CLAUDE.md plugin table to mention share-react. Verify: grep -n share-react kit/plugins/social-media-tools/README.md returns hits in all three tables and the tree; the CLAUDE.md social-media-tools row names share-react.
7
done Cut the release — bump version, tags, keywords, and changelog
Why
A new skill is a MINOR bump per the marketplace rules; the version, tags, and changelog are what actually ship, and the post-write hook validates marketplace.json JSON syntax.
Verify
Bump the social-media-tools version in .claude-plugin/marketplace.json from 2.10.1 to 2.11.0 and add react / component / jsx tags; add matching react , component , jsx keywords to kit/plugins/social-media-tools/.claude-plugin/plugin.json ; add a ## v2.11.0 — 2026-06-09 entry to kit/plugins/social-media-tools/CHANGELOG.md under an ### Added heading. Verify: a python3 -c read of marketplace.json prints version 2.11.0 ; the CHANGELOG top entry is v2.11.0 ; plugin.json keywords include react ; marketplace.json still parses.
8
done Add smoke + registration tests under tests/social-media-tools/
Why
The repo's tests are bash smoke scripts under tests/<area>/ ; committing these makes the objective and the wiring re-checkable on every change.
Verify
Add tests/social-media-tools/test-react-card-smoke.sh (populate react-card.html with a sample component + a 3-row props table + a preview block, serve it, assert the preview pane, highlighted code block, and props rows render and no {{…}} placeholders remain) and tests/social-media-tools/test-share-react-registration.sh (assert marketplace version 2.11.0 , a share-react router rule, valid skill frontmatter, and README listing). Also add tests/social-media-tools/README.md documenting the manual E2E run procedure (load the plugin, invoke share-react on a sample component, confirm the saved HTML + PNG). Verify: bash tests/social-media-tools/test-react-card-smoke.sh and bash tests/social-media-tools/test-share-react-registration.sh both exit 0, and tests/social-media-tools/README.md exists with the E2E procedure.

Tests

The tests that prove the change does what it promises.

Tier 1 — Code-touching plan
Objective share-react card shows preview + implementation + props File: tests/social-media-tools/test-react-card-smoke.sh Type: smoke test Asserts: populating react-card.html with a sample Button.tsx (implementation code + a 3-row props table + a static preview block) yields rendered HTML containing a preview pane, a language-tsx code block, and ≥1 props <tr> row — and zero {{…}} placeholders remain — directly proving the card "shares a React component with a preview of the component and its implementation with props". Run: bash tests/social-media-tools/test-react-card-smoke.sh
Integration Skill registration + version wiring File: tests/social-media-tools/test-share-react-registration.sh Targets: marketplace.json version, the social-share router table, share-react/SKILL.md frontmatter, the README listing. Key cases: social-media-tools version equals 2.11.0 ; the router table contains a .tsx / .jsx → share-react rule above rule #4; SKILL.md frontmatter has name + description + allowed-tools ; the README Skills table lists share-react.
E2E Live skill run produces a saved card + PNG File: manual / agent E2E against the loaded plugin (run instructions documented in tests/social-media-tools/README.md , created in Step 8; uses the existing shared references/rendering-pipeline.md plugin reference). Targets: the full Locate → Capture → Scrub → Extract → Preview → Populate → Screenshot → Deliver path on a real component. Key cases: invoking share-react on a sample Button.tsx saves both react-<slug>-<date>.html and a matching .png to docs/media/social/ ; the saved filename follows the react-<slug>-<date> convention matching other share-* outputs; the scrub gate fired; the local HTTP server is killed afterward (no dangling process).

Definition of done

The plan counts as done when every statement below is true — check each one off as you verify it.

Final check

One last pass to confirm the whole change works end to end.

Load the plugin with claude --plugin-dir ./kit/plugins/social-media-tools , then confirm end-to-end:

Typed component. Run share-react against a sample Button.tsx with a TS Props interface and confirm one card shows a rendered preview (up to 3 states), the implementation code, and a full props table; a matching react-*.html + .png land in docs/media/social/ ; copy panels are present; and the security-scrub gate fired in the transcript.

Inference fallback. Run it against an untyped .jsx component and confirm the props table is inference-populated without crashing.

Router. Ask "share this component" with a .tsx selected and confirm the router dispatches to share-react , not share-selection .

Tests. Run bash tests/social-media-tools/test-react-card-smoke.sh and bash tests/social-media-tools/test-share-react-registration.sh — both exit 0.

Release metadata. Run /validate-plugin social-media-tools and confirm marketplace.json parses and the version reads 2.11.0 .

Wrapping up

Three gates that must all pass before this plan is marked completed.

Required

Completion Report

No items to report — all requirements met.

Next steps

Follow-up ideas that came up along the way — none of them are required to finish this plan.

Add a --states control to share-react

Paste this prompt into Claude to execute this follow-up:

In the social-media-tools plugin, extend the share-react skill (kit/plugins/social-media-tools/skills/share-react/SKILL.md) with an optional --states flag. When provided (e.g. --states=default,disabled,loading), the build-static-preview phase renders exactly those named states in the preview pane of react-card.html instead of Claude inferring up to 3. Document the flag in the skill body and the plugin README, and bump the marketplace.json version with a matching CHANGELOG entry.
Teach share-react to resolve local imports in the preview

Paste this prompt into Claude to execute this follow-up:

In the social-media-tools plugin, improve share-react's static preview fidelity: when the target React component imports sibling components from the same project, read those source files (within the git root only) so the hand-built static mockup approximates their rendered output instead of showing empty placeholders. Update kit/plugins/social-media-tools/skills/share-react/SKILL.md and its preview/props references, and add a smoke test that a component importing a sibling still renders a non-empty preview pane.
Live CDN render mode ( --live ) Wish List

Speculative / blue-sky idea — not on the critical path. Paste into Claude when ready to explore:

Paste this prompt into Claude to execute this follow-up:

Run a workflow to add an optional live-render mode to the social-media-tools share-react skill. Create a second template (react-card-live.html) that loads React 18 + ReactDOM + Babel-standalone from a CDN, embeds the component source in a script type="text/babel" block, and renders it into the preview pane so Playwright screenshots a TRUE render after networkidle. Gate it behind a --live flag and fall back to the static mockup when the component has unresolved imports. Update the skill, references/variables.md, README, CHANGELOG, and marketplace.json version, and add a smoke test that the live card renders a self-contained component.
Storybook / dev-server capture mode ( --story ) Wish List

Speculative / blue-sky idea — not on the critical path. Paste into Claude when ready to explore:

Paste this prompt into Claude to execute this follow-up:

Run a workflow to add a Storybook/dev-server capture mode to the social-media-tools share-react skill. Add a --story=<url-or-id> flag: instead of building a static mockup, Playwright navigates to the component running in the project's Vite/Next/Storybook URL and screenshots the real rendered component for the preview pane, while still showing the implementation code and props table. Handle the no-server case gracefully with a clear error. Update the skill, README, CHANGELOG, and marketplace.json version.