publish-skill

# Skill: publish-skill

Convert a personal agent skill into a clean, distributable, open-source-ready skill package. This skill walks through a 7-phase pipeline that audits for personally identifiable information, generalizes language and role assumptions, verifies license compatibility, checks cross-platform adapter needs, and prepares the final package for commit.

## Communication Rules

- Communicate with the user in their preferred language
- Use English for technical terms (PII, MIT, CC BY, GPL, YAML frontmatter)
- Present audit findings in structured tables

---

## 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 (default: MIT)

### 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 |
|------|-------|------|-------|
```

**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. A skill earns its place by encoding a reusable
decision heuristic, a hard-won constraint, or a verification step — not a snippet anyone
could reconstruct in five minutes. Apply all three gates; **any "no" (or "yes" on the
inverse) stops publication** in favor of documentation or a memory note instead.

| 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** |

Favor skills that encode reviewer-anticipation, reporting-guideline constraints,
verification gates, and decision trees over thin wrappers or one-off snippets. This is
the publish-time analogue of the "reusable pattern vs one-off hack" distinction: a
workflow that fails the gate is better captured as a doc or a memory note than shipped as
a skill that dilutes the catalog.

**Gate**: If any of the three fails, recommend documentation/memory instead and stop. 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

Verify the skill is original work suitable for open-source distribution.

### 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?

### 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 manifest 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 that should also count as a PII hit but is unique to them:
- 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
bash ${CLAUDE_SKILL_DIR}/scripts/audit_skill.sh <source_skill_path> \
    "<First Last>|<native-script name>|<Institution>|<Hospital>"
```

The script runs nine categories that mirror the medsci-skills monorepo linter (`scripts/validate_skills.sh`):

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 / 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