publish-skill

What this skill does

# Publish Skill to Site

Automate the full pipeline for publishing a skill to the claude-skills-site Astro website.

## Paths

- **Skills repo:** `~/ai_projects/claude-skills/`
- **Site repo:** `~/ai_projects/claude-skills-site/`
- **Site skills:** `~/ai_projects/claude-skills-site/src/content/skills/*.mdx`
- **Site bundles:** `~/ai_projects/claude-skills-site/src/content/bundles/*.mdx`

## Invocation

```
/publish-skill <skill-name>              # New skill — generates a hero image by default
/publish-skill <skill-name> --update     # Regenerate existing .mdx (+ hero image)
/publish-skill <skill-name> --dry-run    # Show what would be written, no commits, no image
/publish-skill <skill-name> --no-image   # Skip hero-image generation
```

## Workflow

Execute these phases in order. Stop and report on any error.

### Phase 1 — Locate and Read Source

1. Check `~/ai_projects/claude-skills/<skill-name>/SKILL.md` exists. Also check `~/.claude/skills/<skill-name>/SKILL.md`.
2. If neither exists, report error: "SKILL.md not found for `<skill-name>`. Ensure the skill directory exists in the skills repo or ~/.claude/skills/."
3. If both exist, compare them. If `~/.claude/skills/` version is newer (by mtime), sync it to the skills repo with `rsync -av --exclude='*.egg-info' --exclude='__pycache__'`, commit the change, and push. This ensures the skills repo always has the latest version.
4. Read the SKILL.md (preferring the skills repo copy after any sync). Extract:
   - `name` from YAML frontmatter
   - `description` from YAML frontmatter
   - Body content (everything after the frontmatter closing `---`)
5. Also check if `~/ai_projects/claude-skills/<skill-name>/README.md` exists — if so, read it for supplementary context.

### Phase 2 — Check for Existing MDX

1. Check if `~/ai_projects/claude-skills-site/src/content/skills/<skill-name>.mdx` already exists.
2. If it exists and `--update` was NOT passed: stop and ask for confirmation. "The skill `<skill-name>` already has an .mdx on the site. Pass `--update` to regenerate, or confirm to overwrite."
3. If it exists and `--update` was passed: read the existing .mdx. Preserve these fields from the existing file (do not regenerate):
   - `apothecary_name`
   - `hero_image`
   - `auto_activity`
   - `auto_last_synced` (will be updated to today)

### Phase 3 — Generate MDX Frontmatter

Generate each field:

**`name`** — Use the skill directory name (kebab-case). Must match the filename.

**`tagline`** — One sentence, max 80 characters. Summarize what the skill does in plain language. End with a period. Do not start with "A skill that..." — lead with the action verb or the thing it produces.

**`apothecary_name`** — A poetic 2-4 word name in the style of an old apothecary shop. Follow the existing pattern:
- "The Listener's Ear" (meeting-intelligence)
- "The Scholar's Deep Draught" (deep-research)
- "The Artificer's Bench" (developer-tools)
- "The Therapist's Grimoire" (cognitive-toolkit)
- Use "The [Noun]'s [Noun]" or "[Noun] of [Noun]" patterns.

**`bundle`** — Select the best-fit bundle by analyzing the skill's purpose against these categories:

| Bundle key | Name | Covers |
|---|---|---|
| `meeting-intelligence` | Meeting Intelligence | Transcripts, meetings, recordings, action items, video/audio processing |
| `communication` | Communication | Email, messaging, Telegram, Google Workspace, Zoom |
| `research` | Research | Web research, search, image sourcing, knowledge retrieval |
| `content-publishing` | Content & Publishing | Image generation, presentations, PDFs, reports, brand assets, visual tools |
| `personal-analytics` | Personal Analytics | Health data, dictation analytics, browsing history, self-reflection, hardware signals, knowledge visualization |
| `thinking-strategy` | Thinking & Strategy | Decision frameworks, JTBD, dialogue modes, cognitive tools, self-design |
| `developer-tools` | Developer Tools | TDD, LLM CLI, issue tracking, session search, code tools |
| `lab-consulting` | Lab & Consulting | Lab meetings, client discovery, retrospectives, demos |

