Plans
Implementation Plan

Add explain-codebase skill to social-media-tools

completed
2026-06-03 agentics feature
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.html — Ship explain-codebase skill with full share-* pipeline output
File add-codebase-explain-skill.html
Path docs/plans/add-codebase-explain-skill.html
Acceptance criteria 0 / 4 done

Context

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

1
todo Create skills/explain-codebase/SKILL.md with the full workflow
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
todo Add routing rule to social-share/SKILL.md classification table
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
todo Bump version in .claude-plugin/marketplace.json from 2.5.2 → 2.6.0
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
todo Add CHANGELOG entry at kit/plugins/social-media-tools/CHANGELOG.md
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.

Acceptance Criteria

Verification

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.

Next Steps

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.
Wish List
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:

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.