Skill Publish

Language

Match user's language: Respond in the same language the user uses.

Overview

Package a agent skill into a complete, distributable GitHub repository. Generates all the surrounding files (README, LICENSE, plugin.json, marketplace.json) and optionally creates the GitHub repo.

How It Works

• Identify the skill to publish

• Optionally review first with skill-review

• Collect publishing metadata through dialogue

• Generate the repository structure with publish.py

• Optionally initialize git and create GitHub repo

Dialogue Flow

Progress:

• Step 1: Identify the skill

• Step 2: Pre-publish validation

• Step 3: Collect metadata

• Step 4: Generate repository

• Step 5: Post-generation

Step 1: Identify the Skill

Accept the skill location in multiple forms:

Input Detection Action

Directory with SKILL.md Direct path Use as-is

SKILL.md file path Path ends in SKILL.md

Use parent directory

Current directory No input, cwd has SKILL.md Auto-detect

Step 2: Pre-Publish Validation

Check for skill-review availability:

• First try: {SKILL_DIR}/../skill-review/scripts/validate.py

• Fallback: ~/.agents/skills/skill-review/scripts/validate.py

If found, suggest running validation:

python3 <validate.py path> run --path <skill-path>

If there are failures, recommend fixing them before proceeding. Warnings are acceptable.

If skill-review is not available, offer:

• A) Install it: npx skills add psylch/better-skills@skill-review -g -y

• B) Continue without it (quick manual check: verify SKILL.md exists with valid frontmatter)

• C) Cancel

Step 3: Collect Metadata

Use AskUserQuestion to gather:

GitHub owner/org — Default: try to infer from git config user.name or gh api user -q .login . Ask user to confirm or change.

Repository name — Default: <skill-name>-skill (e.g., cors-audit-skill ). Suggest the convention but let user override.

Version — Default: 1.0.0 . Use semver.

License — Default: MIT. Options: MIT, Apache-2.0, GPL-3.0.

Output directory — Where to create the repo. Default: parent directory of the skill.

Step 4: Generate Repository

python3 {SKILL_DIR}/scripts/publish.py generate
--skill-path <path>
--owner <owner>
--repo <repo-name>
--version <version>
[--license mit|apache2|gpl3]
[--output <dir>]
[--force]

Where {SKILL_DIR} is the directory containing this SKILL.md file.

The script outputs JSON to stdout:

{ "status": "ok", "output_dir": "/path/to/output", "repo": "owner/repo-name", "created": [".claude-plugin/plugin.json", "README.md", "LICENSE", ...], "hint": "Repository files generated. Next: git init or gh repo create." }

Step 5: Post-Generation

Present a completion report:

[Skill Publish] Complete!

Skill: <skill-name> Repository: <owner>/<repo> License: <license> Output: <directory>

Files created: • <list from JSON "created" field>

Next Steps: → A) Initialize git repo → B) Create GitHub repo and push → C) Done — handle git manually

Then let the user choose:

Option A: Initialize git repo

cd <output-dir> git init git add . git commit -m "Initial commit"

Option B: Create GitHub repo and push

cd <output-dir> git init git add . git commit -m "Initial commit" gh repo create <owner>/<repo> --public --source . --push

Option C: Done — User will handle git themselves.

After creation, remind the user:

• Edit README.md and README.zh.md to polish auto-generated content

• Register on skills.sh if they want public discoverability

• Test installation: npx skills add ./ -g -y

Generated Repository Structure

<repo-name>/ ├── .claude-plugin/ │ ├── plugin.json │ └── marketplace.json ├── skills/ │ └── <skill-name>/ # Copied from source │ ├── SKILL.md │ ├── scripts/ │ └── references/ ├── README.md ├── README.zh.md ├── LICENSE └── .gitignore

Distribution Guide Reference

For details about skills.sh registry, versioning strategy, and publishing conventions, read references/distribution_guide.md .