If the skill could fit multiple bundles, prefer the one where it adds the most differentiation. If genuinely unsure, ask the user.

**`tags`** — 3-6 lowercase kebab-case tags. Derive from the skill's domain, tools used, and output types. Check existing skills for tag reuse.

**`accent_color`** — Pick from the validated set: `amber` (default), `blue`, `cyan`, `green`, `orange`, `purple`, `violet`. Use `amber` unless the skill has a strong thematic reason for another color (e.g., hardware/signals → `cyan`, mental health → `violet`, nature/strategy → `green`).

**`auto_description`** — Copy the `description` field from the SKILL.md frontmatter verbatim. Truncate at 200 characters if longer.

**`auto_triggers`** — Extract 0-3 trigger phrases from the SKILL.md description (e.g., "queries like", "check my email"). Leave empty `[]` if no clear triggers.

**`auto_tools`** — Leave as `[]`.

**`auto_last_synced`** — Today's date in `YYYY-MM-DD` format. Run `date +"%Y-%m-%d"` to get it.

**`auto_last_commit`** — Run `git -C ~/ai_projects/claude-skills log -1 --format="%Y-%m-%d" -- <skill-name>/` to get the last commit date for that skill directory.

**`auto_activity`** — Leave as `[]` for new skills. Preserve from existing .mdx on `--update`.

**`install_command`** — Leave as `""`.

**`repo_path`** — The skill directory name (same as `name`).

**`dependencies`** — Extract from SKILL.md requirements/prerequisites sections. List Python packages, CLI tools, or APIs needed. Use `[]` if none.

**`hero_image`** — Leave commented out (`# hero_image:`) at this stage. Phase 6.5 generates a hero image **by default** and rewrites this field to the generated path. It stays commented only if `--no-image` was passed (or generation fails and no repo screenshot exists).

### Phase 4 — Generate MDX Body

Write the body following this exact structure:

```mdx
## What it does

[2-3 sentences describing the skill's primary function. Be specific about what it produces or enables. Reference concrete tools, APIs, or protocols if relevant.]

## Key features

[Bulleted list of 4-6 distinguishing features. Each bullet: **Bold label** — explanation. Focus on what makes this skill interesting, not obvious capabilities.]

## When to use

[1-2 sentences describing the trigger scenarios. Start with "When..." to match the existing pattern.]
```

Additional sections to include only when relevant:
- `## Signals` or `## Modes` — if the skill has named operational modes or signal types
- `## How it works` — if the skill uses a non-obvious protocol (MIDI, MCP, etc.)

Do NOT include: installation instructions, quick start commands, code blocks, or dependency lists. Those belong in the SKILL.md and README, not the site .mdx.

### Phase 5 — Validate

Before writing, verify:

1. **Bundle exists:** Confirm `~/ai_projects/claude-skills-site/src/content/bundles/<bundle>.mdx` exists.
2. **No duplicate:** If not `--update`, confirm no .mdx already exists (handled in Phase 2).
3. **Accent color valid:** Must be one of: `amber`, `blue`, `cyan`, `green`, `orange`, `purple`, `violet`.
4. **Name matches:** The `name` field, `repo_path`, and filename must all match.
5. **Tagline length:** Must be under 100 characters.

If any check fails, report the specific error and stop.

### Phase 6 — Write Files

1. **Write the .mdx file** to `~/ai_projects/claude-skills-site/src/content/skills/<skill-name>.mdx`.
2. **Update the bundle:** Read the target bundle .mdx. Add the skill name to the `skills:` array if not already present. Append at the end of the array.
3. If `--dry-run`: Instead of writing, display the full .mdx content and the bundle change, then stop.

### Phase 6.5 — Generate Hero Image (default; skip with `--no-image`)

This phase runs **by default**. Skip it only if `--no-image` was passed, or under `--dry-run` (which shows planned output without generating).

Generate a hero image using the `/codex`