shawn-sandy/share-explanation

share-explanation

Answer "how does X work" questions about any file, component, function, or concept in the current project — by reading the actual source files and synthesizing a structured developer-friendly explanation. Then deliver the result the same way all other share-* skills do: security scrub → platform-aware copy → dark-mode card → persistent save.

Quick Reference

| Phase | Action | |-------|--------| | 0 — Locate | Locate templates/ and derive PLUGIN_DIR | | 0b — Config | Load SOCIAL.md for platform/tone defaults | | 1 — Parse | Extract target name/concept and flags from $ARGUMENTS | | 2 — Locate files | Map target to SKILL.md, reference docs, and scripts | | 3 — Synthesize | Read files and build structured explanation | | 4 — Scrub | security-scrub the full explanation (BLOCKED = hard stop) | | 5 — Draft | Write content-first, platform-aware social copy | | 5b — Reuse | Check docs/media/social/ for an existing post on this target | | 6 — Populate | Select template, substitute {{VARIABLES}} | | 6b — Save | Persistent save to docs/media/social/ | | 7 — Screenshot | Serve HTML locally, Playwright screenshot | | 8 — Deliver | Present explanation + copy + attach PNG + show saved path |

Exit plan mode

ExitPlanMode is a deferred tool whose schema must be loaded before it can be called. Use ToolSearch with select:ExitPlanMode first, then call ExitPlanMode. Both steps happen silently with no user-visible output.

Error handling: If ExitPlanMode returns "You are not in plan mode", treat that as success — continue immediately.

---

Phase 0 — Locate Plugin Assets

Run silently:

[ -n "${CLAUDE_PLUGIN_ROOT}" ] && [ -d "${CLAUDE_PLUGIN_ROOT}/templates" ] && \
  echo "${CLAUDE_PLUGIN_ROOT}/templates"
find ~/.claude/plugins -path "*/social-media-tools/templates" -type d 2>/dev/null | head -1
find ~/.claude -path "*/social-media-tools/templates" -type d 2>/dev/null | head -1

Use the first non-empty result as TEMPLATES_DIR. Derive:

PLUGIN_DIR=$(dirname "$TEMPLATES_DIR")

If no directory is found: output "Templates not found. Install the plugin or load it with --plugin-dir." and STOP.

---

Phase 0b — Load Project Sharing Config

SOCIAL_CONFIG=""
GIT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
if [ -f "$PWD/SOCIAL.md" ]; then
  SOCIAL_CONFIG="$PWD/SOCIAL.md"
elif [ -n "$GIT_ROOT" ] && [ -f "$GIT_ROOT/SOCIAL.md" ]; then
  SOCIAL_CONFIG="$GIT_ROOT/SOCIAL.md"
fi

If SOCIAL_CONFIG is non-empty, Read it silently. Extract:

• DEFAULT_PLATFORM from ## Defaults → Platform: line
• DEFAULT_TONE from ## Defaults → Tone: line

---

Phase 1 — Parse $ARGUMENTS

Extract:

• TARGET_RAW — all text that is not a --flag; the question or component name (e.g. "how does the share-session skill work", "security scrub pattern", "share-scan")
• PLATFORM — from --platform=<v>; keep empty if absent
• TONE — from --tone=<v>; keep empty if absent

If TARGET_RAW is empty after parsing, ask once via AskUserQuestion: "What component or concept would you like me to explain?" — stop if still empty.

---

Phase 2 — Identify Target and Locate Files

Establish project root — run silently:

GIT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
[ -z "$GIT_ROOT" ] && GIT_ROOT="$PWD"

GIT_ROOT is the search boundary for all lookups below. Never search outside it.

---

Match priority — try each tier in order; stop at the first hit:

Tier 1 — Skill (SKILL.md)

For each token in TARGET_RAW, check if it matches a skill directory name anywhere in $GIT_ROOT (case-insensitive):

find "$GIT_ROOT" -path "*/skills/*/SKILL.md" -not -path "*/archive/*" \
  -not -path "*/.git/*" -type f 2>/dev/null | \
  awk -F/ '{print $(NF-1)"|"$0}' | grep -i "^<token>|" | head -1

If matched:

• TARGET_TYPE=skill
• TARGET_NAME=<skill-dir-name>
• PRIMARY_FILE=<full-path>

Tier 2 — Command file

If no skill matched, check each token against command filenames in $GIT_ROOT:

find "$GIT_ROOT" -path "*/commands/*.md" -not -path "*/archive/*" \
  -not -path "*/.git/*" -type f 2>/dev/null | \
  awk -F/ '{name=$(NF); sub(/\.md$/,"",name); print name"|"$0}' | \
  grep -i "^<token>|" | head -1

