Plans

Refine social-media-tools copy to teach, not just promote

Medium completed
2026-06-05 agentics refactor Medium effort
Objective

Rewire the social-media-tools voice so every generated post leads with a concrete, teachable takeaway about agentic development — turning the plugin's output from "look what I shipped" into a running, shareable curriculum that readers can learn from and apply.

Implement Read and implement all steps in the plan at docs/plans/refine-social-copy-instructional.md — Refine social-media-tools copy to teach, not just promote. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/refine-social-copy-instructional.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
Achieve this goal: Refine social-media-tools copy to teach, not just promote. The plan at docs/plans/refine-social-copy-instructional.md describes one approach — use it as reference, but optimize for the outcome. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/refine-social-copy-instructional.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 refine-social-copy-instructional.html
Path docs/plans/refine-social-copy-instructional.html
Spec docs/plans/refine-social-copy-instructional.md
Definition of done 7 / 7 done

Context

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

The social-media-tools plugin (currently v2.9.1) ships nine card-generating skills — share-code, share-selection, share-github, share-session, share-project, share-explanation, share-blog, share-video, plus the social-share router. They all draft copy from one shared doctrine in references/platforms.md , which today optimizes for reach and followers: a mandatory promotional "Follow CTA", a "thought leadership" framing on quote cards, and per-platform formats whose arc is hook → insight → CTA.

The owner wants the plugin to do double duty: its posts should still travel well, but they should primarily teach . Each post should leave the reader with a concrete principle or technique about agentic development they can apply — so the body of work becomes a learning resource, not a highlight reel. Because every skill reads the shared doctrine at runtime, the leverage point is centralized: change the doctrine and the per-skill Draft phases that echo it, and all skills inherit the instructional voice at once.

