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.

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

---

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 ${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 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 when installed; skipped silently otherwise with an install hint)

False-positive guard: text scans use grep --binary-files=without-match so byte-stream collisions inside .pyc, .png, or .docx files do not trigger findings. __pycache__/ is also explicitly skipped.

Cross-validation

For categories the script flags, also manually verify with the Grep tool against ${CLAUDE_SKILL_DIR}/references/pii-patterns.md. Pay particular attention to:

• Names not in the EXTRA_PATTERNS argument (e.g., a co-author who appeared only in one early draft)
• Domain-specific institutional acronyms (your institution may not be in the default list)
• Project-specific identifiers like CK-NN, MA-NN, dated cohort names

Output Format

Present all findings in a remediation table:

| # | File:Line | Category | Match | Suggested Fix |
|---|-----------|----------|-------|---------------|

Gate: User reviews all findings. Fix each one. Re-run audit. Proceed only when 0 hits confirmed.

---

Phase 3: Generalization

Transform personal assumptions into universal defaults.

Language

• Replace: "in Korean" / "한국어로" / "Korean language" → "in the user's preferred language"
• Replace: "communicate in [specific language]" → "Communicate with the user in their preferred language"
• Keep: multilingual trigger keywords in the triggers: field (these aid discovery)

Role

• Replace: "radiology researcher" → "medical researcher" (if the skill is domain-general)
• Replace: "professor" / "fellow" → "researcher" or "user" (context-dependent)
• Keep: domain-specific terms that define the skill's scope (e.g., "diagnostic accuracy" is fine)

Paths

• Replace: hardcoded absolute paths → ${CLAUDE_SKILL_DIR} for bundled reference files
• Replace: ~/Documents/... → user-provided output directory
• Keep: relative paths within the skill directory structure

Environment

• Remove: assumptions about specific OS (macOS, Linux)
• Remove: assumptions about specific editors or IDEs
• Remove: references to personal infrastructure (agents, other personal skills)
• Keep: tool requirements listed in frontmatter tools: field

Interoperability

• Check: does the skill reference other skills by name (e.g., "route to analyze-stats")?
• If referenced skill exists in target package: keep the reference
• If referenced skill does NOT exist in target package: make it optional with fallback instructions

Output

Show a unified diff of all generalization changes for user review.

---

Phase 4: License Compatibility Check

Verify all bundled files are compatible with the target package license.

Scan Process

For each file in the skill's references/ and scripts/ directories:

1. Check for license headers or declarations within the file 2. Check for LICENSE files in the same directory 3. If the file contains content from a known standard (reporting guidelines, clinical scores, etc.), identify the source and its license

Compatibility Matrix

Reference ${CLAUDE_SKILL_DIR}/references/license-compatibility-matrix.md for the full matrix.

Quick reference for MIT target:

URL Manifest Pattern

For non-compatible content, convert from bundled file to a URL manifest:

## [Checklist Name]

This checklist is not bundled due to license restrictions ([License Type]).

**Official source**: [URL]
**How to use**: Download the checklist from the official source and place it in
`references/` before using this skill's reporting check feature.

Output

Present license audit table:

| File | Source | License | Compatible? | Action |
|------|--------|---------|------------|--------|

---

Phase 5: Validate and Test

Structural Validation

1. YAML frontmatter: Parse and verify all required fields (name, description, tools) 2. File references: Every ${CLAUDE_SKILL_DIR}/... path resolves to an actual file 3. Script executability: Scripts in scripts/ have appropriate shebangs 4. Line count: SKILL.md should be under 500 lines for optimal loading 5. Description quality: Description should start with a verb and include trigger keywords

Final PII Re-check

Run audit_skill.sh one final time. Must return exit code 0.

Cross-Platform Adapter Review

Check whether the skill can run in common desktop-agent environments:

If the package is intended for a workshop or classroom, prepare direct-download ZIPs rather than asking users to navigate GitHub manually:

https://github.com/{owner}/{repo}/releases/latest/download/{package}-classroom-windows.zip
https://github.com/{owner}/{repo}/releases/latest/download/{package}-classroom-macos.zip

README Entry Draft

Generate a table row matching the target package's README format:

| **{skill-name}** | {One-sentence description of what the skill does.} |

User Testing

Instruct the user to:

1. Copy the cleaned skill to a test location: cp -r <cleaned_skill> ~/.claude/skills/<skill-name> 2. Restart Claude Code 3. Test the skill triggers by typing /<skill-name> or relevant trigger phrases 4. Verify all phases work end-to-end on a sample input

Gate: User confirms testing is complete.

---

Phase 6: Package and Commit

Copy to Target Package

cp -r <cleaned_skill_path> <target_package>/skills/<skill-name>/

Update README

Apply the README entry drafted in Phase 5:

• Add row to the appropriate table (Available Now / Coming Soon)
• Update pipeline diagram if the skill adds a new stage
• Update skill count if mentioned in prose

Generate Commit Commands

Present the exact commands but do NOT auto-execute push:

cd <target_package>
git add skills/<skill-name>/
git add README.md
git diff --cached   # User reviews
git commit -m "Add <skill-name>: <one-line description>"

Gate: User reviews git diff --cached and explicitly approves the commit. Push is always manual.

Post-Publish

Remind the user to:

• Update any memory files tracking package status
• Add the skill to any marketplace listings if applicable
• Test installation from a clean clone: git clone <repo> && cp -r <repo>/skills/<skill-name> ~/.claude/skills/
• For classroom distribution, create or update GitHub Release ZIP assets and test direct download links.

Classroom Package Checklist (if applicable)