If matched:

• TARGET_TYPE=command
• TARGET_NAME=<basename-without-.md>
• PRIMARY_FILE=<full-path>

Tier 3 — Any source file by name

If still no match, search for any file whose base name (without extension) matches a token in TARGET_RAW across all tracked files in $GIT_ROOT:

find "$GIT_ROOT" \
  -not -path "*/.git/*" -not -path "*/archive/*" -not -path "*/node_modules/*" \
  -not -path "*/__pycache__/*" -not -path "*/dist/*" -not -path "*/build/*" \
  -type f \( -name "*.md" -o -name "*.py" -o -name "*.js" -o -name "*.ts" \
             -o -name "*.mjs" -o -name "*.sh" -o -name "*.json" \) 2>/dev/null | \
  awk -F/ '{name=$(NF); sub(/\.[^.]+$/,"",name); print name"|"$0}' | \
  grep -i "^<token>|" | head -3

Set TARGET_TYPE=file. Collect all matches as SOURCE_FILES (up to 3).

Tier 4 — Function or symbol search

If still no match, grep the project for a function definition, class, or exported symbol whose name contains any token from TARGET_RAW:

grep -rn --include="*.py" --include="*.js" --include="*.ts" --include="*.mjs" \
  -E "(def |function |class |export (function|const|class) )<token>" \
  "$GIT_ROOT" 2>/dev/null | \
  grep -v "archive\|node_modules\|\.git\|dist\|build" | head -10

Set TARGET_TYPE=function. Collect unique file paths from results as SOURCE_FILES.

Tier 5 — Keyword/concept grep (last resort)

If nothing matched above, grep all text files in $GIT_ROOT for the key terms in TARGET_RAW:

grep -ril "<key-terms>" "$GIT_ROOT" \
  --include="*.md" --include="*.py" --include="*.js" --include="*.ts" \
  --include="*.mjs" --include="*.sh" 2>/dev/null | \
  grep -v "archive\|node_modules\|\.git\|dist\|build" | head -5

Set TARGET_TYPE=concept. Collect up to 5 paths as SOURCE_FILES.

---

Derive a TARGET_NAME slug from TARGET_RAW for use in filenames:

TARGET_NAME=$(echo "$TARGET_RAW" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | tr -s '-' | sed 's/^-\|-$//g' | cut -c1-30)

If nothing matched across all five tiers: output "Could not locate <TARGET_RAW> in the project. Try the exact file name, function name, or a key term from the code." and STOP.

---

Phase 3 — Read Files and Synthesize

Read PRIMARY_FILE (or each file in SOURCE_FILES for multi-file targets). For skill targets, also read any reference files explicitly named in the SKILL.md body — do not bulk-read any directory. For code targets (file, function, concept), read only the matched files; do not speculatively read adjacent files.

Adapt the synthesis structure to TARGET_TYPE:

For skill or command targets — six sections:

1. Core Purpose — 1–2 sentences: what this component does and why it exists
2. Activation Conditions (skills only) — what user intent or trigger fires it; the frontmatter description field is the source of truth
3. Workflow Phases — numbered list, one line per phase: phase name + what it does
4. Key Patterns — bullet list of non-obvious conventions used
5. Important Files — path/to/file — purpose for each file the component reads or writes
6. Invocation — exact syntax with a brief usage example

For file, function, or concept targets — five sections:

1. Core Purpose — what this code does and the problem it solves
2. How It Works — numbered steps describing the logic flow or algorithm
3. Key Patterns — non-obvious conventions, assumptions, or design choices
4. Dependencies / Callers — what calls this and what it depends on (from the source)
5. Usage Example — minimal concrete call or invocation

Write concretely — real file names, real function signatures, real variable names. No filler.

SUMMARY_RAW = full EXPLANATION_RAW text (passed to security scrub in Phase 4).

---

Phase 4 — Security Scrub

Write EXPLANATION_RAW to a temp file:

mkdir -p ~/.claude/tmp

Write content to ~/.claude/tmp/scrub-input.txt.

Invoke:

Skill(skill: "social-media-tools:security-scrub", args: "Scan the file at ~/.claude/tmp/scrub-input.txt for secrets before sharing.")

Check the returned GATE RESULT line:

• GATE RESULT: BLOCKED or GATE RESULT: CANCELLED → STOP. Do not proceed to Phase 5.
• GATE RESULT: APPROVED → proceed to Phase 5.
• Missing or unrecognized result → STOP and report error (treat as gate failure).

