Plans

Add explain-codebase skill to social-media-tools

Medium completed
2026-06-03 agentics feature Medium effort
Objective

Ship an explain-codebase skill that answers natural-language questions like "how does the share-session skill work" by reading source files, synthesizing a structured developer-friendly explanation of fundamental principles, and delivering it with platform-aware social copy and a dark-mode card image — following the same pipeline as all other share-* skills.

Implement Read and implement all steps in the plan at docs/plans/add-codebase-explain-skill.md — Add explain-codebase 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-codebase-explain-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
Achieve this goal: Add explain-codebase skill to social-media-tools. The plan at docs/plans/add-codebase-explain-skill.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/add-codebase-explain-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-codebase-explain-skill.html
Path docs/plans/add-codebase-explain-skill.html
Spec docs/plans/add-codebase-explain-skill.md
Definition of done 4 / 4 done

Context

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

The social-media-tools plugin ships twelve skills across share-*, social-share, and media-library workflows. When a developer wants to understand how a specific skill operates — its phases, patterns, invocation syntax, and file layout — they have to read raw SKILL.md files directly. There is no conversational entry point that reads those files and explains the underlying principles.

An explain-codebase skill fills that gap: parse the question, locate the relevant files (SKILL.md, reference docs, scripts), read them, synthesize a structured developer-friendly answer, and then deliver the output the same way every other share-* skill does — security scrub the content, draft platform-aware social copy, populate a card template ( feature-card.html for skill/component explanations, quote-card.html for concept/pattern explanations), screenshot via the rendering pipeline, save persistently to docs/media/social/ , and deliver copy + image in the same turn.

This also closes a routing gap in social-share : "how does X work" queries currently fall through to the share-code fallback, which is wrong. A new classification rule fixes the routing.

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 Create skills/explain-codebase/SKILL.md with the full workflow
Why
This is the core deliverable. The SKILL.md must cover nine phases that mirror the share-* pipeline exactly: (a) Phase 0 — silently locate PLUGIN_DIR using the same find-chain all other skills use; (b) Phase 0b — load SOCIAL.md config for platform/tone defaults; (c) Phase 1 — parse $ARGUMENTS for target name/concept and optional --platform / --tone flags; (d) Phase 1c — reuse check against docs/media/social/ (read references/reuse-check.md ); (e) Phase 2 — map target to files: skill name → skills/<name>/SKILL.md + referenced files; concept keyword → grep references/ and skill bodies; (f) Phase 3 — Read all located files and synthesize explanation with sections: Core Purpose, Activation Conditions, Workflow Phases, Key Patterns, Important Files, Invocation; (g) Phase 4 — security scrub the full synthesis (write to ~/.claude/tmp/scrub-input.txt , invoke security-scrub skill, check GATE RESULT — BLOCKED is a hard stop); (h) Phase 5 — draft platform-aware social copy from the synthesis following references/platforms.md rules — lead with the core principle, not process; (i) Phase 6 — populate card template: skill/component target → feature-card.html (TITLE=skill name, SUBTITLE=one-line purpose, BULLETS=key workflow phases), concept/pattern target → quote-card.html (QUOTE=core principle, ATTRIBUTION=skill/file name, CONTEXT=pattern category); (j) Phase 6b — persistent save to docs/media/social/ (read references/saving-and-delivery.md ); (k) Phase 7 — screenshot via Playwright (read references/rendering-pipeline.md ); (l) Phase 8 — deliver: present explanation in a fenced block, copy in a fenced block, attach PNG (read references/saving-and-delivery.md Deliver section). allowed-tools must include Bash, Read, Glob, Grep, Write, AskUserQuestion, Skill, ToolSearch, ExitPlanMode, SendUserFile .
Verify
File exists at kit/plugins/social-media-tools/skills/explain-codebase/SKILL.md . Frontmatter has name: explain-codebase , description ≤200 chars (three-part format), and allowed-tools listing all required tools. Body covers all nine phases including security scrub gate (Phase 4), copy drafting (Phase 5), template population logic (Phase 6), persistent save (Phase 6b), screenshot (Phase 7), and deliver (Phase 8).
2
done Add routing rule to social-share/SKILL.md classification table
Why
Without a rule, natural-language questions like "how does share-session work" fall through to Fallback A (share-code) or Fallback B (share-project) — both wrong. The new rule must fire before the fallbacks. Insert it as rule 8 in the first-match-wins table (before the current session rule and fallbacks), matching on tokens: explain , how does , how do , how it works , what is , what does , describe → target explain-codebase , no extra flags. Renumber subsequent rules accordingly.
Verify
Read kit/plugins/social-media-tools/skills/social-share/SKILL.md and confirm: (1) a new row exists in the classification table targeting explain-codebase with the listed trigger tokens; (2) it appears before Fallback A and B; (3) existing rules for share-session and share-code/share-project are unchanged.
3
done Bump version in .claude-plugin/marketplace.json from 2.5.2 → 2.6.0
Why
Adding a new skill is a MINOR change per the versioning conventions in .claude/rules/marketplace.md . The version lives only in marketplace.json — not in plugin.json — for relative-path plugins.
Verify
Run grep -A3 "social-media-tools" .claude-plugin/marketplace.json and confirm "version": "2.6.0" . Confirm kit/plugins/social-media-tools/.claude-plugin/plugin.json does NOT contain a version field.
4
done Add CHANGELOG entry at kit/plugins/social-media-tools/CHANGELOG.md
Why
All version bumps require a CHANGELOG entry. The entry must follow the existing format: a ## [2.6.0] header with today's date, an ### Added subsection listing the new skill, and a brief description of its purpose and trigger.
Verify
Run head -30 kit/plugins/social-media-tools/CHANGELOG.md and confirm a ## [2.6.0] - 2026-06-03 block appears at the top with an ### Added entry for explain-codebase .

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.