• [ ] Full skill set is installed once; lesson tasks use only 1-2 skills at a time
• [ ] Windows ZIP includes installers/install-windows.cmd
• [ ] macOS ZIP includes installers/install-macos.command
• [ ] README_FIRST.md explains unzip -> double-click -> restart -> test prompt
• [ ] Email announcement uses direct GitHub Release download links
• [ ] WSL is documented as an advanced option, not a default requirement
• [ ] First prompts avoid full end-to-end orchestration

---

What This Skill Does NOT Do

• Never auto-executes git push -- push is always manual
• Never modifies the source skill in place -- works on a copy or the target directory
• Never makes judgment calls on competitive sensitivity -- always asks the user
• Never bundles content with incompatible licenses -- converts to URL references
• Never assumes a specific package license -- asks in Phase 0
• Never skips the PII audit -- zero tolerance is enforced at Phase 2 and Phase 5

Anti-Hallucination

• Never fabricate file paths, URLs, DOIs, or package names. Verify existence before recommending.
• Never invent journal metadata, impact factors, or submission policies without verification at the journal's website.
• If a tool, package, or resource does not exist or you are unsure, say so explicitly rather than guessing.

License Compatibility Matrix

Reference for determining whether third-party content can be bundled in an open-source skill package. This matrix assumes the target package uses the MIT License as its primary license.

Compatible for Bundling

These licenses allow bundling inside an MIT-licensed package:

Attribution Template

When bundling CC BY content, add this header to the file:

<!-- 
  Source: [Title] by [Author(s)]
  License: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/)
  Original: [URL]
  Modifications: [describe any changes, or "None"]
-->

---

NOT Compatible for Bundling

These licenses conflict with MIT distribution. Convert to URL references.

---

URL Reference Pattern

When content cannot be bundled, replace the file with a reference document:

# [Resource Name]

> Not bundled due to license restrictions ([License Type]).

## Official Source

- **URL**: [direct link to official source]
- **Publisher**: [organization name]
- **License**: [license name and URL]

## How to Use

1. Download the resource from the official source above
2. Place it in this skill's `references/` directory as `[filename]`
3. The skill will automatically detect and use the local copy

## What This Skill Does Without It

When the resource is not locally available, the skill will:
- Use knowledge-based assessment instead of checklist-driven assessment
- Note in its output that the assessment was performed without the official checklist
- Recommend the user obtain the official resource for more thorough analysis

---

Optional External Dependency Pattern

For GPL-licensed tools that the skill can use but does not require:

## Optional: [Tool Name]

This skill can optionally use [Tool Name] for [specific feature].

- **License**: GPL v3
- **Install**: `pip install [package]` or `install.packages("[package]")`
- **Without it**: The skill will [describe fallback behavior]

---

Common Academic Content Licenses

Quick reference for frequently encountered academic content:

---

Decision Flowchart

Is the content original (written by you)?
  YES → Bundleable under MIT
  NO  → What is its license?
          CC0 / CC BY / MIT / BSD / Apache → Bundle with attribution
          CC BY-NC / CC BY-ND / CC BY-SA   → URL reference only
          GPL / LGPL                        → Optional external dependency
          Unknown / Proprietary             → Remove or contact author

PII Detection Patterns

Grep patterns for identifying personally identifiable information in Claude Code skills before open-source publication. All patterns are grep -riE compatible.

How to Use

1. Add your own identifiers to the User-Specific section below before running 2. Run audit_skill.sh <skill_directory> or use these patterns manually with Grep 3. Every match must be resolved before publishing -- zero tolerance

---

Universal Patterns

Hardcoded Paths

/Users/[a-zA-Z]|/home/[a-zA-Z]|~/Documents|~/Desktop|~/Downloads|~/Projects

Remediation: Replace with ${CLAUDE_SKILL_DIR} for bundled references, or use user-provided paths for output directories.

Email Addresses

[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}

Remediation: Remove entirely. If an email is needed for API registration, use a placeholder like <your-email>.

IP Addresses and Internal URLs

\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b|https?://[a-z]+\.(internal|local|corp)

Remediation: Remove or replace with <your-server>.

---

Domain-Specific Patterns (Medical/Academic)

Institutional References

SNUH|AMC|SMC|KAIST|SNU|ASAN|Mayo Clinic|Johns Hopkins|MGH|Charit

Remediation: Replace with "institution" or "medical center", or remove if not essential to the skill logic.

Academic Roles with Names

professor\s+[A-Z][a-z]+|Prof\.\s+[A-Z]|Dr\.\s+[A-Z][a-z]+|PGY[0-9]|R[0-9]-[0-9]

Remediation: Replace with "researcher", "user", or "collaborator".

Hospital-Specific Identifiers

IRB[- ]?\d|MRN[- ]?\d|patient[- ]?id|accession[- ]?number

Remediation: Use generic placeholders like <IRB-number>, <patient-id>.

---

Language and Locale

Hardcoded Language Preferences

in Korean|한국어로|Korean language|communicate in Korean|in Japanese|in Chinese|in English(?! for technical)

Remediation: Replace with "in the user's preferred language".

Note: Multilingual trigger keywords in the triggers: field are acceptable and encouraged for discoverability.

Location-Specific References

Seoul|Busan|Tokyo|Beijing|서울|부산|울산|창원

Remediation: Remove or generalize to region/country level only if essential.

---

User-Specific Patterns

IMPORTANT: Before each audit, add your personal identifiers below.

Names (add yours)

# Example -- replace with your actual names:
# firstname|lastname|이름|성명|romanized_variants

Institutional Affiliations (add yours)

# Example -- replace with your actual affiliations:
# university_name|hospital_name|lab_name|department

Collaborator Names (add yours)

# Example -- replace with collaborator names that may appear:
# collaborator1|collaborator2|advisor_name

---

False Positive Guidance

The following matches are typically safe to ignore:

When in doubt, flag the match for human review rather than auto-dismissing.