feat(publisher): implement upskill/publisher — skill publication pipeline [v1]

[ngouy]

upskill/publisher — Implementation Brief

What This Is

publisher is the missing layer between "I created a skill" and "anyone in the world can install my skill." It takes a skill in any state — raw markdown, partially structured plugin, project-level skill, or complete plugin — and handles the full publication pipeline: scaffolding, git setup, GitHub repo creation, versioning, tagging, and docs.

Reference: VISION.md → Section "upskill/publisher"
Session structure: brainstorm → plan → implement → review (do not skip or combine)

---

The Core Problem It Solves

Getting a skill from a local markdown file to an installable Claude Code plugin requires:

• Creating plugin.json with the right format
• Structuring the directory correctly (skills/<name>/SKILL.md)
• Initializing a git repo
• Creating a GitHub repo
• Setting up the remote
• Writing a README
• Setting up RELEASE-NOTES.md
• Tagging releases with semver
• Creating GitHub releases via gh

This is 30+ minutes of boilerplate that virtually nobody does. Skills die on local machines because the path to sharing them is too long. publisher collapses this into a guided, conversational flow.

For project-level skills (.claude/skills/), the problem is different — the skill already lives in a repo, but has no versioning, no structure, and changes are just raw commits. Publisher handles this case too.

---

Key Positioning

publisher is the natural handoff from skill-creator. skill-creator (official Anthropic plugin) generates skills from scratch. The moment it finishes, publisher is the next thing a user should reach for.

publisher picks up where skill-creator leaves off — it never generates or modifies skill content, only the infrastructure around it.

---

The Pipeline State Machine

Publisher detects which stage the skill/plugin is at and guides the user to the next step. It can enter at any stage:

raw .md file
  → scaffolded    (has .claude-plugin/plugin.json + skills/ structure)
  → git-tracked   (has git history, initial commit)
  → github-hosted (has GitHub remote, pushed)
  → versioned     (has semver tags)
  → released      (has GitHub releases with release notes)

Default behavior (no specific task stated): run the interactive wizard — detect current state and guide to next step.

---

External Templates

Templates are external files, not embedded in the SKILL.md. Publisher's SKILL.md contains slim instructions that reference template files stored alongside it in the plugin repo. Claude reads the templates only when publisher is actually invoked — they cost zero tokens in sessions where publisher isn't used.

upskill/
└── skills/
    └── publisher/
        ├── SKILL.md                        ← slim instructions (loaded every session)
        └── templates/
            ├── plugin.json.template        ← read on demand
            ├── gitignore.template
            ├── readme.md.template
            └── release-notes.md.template

The SKILL.md instructs Claude to: read the relevant template, fill in user-provided values (name, description, author), and write the result.

---

Capability Set

1. Scaffold

Transform a raw skill file into a proper plugin structure.

Input: path to a .md file, or a skill name if it's in ~/.claude/skills/

Output structure:

my-plugin/
├── .claude-plugin/
│   └── plugin.json   ← generated from template with user input
├── skills/
│   └── my-skill/
│       └── SKILL.md  ← moved from original location, never overwritten
├── README.md         ← generated from template
└── RELEASE-NOTES.md  ← generated from template

Critical: prompt the user for name, description, author — never guess. Never overwrite existing SKILL.md content.

Skills are auto-discovered from skills/ — NO skills array in plugin.json.

2. Watermark (opt-in)

During scaffold, ask: "Add upskill attribution? [y/N]". If yes, store watermark.enabled: true in ~/.claude/upskill-state.json.

When enabled, add to SKILL.md frontmatter:

maintained-with: upskill (github.com/ngouy/upskill)

And to README.md footer:

