skill-showcase

Files (11)

• README.md
• SKILL.md
• hero.png · assets/
• showcase-shell.html · assets/
• README.md · fixtures/edge-cases/
• SKILL.md · fixtures/edge-cases/
• README.md · fixtures/fence-preservation/
• SKILL.md · fixtures/fence-preservation/
• README.md · fixtures/pii-scrubbing/
• SKILL.md · fixtures/pii-scrubbing/
• build-showcase.js · scripts/

SKILL.md (first lines)

# Skill Showcase

Assemble a single self-contained HTML page that presents a collection of skill READMEs as a public-facing gallery. The output is static, offline-capable, and sanitized of personal identifying information — suitable for publishing, sharing as a portfolio, or embedding in documentation.

This skill **drafts human-facing READMEs in memory** for any skill that lacks one (see "Drafting READMEs" below) — the runtime skill folders are never modified. It does **not** generate hero images. Skills without an `assets/hero.png` still render cleanly, just without the hero panel; generate heroes separately with an image-gen skill if you want them.

## Workflow

1. **Identify the target skills directory** — usually one of:
   - A repo's `skills/` folder (default when invoked inside a toolkit-style repo)
   - `~/.claude/skills/` (global user skills)
   - `~/.claude/plugins/cache/*/skills/` (plugin skills)
   - Any directory the user specifies

2. **Enumerate skills** — for each subdirectory that contains a `SKILL.md`:
   - Read the `SKILL.md` frontmatter (name, description, version, source if present)
   - Read `README.md` if it exists
   - Check for `assets/hero.png` or `assets/hero.jpg`
   - Classify as **custom** or **plugin** based on path (see below)

3. **Draft READMEs for skills that lack one** — see "Drafting READMEs" below. A showcase built against a user's `~/.claude/skills/` often finds most skills have no public README (the SKILL.md is written for Claude, not humans). For each such skill, draft a README in memory, then pass the drafts to the build script via `--readme-overrides`. Skills that already have a README are left alone — the author's words win.

4. **Categorize** — group skills by the category hints in their READMEs or by user-provided grouping. Common categories: Design & UX, Testing & QA, Multi-agent thinking, Planning & documents, Reporting & setup, Meta / Infrastructure. If a skill doesn't fit, put it in "Uncategorized" and ask the user to confirm.

5. **Scrub PII** — scan README content and replace personal identifiers (see PII Scrubbing below).

6. **Assemble the HTML page** — use `assets/showcase-shell.html` as the structural template. The shell provides the sticky nav, table of contents, section layout, and styles. Inject rendered README content and hero images.

7. **Write output** — save to `~/.claude/showcase/skills-<YYYY-MM-DD>.html` by default. Never dump files into the user's current working directory. If the user is running this skill from an unrelated repo, we do not want to create `docs/showcase/` folders they didn't ask for. Only write to cwd when the user explicitly passes `--output <path>`.

8. **Open in browser** — run `open <path>` so the user can review.

## Custom vs plugin classification

Mark a skill as **plugin** if its path contains any of:

- `/plugins/cache/`
- `/plugins/installed/`
- `/.claude/plugins/`

Otherwise mark it as **custom** (user-authored or repo-local).

Show the distinction in the showcase: custom skills get a `● Custom` badge, plugin skills get a `◆ Plugin` badge with the plugin name if determinable (from the parent directory name in the plugins cache).

If a skill's `SKILL.md` frontmatter has an explicit `source:` or `origin:` field, honor that over the path-based classification.

## PII scrubbing

The showcase is intended for public sharing. Before rendering each README, apply these substitutions in memory (do NOT modify the original files):

| Pattern                                                                                     | Replacement                                                     |
| ------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `github.com/<username>/` (when username matches `git config user.name` or repo owner)       | `github.com/<your-username>/`                                   |
| `raw.githubusercontent.com/<username>/`                                                     | `raw.githubusercontent.com/<your-username>/`                    |
| `/Users/<username>/`                                                                        | `~/`                                                            |
| `/home/<username>/`                                                                         | `~/`                                                            |
| First name or full name of the current user (from `git config user.name` or `~/.gitconfig`) | Remove or replace with a neutral pronoun                        |
| Real email addresses                                                                        | `<your-email>`                                                  |
| Company/employer name (if obvious from repo or user context)                                | `<your-company>`                                                |
| Specific project names in sample content that look personal                                 | leave alone unless clearly identifying — ask the user if unsure |

Also inspect hero image filenames and paths. **Do not OCR-scrub hero images** — the skill cannot edit rasterized pixels. Instead, when a skill has a known-PII hero (detected by scanning the skill's sample HTML source if one exists), warn the user and suggest regenerating that specific hero before running the showcase.

Before writing the final HTML, do a sanity grep of the assembled output for the detected identifiers and warn if any slipped through.

## Drafting READMEs for skills that lack one

Most skills in `~/.claude/skills/` only have a `SKILL.md` — written for Claude, not humans. Rendered in the showcase raw, that content looks like technical instructions, not a description. To give third-party users a decent showcase without requiring them to author READMEs first, **draft a human-facing README from each skill's full SKILL.md in memory** before invoking the build script.

### When to draft

For each skill:

1. If `README.md` exists on disk → **use it as-is**, do not draft. The author's words always win.
2. If no `README.md` → draft one in memory from the full SKILL.md. Do **not** write it to the skill folder. The showcase should not modify the user's skills directory.

If the user passes `--no-draft-missing` (via a user-facing instruction like "don't generate READMEs, just show what's there"), skip drafting entirely and let those skills render with the "No public README yet" stub.

### What to use as input

Read the **entire** SKILL.md (frontmatter + body), not just the frontmatter. Frontmatter alone produces generic boilerplate. The SKILL.md body has the actual workflow, examples, rules, and tone that make for a useful README.

Also glance at the skill folder for grounding details:

- `scripts/` filenames — hint at what commands the skill runs
- `fixtures/` or `examples/` — source of example prompts
- Any sibling `*.md` files worth referencing

### Target style

Match the style of the existing well-authored READMEs in `~/Coding/claude-toolkit/skills/` (use one as a reference if accessible). The shape is:

```markdown
# <skill-id>

> One-sentence tagline — what the skill does and why it matters in one line.

## Use this when...

- Specific situation 1 where the skill applies (bold the keyword, explain the pain)
- Specific situation 2
- 3–5 bullets total; each names a concrete scenario

## What you say to Claude

\`\`\`
Example of a natural-language invocation that would trigger this skill.
Include a realistic constraint or input so the example feels grounded.
\`\`\`

Short paragraph explaining what happens next — which tools or sub-skills Claude runs, what output the user gets.

## What you get back

Description of the output artifact(s), with a specific, concrete example.
```

Optional sections if the SKILL.md supports them: **Install**, **Requirements**, **Limits**, **See also**.

From kabirdos/claude-toolkit, MIT.

More from kabirdos/claude-toolkit