Confirmed decisions: keep a closing follow line but reframe it as a learn-more invitation (never a hard sell, always secondary to the takeaway); apply the refactor across the full plugin and the SOCIAL.md config (a new "Instructional" tone); ship as a MINOR bump to 2.10.0. Two interview rulings sharpen the doctrine: (1) the teaching-first voice is the unconditional default for every skill — the SOCIAL.md tone only nudges register (professional / conversational / technical) and can never switch the takeaway off; (2) on length-tight platforms (Twitter/X 280, Bluesky 300) the takeaway wins and the learn-more line is dropped , extending the existing "content wins" budget rule.

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 Add an "Instructional Voice" doctrine to the shared references/platforms.md and reframe its CTA and per-platform formats
Why
This file is read at runtime by every card-generating skill — adding the teaching-first doctrine here propagates the new voice to all nine skills in one edit, rather than nine divergent copies.
Verify
In kit/plugins/social-media-tools/references/platforms.md : a new "Instructional Voice" (teach, don't just promote) section exists and states the teaching-first arc is the unconditional default for every skill (tone only nudges register, never disables the takeaway); the "Follow CTA" section's examples are learn-more framed (e.g. "more agentic-dev breakdowns like this") with explicit "secondary to the takeaway, never a hard sell" guidance and a rule that on Twitter/X and Bluesky the takeaway wins and the learn-more line is dropped when budget is tight; each entry under "Default Per-Platform Copy Formats" names a concrete takeaway/lesson element. The post arc reads hook → takeaway/lesson → learn-more.
2
done Update each skill's Draft phase to require a concrete, applicable takeaway and point at the new doctrine
Why
Each SKILL.md layers content-specific copy guidance on top of the shared file; without updating these, individual skills (e.g. share-code's diff angle, share-session's recap) keep their old promotional/accomplishment-first arc.
Verify
The Draft phases of share-code , share-selection , share-github , share-session , share-project , and share-explanation SKILL.md each instruct the model to surface a teachable takeaway ("what the reader can learn or apply") and reference the Instructional Voice doctrine. No Draft phase frames the post as accomplishment-first or "thought leadership"-first.
3
done Rewrite the two skill-local copy-format references (share-blog, share-video) to lead with a lesson and use learn-more CTAs
Why
share-blog and share-video keep their own references/platforms.md with concrete LinkedIn/Substack templates; these must lead with a takeaway and reframe their subscribe/follow CTAs, or they will contradict the shared doctrine.
Verify
In skills/share-blog/references/platforms.md and skills/share-video/references/platforms.md : the LinkedIn and Substack structure lines name a takeaway/lesson as the lead element; example CTAs are learn-more / subscribe-to-learn framed, not hard-sell. Twitter/Bluesky examples still lead with the insight.
4
done Update the discovery heuristics so "shareable" is judged by teaching value
Why
share-scan and share-project decide what is worth posting; if their selection criteria still favor "impressive" changes over "instructive" ones, the upstream content choice undercuts the downstream instructional voice.
Verify
In skills/share-scan/references/interesting-patterns.md : shareability is scored by teaching/learning value (does this illustrate an agentic-dev lesson?) as a primary criterion. In skills/share-project/references/topics.md : the CTA note aligns with the learn-more framing from the shared doctrine.
5
done Add an "Instructional / Educational" tone to share-init and write it into the generated SOCIAL.md
Why
SOCIAL.md persists per-project register defaults that every skill reads. The teaching-first voice is always on (Step 1), so this tone only sets the register the lesson is delivered in — adding "Instructional / Educational" makes the educational register the recommended starting point without ever gating the takeaway.
Verify
In skills/share-init/SKILL.md : the Tone AskUserQuestion lists "Instructional / Educational" (recommended); the generated SOCIAL.md ## Defaults template documents the instructional register and notes the teaching-first voice applies regardless of tone. references/social-config.md mentions the new tone option so the config schema stays in sync.
6
done Reword the README, add a CHANGELOG entry, and bump marketplace.json to 2.10.0
Why
The README's "share/promote" language and the version metadata must reflect the new cross-cutting behavior; per repo convention the marketplace.json version is authoritative and a CHANGELOG entry is required for every bump.
Verify
.claude-plugin/marketplace.json shows social-media-tools at 2.10.0 ; kit/plugins/social-media-tools/CHANGELOG.md has a 2.10.0 entry describing the instructional refactor; the README describes the teaching-first voice and the new tone. The .claude/settings.json JSON-validation hook passes after the marketplace.json edit.

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.

End-to-end: from the plugin root, run grep -rniE "thought leadership|hard sell|promote" kit/plugins/social-media-tools/{references,skills} --include="*.md" and confirm the only remaining hits are intentional (e.g. README descriptive text), with no copy-doctrine instruction still framing posts as promotion-first. Then grep for the new vocabulary — grep -rni "instructional\|takeaway\|learn-more\|teach" kit/plugins/social-media-tools/references kit/plugins/social-media-tools/skills — and confirm the doctrine, the per-skill Draft phases, and the two skill-local references all reference it.

Behavioral check: invoke /social-media-tools:share-explanation "how does the security-scrub skill work" and confirm the drafted LinkedIn copy opens with a teachable principle (not "Here's how X works" or a follow plug), names 2–3 applicable patterns, and ends with a learn-more line that could be deleted without breaking the post. Repeat once with share-code on a recent diff to confirm the diff angle leads with the lesson, not the accomplishment.

Metadata check: confirm .claude-plugin/marketplace.json reports 2.10.0 for social-media-tools, the CHANGELOG has the matching dated entry, and the settings.json marketplace-validation hook reports no JSON errors.

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.

Regenerate the saved social cards under docs/media/social with the new voice

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

Review the saved social cards in docs/media/social/ in the agentics repo. For each one whose copy reads as promotion-first (accomplishment or follow-plug leads the post), regenerate it with the social-media-tools instructional voice: lead with a concrete, applicable takeaway about agentic development, keep any follow line as a secondary learn-more invitation. Report which cards you changed and which you left as-is and why.
Add an instructional-voice eval to lock the behavior in

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

Add a lightweight evaluation for the social-media-tools plugin that runs each card-generating skill against a fixed input and asserts the drafted copy leads with a teachable takeaway and treats any follow line as optional/secondary. Place fixtures under tests/fixtures/ and document how to run the check. Do not change skill behavior — only add the eval.
Build a dedicated "lesson-card" template for agentic-dev teaching posts 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:

Design a new social card template for the social-media-tools plugin called lesson-card.html, purpose-built for teaching posts: a prominent "what you'll learn" header, a numbered principle/steps region, and a small "try it yourself" footer instead of a follow CTA. Match the existing dark-mode design system of the other card templates, wire it into the template-selection heuristics, and document when skills should pick it.
Thread posts into a numbered "agentic dev" learning series 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:

Explore adding an optional "learning series" mode to the social-media-tools plugin: posts on a recurring topic get auto-numbered (e.g. "Agentic Dev #7") and cross-link to prior entries, so the body of work reads as a curriculum. Recommend where series state should live (SOCIAL.md? a manifest in docs/media/social/?) and sketch the minimal implementation.