---
*Managed with [upskill](https://github.com/ngouy/upskill)*

If not enabled, skip both. Never add watermark to skills the user doesn't own. Default is false.

3. Git Initialize

git init, initial commit, .gitignore with sensible defaults for Claude plugins.

4. GitHub: Create & Push

Using gh CLI (gh is a hard requirement):

• Create GitHub repo (ask about visibility upfront: public/private/org)
• Set up remote
• Push initial commit
• Never push without explicit user confirmation

5. Version Bump

Analyze git diff since last tag → suggest semver bump with reasoning → user can always override.

Bump logic:

• New capabilities, new skills added → minor
• Breaking changes to behavior or trigger conditions → major
• Typos, docs, clarifications only → patch

After bump: update plugin.json version field, commit.

6. Tag & Release

1. Create git tag (v1.2.0)
2. Prompt user to review/edit RELEASE-NOTES.md
3. Push tag to GitHub
4. Create GitHub release via gh release create

7. Docs Assistance

Actively help write README and RELEASE-NOTES — don't just create stubs and move on. Fill in what can be inferred from the skill content. Flag missing sections rather than silently omitting.

8. Project-Level Skill Management

For skills in <project>/.claude/skills/, publisher operates differently — these already live in a repo:

• Version tracking: Add lightweight semver metadata to the skill's frontmatter (no separate plugin.json needed)
• PR workflow: When a project skill is updated, create a PR on the project repo with the changes
• Watermark: If opted-in, add maintained-with to frontmatter

Project-level skills are a primary use case — teams share deploy helpers, review checklists, coding standards via their repos.

---

What publisher Must Never Do

• Never overwrite existing SKILL.md content — ever
• Never push to GitHub without explicit user confirmation
• Never create a public repo without confirming visibility preference
• Never skip README/release notes prompting
• Never add a skills array to plugin.json
• Never generate or modify skill content — that's skill-creator's and doctor's territory
• Never add watermark without asking (opt-in)

---

When to Use (trigger signals for SKILL.md description)

• User has just created a skill (especially right after skill-creator completes)
• User wants to put a skill on GitHub or make it installable by others
• User wants to release a new version of an existing plugin
• User wants to manage or version a project-level skill (.claude/skills/)
• User wants to add proper structure, docs, or semver to a raw skill file
• User asks how to share a skill with their team or the community
• User asks "how do I publish this?"

The skill-creator handoff is the primary trigger.

---

Quality Gate

Before this skill is considered done:

• Passes doctor --curator with zero CRITICAL or HIGH findings
• Wizard correctly detects all 5 pipeline stages and routes correctly
• plugin.json scaffold output exactly matches the correct format (no skills array, author as object)
• Templates are external files in skills/publisher/templates/, not embedded in SKILL.md
• Visibility (public/private/org) asked before any GitHub operation
• Never overwrites SKILL.md content — verified
• Watermark only added when user opts in
• Project-level skills handled (PR workflow)
• Token footprint target: ~400 tokens for SKILL.md only (verify with character count)

[ngouy]

Review update — design changes

Following a critical design review (#5), publisher remains in v1 scope as one of the two priority skills.

Changes to publisher's design (captured in VISION.md via #5):

• External templates pattern. Scaffold templates (plugin.json, .gitignore, README.md, RELEASE-NOTES.md) live as separate files in skills/publisher/templates/ — not embedded in the SKILL.md. Claude reads them on demand, so they cost zero tokens in sessions where publisher isn't used.
• Project-level skill management added. For skills in <project>/.claude/skills/, publisher creates PRs on the project repo instead of creating standalone plugin repos. Supports inline semver in frontmatter for project skills.
• Watermark is opt-in. Asked during publisher scaffold: "Add upskill attribution? [y/N]". Default is no. Never added silently.
• gh CLI is a hard requirement. No need to design around it being missing — if you're publishing to GitHub, you have gh.

Open questions resolved:

• Q1 (pipeline state detection): No changes, still check for plugin.json/git/remote/tags/releases
• Q2 (project .claude/skills/): Now first-class — publisher creates PRs for project skills
• Q4 (gh not installed): Hard requirement, just check and tell the user
• Q6 (watermark on update): Opt-in, only added if user chose it during scaffold