Invoke /social-media-tools:explain-codebase how does the share-session skill work and confirm: (1) locates and reads skills/share-session/SKILL.md plus referenced files; (2) returns structured explanation with Core Purpose, Workflow Phases (Phase 0–6), Key Patterns (ExitPlanMode bootstrap, session_usage.py, security scrub gate, reuse check), Important Files, and Invocation; (3) passes the security scrub gate without blocking; (4) produces platform-aware social copy; (5) populates feature-card.html with skill name, one-line purpose, and key phases as bullets; (6) saves a PNG to docs/media/social/ ; (7) delivers explanation + copy + image in the same response turn.

Then verify routing: send "how does share-scan work" via social-share and confirm dispatch to explain-codebase rather than share-code or share-project .

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.

Extend coverage to commands and reference files

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

Update kit/plugins/social-media-tools/skills/explain-codebase/SKILL.md so Phase 2 also handles command file targets (commands/*.md) and reference doc targets (references/*.md). When the question mentions a file name that matches a command or reference file instead of a skill name, read that file and format the response appropriately: commands get an Invocation + Arguments section; reference files get a Purpose + Key Rules section in place of Workflow Phases.
Add a dedicated explain-card.html template for richer layout

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

Create kit/plugins/social-media-tools/templates/explain-card.html — a dark-mode card template specifically for explain-codebase output. Layout: header row with skill name ({{TITLE}}) and type badge ({{BADGE}}); a "Core Principle" pull-quote ({{QUOTE}}); a compact phase table ({{PHASES}} — each row: phase number + one-line description); a footer bar with invocation syntax ({{INVOCATION}}) and repo slug ({{REPO}}). Reuse the same CSS colour tokens as feature-card.html and diff-card.html for visual consistency. Then update explain-codebase/SKILL.md Phase 6 to use this template instead of feature-card.html.
Onboarding guide generator — explain all skills in one pass 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 generate a full onboarding guide for the social-media-tools plugin. For each skill directory under kit/plugins/social-media-tools/skills/, invoke explain-codebase and collect the structured output. Merge all outputs into a single docs/ONBOARDING.md with a table of contents, one section per skill in alphabetical order. Each section should cover Core Purpose, Workflow Phases, and Invocation — omitting the raw file listings to keep the doc human-friendly.