---

Phase 5 — Draft Copy

Read $PLUGIN_DIR/references/platforms.md for character limits, tone defaults, Follow CTA rule, and Default Per-Platform Copy Formats.

Resolve PLATFORM and TONE concretely before prompting:

# PLATFORM and TONE were parsed from $ARGUMENTS in Phase 1
[ -z "$PLATFORM" ] && [ -n "$DEFAULT_PLATFORM" ] && PLATFORM="$DEFAULT_PLATFORM"
[ -z "$TONE" ]     && [ -n "$DEFAULT_TONE" ]     && TONE="$DEFAULT_TONE"

Only if either variable is still empty after applying the above, ask for both in a single AskUserQuestion.

Lead with insight, not process. The hook should surface the most interesting or surprising aspect of how the component works — not just "here's how X works."

Content guidance per platform:

• LinkedIn: hook on the key insight → 2–3 most important patterns → one-line invocation example → follow CTA
• Twitter/X: one sharp principle in ≤280 chars; invocation if space allows
• Bluesky: conversational, principle-first, same brevity as Twitter/X
• Substack: reflect on what the design reveals about the plugin's philosophy; patterns as supporting detail

---

Phase 5b — Reuse Check

Now that TARGET_NAME and PLATFORM are both resolved, check for an existing post:

FILE_PREFIX=explain

Read $PLUGIN_DIR/references/reuse-check.md and follow its procedure.

---

Phase 6 — Populate Template

Select template based on target type:

• TARGET_TYPE=skill or TARGET_TYPE=command → use feature-card.html
• TARGET_TYPE=file or TARGET_TYPE=function → use feature-card.html
• TARGET_TYPE=concept → use quote-card.html

TEMPLATE_FILE=$TEMPLATES_DIR/<selected-template>
TEMP_HTML=explain-share-card.html
TODAY=$(date '+%Y-%m-%d')
# Normalize TARGET_NAME (or TARGET_RAW for concept targets) through the same slug pipeline
TARGET_SLUG="$(printf '%s' "${TARGET_NAME:-$TARGET_RAW}" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-' | sed 's/^-*//;s/-*$//' | cut -c1-30)"
SLUG_INPUT="explain-${TARGET_SLUG}-${TODAY}"

Read $PLUGIN_DIR/references/variables.md for the variable reference. Read $PLUGIN_DIR/references/copy-panels.md for {{COPY_PANELS}} markup and escaping.

HTML-escape all values — MANDATORY

Apply in this exact order:

1. & → & ← first, to prevent double-escaping
2. < → <
3. > → >
4. " → "

feature-card.html substitutions

| Template variable | Value | |-------------------|-------| | {{TITLE}} | TARGET_NAME (HTML-escaped; e.g. share-session) | | {{SUBTITLE}} | Core Purpose sentence, ≤100 chars (HTML-escaped) | | {{BULLETS}} | One <li>…</li> per Workflow Phase — HTML-escape each phase's text, wrap in <li>. No wrapping <ul>. | | {{BADGE}} | TARGET_TYPE (HTML-escaped; skill or command) | | {{FOOTER_NOTE}} | Invocation syntax (HTML-escaped; e.g. /social-media-tools:share-session [--platform=]) | | {{COPY_PANELS}} | Copy panel HTML — see references/copy-panels.md |

quote-card.html substitutions

| Template variable | Value | |-------------------|-------| | {{QUOTE}} | Most important Key Pattern principle, ≤200 chars (HTML-escaped) | | {{ATTRIBUTION}} | Plugin or project name (HTML-escaped; e.g. social-media-tools) | | {{CONTEXT}} | Pattern category (HTML-escaped; e.g. Security pattern, Bootstrap pattern) | | {{COPY_PANELS}} | Copy panel HTML — see references/copy-panels.md |

Write the populated HTML to ~/.claude/tmp/explain-share-card.html.

---

Phase 6b — Persistent Save

Variables: FILE_PREFIX=explain, SLUG_INPUT, TEMP_HTML=explain-share-card.html.

Read $PLUGIN_DIR/references/saving-and-delivery.md — Persistent Save section.

---

Phase 7 — Screenshot

Read $PLUGIN_DIR/references/rendering-pipeline.md and follow the full pipeline.

---

Phase 8 — Deliver

Present the structured explanation in a fenced markdown block labeled ## Explanation.

Present the social copy in a separate fenced block labeled ## Copy.

Read $PLUGIN_DIR/references/saving-and-delivery.md — Deliver section for attaching the PNG and reporting the saved path.