mostafa-drz/code/publish-skills

Publish Skills

Publish personal Claude skills to a GitHub repository for sharing and versioning.

Preferences

Read ~/.claude/skills/publish-skills/preferences.md using the Read tool. If not found, no preferences are set.

Context

On startup, use the Glob tool to find ~/.claude/skills/*/SKILL.md to count skills, and read preferences (above) to extract repo-path and last-published.

Command routing

Check $ARGUMENTS:

• help → display help then stop
• config → interactive setup then stop
• reset → delete ~/.claude/skills/publish-skills/preferences.md, confirm, stop
• --preview → show what would be published, don't commit/push
• --diff → show diff between local skills and published repo
• --skip-audit → publish without running pre-publish audit checks
• anything else (including empty) → publish

Help

Publish Skills — Share Claude skills via GitHub

Usage:
  /publish-skills                    Publish all skills to GitHub repo
  /publish-skills --preview          Show what would change without publishing
  /publish-skills --diff             Show diff between local and published
  /publish-skills --skip-audit       Publish without pre-publish audit checks
  /publish-skills config             Set repo path and GitHub remote
  /publish-skills reset              Clear preferences
  /publish-skills help               This help

What it does:
  1. Copies skill files to the publish repo (excludes preferences, audit logs)
  2. Generates a README.md catalog from skill descriptions
  3. Commits changes with a summary message
  4. Pushes to GitHub

What gets published:
  - SKILLS_GUIDE.md (design guide)
  - Each skill's SKILL.md
  - Each skill's reference/ and examples/ directories
  - Auto-generated README.md catalog

What stays private:
  - preferences.md files (user-specific config)
  - last-audit.md (audit logs)
  - Any file matching .gitignore patterns

Current preferences:
  (shown above under Preferences)

Config

Use AskUserQuestion:

Q1 — "GitHub repo path?" (text input)

• Where the publish repo is cloned locally
• Example: ~/Dev/claude-skills

Q2 — "GitHub remote URL?" (text input)

• The remote URL for the repo
• Example: [email protected]:username/claude-skills.git

Q3 — "Commit style?" (Auto-summary (default) — list changed skills, Custom — ask each time)

Save to ~/.claude/skills/publish-skills/preferences.md.

First-time detection

If no preferences file exists:

1. Show: "First time using /publish-skills? Let me set up the publish repo."
2. Use AskUserQuestion:
   • Q1: "Where should the publish repo live?" — ~/Dev/claude-skills (Recommended), custom path
   • Q2: "GitHub repo URL?" — text input (e.g., [email protected]:username/claude-skills.git)
3. Initialize the repo if it doesn't exist (see Setup below)
4. Save preferences
5. Continue with publish

Setup (one-time)

If the repo path doesn't exist or isn't a git repo:

1. Create directory: mkdir -p {repo-path}
2. Initialize: cd {repo-path} && git init
3. Create .gitignore:

   preferences.md
   last-audit.md
   .DS_Store
   

4. Add remote: git remote add origin {remote-url}
5. Create initial commit with .gitignore
6. Do NOT push yet — the user needs to create the repo on GitHub first

If remote repo doesn't exist, inform: "Repo initialized locally. Create the repo on GitHub first, then run /publish-skills again to push."

Steps

1. Load config

Read preferences for repo-path and remote-url.

2. Discover and compare skills

Find all local skills:

~/.claude/skills/*/SKILL.md

For each skill, extract from frontmatter:

• name
• description
• argument-hint
• disable-model-invocation

Also note if the skill has reference/ or examples/ directories.

Compare with published repo to detect changes:

# For each local skill, diff against published version
# (this repo uses code/ as the skill directory, not skills/)
diff ~/.claude/skills/{skill-name}/SKILL.md {repo-path}/code/{skill-name}/SKILL.md

Categorize each skill:

• New — exists locally but not in the publish repo
• Changed — exists in both but files differ
• Unchanged — identical in both
• Removed — exists in repo but not locally

Also check if SKILLS_GUIDE.md changed.

2.5 Quick audit before publishing

Skip this step if --skip-audit flag is present.

For each skill being considered for publish (new or changed), run these quick checks inline:

• [ ] description present and third-person
• [ ] disable-model-invocation matches side-effect profile (has Write/Edit/Bash mutations = needs true)
• [ ] allowed-tools present
• [ ] No preferences.md files being included

If any skill fails checks, show warnings alongside the diff summary:

  ⚠️  /skill-name: missing disable-model-invocation (has side effects)
  ⚠️  /skill-name: description not third-person

Use AskUserQuestion: "{N} skills have audit warnings. Publish anyway? / Fix first / Skip those skills"

• Publish anyway — continue with all selected skills despite warnings
• Fix first — stop and let the user fix issues before retrying
• Skip those skills — remove skills with warnings from the publish set, continue with the rest

3. Present changes and confirm

Show a summary of what would be published:

Skills to publish:

  New:
    + /skill-name — short description
    + /skill-name — short description

  Changed:
    ~ /skill-name — short description
    ~ /skill-name — short description

  Unchanged:
    = /skill-name (skipped)
    = /skill-name (skipped)

  Removed from repo:
    - /skill-name (no longer exists locally)

  Also: SKILLS_GUIDE.md (changed/unchanged)

Use AskUserQuestion (multiSelect: true):

• One option per new/changed/removed skill (pre-selected label shows the action: add/update/remove)
• "Publish all changes" — select all new + changed + removed
• "Cancel" — stop without publishing

