/publish-skill

name: publish-skill
description: Use when turning a personal agent skill into an open-source, distributable one. Runs a PII audit, generalizes personal details, checks licence compatibility, reviews cross-platform adapters and walks through packaging.
metadata:
  triggers: "publish skill, distribute skill, open-source skill, package skill, universalize skill"

Skill: publish-skill

Phase 0: Init and Identify Source

Required Inputs

Collect from the user:

1. **Source skill path**: directory containing the personal skill (e.g., `~/.claude/skills/my-skill/` or `~/.agents/skills/my-skill/`) 2. **Target package path**: directory of the distributable package (e.g., `~/workspace/<your-package>/`) 3. **Target license**: license of the package — ask; offer MIT as the default, never assume it

Actions

1. Read `SKILL.md` from the source skill directory 2. Inventory all files recursively (`ls -R`) 3. Classify skill type:

• **Standalone**: self-contained skill with no agent delegation
• **Orchestrator**: delegates to sub-agents (NOT suitable for distribution without refactoring)
• **Wrapper**: thin wrapper around another tool/API

4. Present inventory table to the user:

| File | Lines | Type | Notes |
|------|-------|------|-------|

Make every later fix on a working copy (`<cleaned_skill_path>` below) or in the target directory. NEVER modify the source skill in place, because it is the user's working original.

**Gate**: User confirms source skill and target package before proceeding.

---

Phase 0.5: Skill-Worthiness Gate

Before spending effort on PII scrubbing and generalization, confirm the workflow is worth distributing *as a skill* at all. Apply all three gates:

| Gate | Question | Pass condition | |------|----------|----------------| | **Uniqueness** | Could a competent user get the same result by searching the web for ~5 minutes, or by asking a general assistant with no skill installed? | **No** | | **Specificity** | Does it encode a workflow, decision heuristic, constraint, or convention specific to this domain or a recurring task — rather than a generic code snippet or a standard-library example? | **Yes** | | **Effort** | Did discovering it take real debugging, study design, operational effort, or a reviewer-anticipation lesson (a pitfall, a verification step, a domain convention)? | **Yes** |

**Gate**: Any "no" (or "yes" on the inverse) stops publication — recommend documentation or a memory note instead. If the value is real but the skill delegates to private agents, route through Phase 1's orchestrator finding (refactor to standalone first). Only a clear three-way pass proceeds.

---

Phase 1: Originality Check

Checks

1. **External source**: Is this skill adapted from another package or author? Check for attribution headers, license blocks, or "based on" comments. 2. **Third-party content**: Do any files in `references/` come from external sources (published guidelines, textbooks, standards bodies)? 3. **Competitive sensitivity**: Does the skill reveal proprietary business logic or competitive advantage that should remain private? Ask the user; never make this judgment call yourself.

Decision Matrix

| Finding | Action | |---------|--------| | Fully original | Proceed to Phase 2 | | Adapted with compatible license | Add attribution header, proceed | | Contains non-compatible third-party content | Flag for removal or URL reference conversion | | Orchestrator with private agent references | STOP -- requires refactoring to standalone first | | Competitive/proprietary logic | STOP -- not suitable for open-source |

---

Phase 2: PII De-identification Audit

**Zero tolerance**: the skill must have exactly 0 PII matches before proceeding.

Pre-scan Setup

Before running, ask the user for everything unique to them that should also count as a PII hit:

• Their name(s) in all languages and romanizations (a placeholder shape: `<First Last>|<native-script name>`)
• Their institutional affiliation(s) (a placeholder shape: `<Institution>|<Hospital>`)
• Any collaborator surnames that may appear in drafts or filenames

Combine the inputs into a single `grep -E` alternation pattern (pipe-separated).

Automated Scan

Run the bundled audit script. The first argument is the skill directory; the second is the user-specific alternation pattern from Pre-scan Setup.

bash ${CLAUDE_SKILL_DIR}/scripts/audit_skill.sh --strict <source_skill_path> \
    "<First Last>|<native-script name>|<Institution>|<Hospital>"

The script scans ten categories, plus the user pattern:

1. **Hardcoded paths** (`/Users/<name>/`, `/home/<name>/`, `~/Documents`, `~/Desktop`, `~/Downloads`, `~/Projects`) 2. **Email addresses** (any address-shaped string) 3. **IP addresses / internal URLs** (`*.internal`, `*.local`, `*.corp`) 4. **Institutional references** (SNUH / AMC / SMC / KAIST / SNU / ASAN / MGH / UCSF / Mayo Clinic / Johns Hopkins / Samsung Medical / Severance / Asan Medical) 5. **Academic roles with names** (`professor <Surname>`, `Prof. <Surname>`, `Dr. <Surname>`, `PGY[0-9]`, `<한글이름> 교수님`) 6. **Language hardcoding** ("in Korean", "한국어로", "in Japanese", "in Chinese") 7. **Location specifics** (Seoul / Busan / Daegu / Tokyo / Beijing / Shanghai / Boston / Stanford and Korean variants) 8. **Blockquote dated precedent** (`> YYYY-MM-DD ...` lines that reveal an internal review timeline) 9. **Author-style filenames** (`<Surname>{Year}_*` pattern, e.g., `<Surname>2025_<Journal>_Fig01.png`; allow-list excludes generic tokens like `Issue2024_`, `Sample2025_`) 10. **Binary EXIF metadata** (DOCX / PPTX / XLSX / PDF / PNG / JPG / TIFF — scanned via `exiftool` for home paths, email addresses and the user pattern, matched case-insensitively. If binaries are present and `exiftool` is not installed, the RESULT line reads INCOMPLETE and `--strict` exits 3)

Exit codes: 0 clean, 1 findings, 2 usage error / invalid user regex / a scan that could not run, 3 (`--st