Only proceed with the skills the user explicitly selects. Never auto-publish.

4. Sync selected files

Only copy the skills the user approved:

For each approved skill:

# Create skill dir in repo (this repo uses code/, not skills/)
mkdir -p {repo-path}/code/{skill-name}

# Copy SKILL.md (always)
cp ~/.claude/skills/{skill-name}/SKILL.md {repo-path}/code/{skill-name}/

# Copy DESIGN.md if exists (renderer contract for UI-rendering skills —
# convention added by skill-creator manifest items 26-30, 2026-05-13)
if [ -f ~/.claude/skills/{skill-name}/DESIGN.md ]; then
  cp ~/.claude/skills/{skill-name}/DESIGN.md {repo-path}/code/{skill-name}/
fi

# Copy icon if exists (icon.svg or icon.png at the skill root)
for ext in svg png; do
  if [ -f ~/.claude/skills/{skill-name}/icon.$ext ]; then
    cp ~/.claude/skills/{skill-name}/icon.$ext {repo-path}/code/{skill-name}/
  fi
done

# Copy reference/ if exists
if [ -d ~/.claude/skills/{skill-name}/reference ]; then
  cp -r ~/.claude/skills/{skill-name}/reference {repo-path}/code/{skill-name}/
fi

# Copy examples/ if exists
if [ -d ~/.claude/skills/{skill-name}/examples ]; then
  cp -r ~/.claude/skills/{skill-name}/examples {repo-path}/code/{skill-name}/
fi

# Copy templates/ if exists (skill-creator manifest item 25)
if [ -d ~/.claude/skills/{skill-name}/templates ]; then
  cp -r ~/.claude/skills/{skill-name}/templates {repo-path}/code/{skill-name}/
fi

Never copy these (user-specific or runtime artefacts, must stay local):

• preferences.md · feedback-journal.md · anonymise.deny
• reports/ · sessions/ · resume-state.md · last-audit.md

These are also .gitignore'd in the publish repo as defense-in-depth.

For each approved removal:

rm -rf {repo-path}/code/{skill-name}

Copy SKILLS_GUIDE.md (if changed and user approved):

cp ~/.claude/skills/SKILLS_GUIDE.md {repo-path}/

5. Generate README.md

Build the catalog:

# Claude Skills

Personal collection of Claude Code skills for developer workflows.

## Quick Start

To use these skills, copy them to your `~/.claude/skills/` directory:

```bash
# Clone and copy all skills
git clone {remote-url}
cp -r claude-skills/skills/* ~/.claude/skills/

# Or copy a single skill
cp -r claude-skills/skills/whats-next ~/.claude/skills/

Skills Catalog

| Skill | Description | Side Effects | |-------|-------------|:------------:| | /address-pr-comments | {short description} | Yes | | /audit-skills | {short description} | No | | ... | ... | ... |

Skill Details

/skill-name

{full description from frontmatter}

Usage: /skill-name {argument-hint}

{link to SKILL.md}

---

Design Guide

These skills follow a consistent design guide with:

• CLI-style help, config, and reset subcommands
• Persistent preferences per skill
• First-time setup guidance
• Learning from user corrections

License

MIT

For the catalog table:
- Short description: first sentence of the frontmatter description (up to the first period)
- Side effects: "Yes" if `disable-model-invocation: true`, "No" otherwise

### 6. Commit and push

**If `--preview`:**
Steps 2-3 already showed the changes — stop here without modifying the repo.

**If `--diff`:**
Run `git -C {repo-path} diff` and show, then stop.

**Otherwise (after user confirmed in step 3):**

Stage only the approved files:
```bash
cd {repo-path}
git add skills/{approved-skill-1}/ skills/{approved-skill-2}/ README.md SKILLS_GUIDE.md
git status --short

Build commit message from what was approved:

Update skills: {list of approved skill names}

Added: {comma-separated list of new skills}
Updated: {comma-separated list of changed skills}
Removed: {comma-separated list of removed skills}

Show the staged diff summary and ask for final confirmation:

Use AskUserQuestion:

• "Commit and push?" (Yes — commit and push, Commit only — don't push, Cancel — discard staged changes)

Then execute based on choice:

git -C {repo-path} commit -m "{message}"
git -C {repo-path} push origin main   # only if user chose push

If push fails (no remote repo): "Committed locally but push failed. Make sure the GitHub repo exists and you have push access."

7. Update preferences timestamp

Update last-published in preferences file.

8. Report

Published {N} skills to {remote-url}

  Added:   {list}
  Updated: {list}
  Removed: {list}
  Skipped: {list of unchanged or user-excluded skills}

  Commit: {hash} "{message}"
  Repo:   {remote-url}

  README catalog updated with {N} skills.

If any skills had audit warnings during step 2.5, append:

Tip: run /audit-skills --fix to resolve all issues before publishing.

9. Learn

If user changes repo path, update preference. If user consistently excludes certain skills, note that pattern. If user consistently uses --preview first, note that pattern.

Principles

• Always confirm before publishing — show what changed, let the user pick which skills to include, confirm before commit/push. Never auto-publish.
• Never publish preferences — preferences.md is user-specific and stays local.
• Always generate README — the catalog is the main value of the GitHub repo.
• Non-destructive — copies files, never modifies the source ~/.claude/skills/ directory.
• Atomic publish — one commit per publish with a clear summary.
• Idempotent — running twice without changes produces no new commits.