From 5f3187b1e8849ef814a0f60fd99f2bee621359d5 Mon Sep 17 00:00:00 2001 From: ngouy Date: Sun, 8 Mar 2026 22:35:03 -0400 Subject: [PATCH 1/3] docs: update installation with marketplace flow and 24h availability note Co-Authored-By: Claude Sonnet 4.6 --- README.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 438b838..6564612 100644 --- a/README.md +++ b/README.md @@ -32,16 +32,20 @@ ## Installation -Claude Code uses a marketplace registry model. Register the upskill marketplace, then install: +### Via marketplace (recommended) + +Register the upskill marketplace, then install: ``` /plugin marketplace add ngouy/upskill-marketplace /plugin install upskill@upskill-marketplace ``` -All sub-skills become available immediately in the current session and every future session. +> **Note:** After registering a new marketplace, Claude Code may take up to 24 hours to make it available. If the install fails immediately after adding the marketplace, wait and try again. + +All sub-skills become available in the current session and every future session. -### Manual install (without marketplace) +### Manual install Clone directly into the plugins directory and restart Claude Code: @@ -49,8 +53,6 @@ Clone directly into the plugins directory and restart Claude Code: git clone https://github.com/ngouy/upskill ~/.claude/plugins/ngouy/upskill ``` -> **Note:** The marketplace registry (`ngouy/upskill-marketplace`) must be created and upskill registered in it before the `/plugin install` path works. Until then, use the manual install above. - --- ## Quick Start From af3fd8e41c488d4a35c5992515e4abea88b8b41b Mon Sep 17 00:00:00 2001 From: ngouy Date: Sun, 8 Mar 2026 22:37:51 -0400 Subject: [PATCH 2/3] docs: mark unbuilt sections as under construction - Quick Start trimmed to publisher-only examples - Sub-skills table adds Status column - manager and auditor sections replaced with coming-soon stubs - doctor section marked in-progress with link to issue Co-Authored-By: Claude Sonnet 4.6 --- README.md | 118 +++++++----------------------------------------------- 1 file changed, 15 insertions(+), 103 deletions(-) diff --git a/README.md b/README.md index 6564612..2f376c5 100644 --- a/README.md +++ b/README.md @@ -58,31 +58,28 @@ git clone https://github.com/ngouy/upskill ~/.claude/plugins/ngouy/upskill ## Quick Start ``` -# See everything installed -"Show me all my installed skills" - # Publish a skill you just created "I just made a new skill, help me put it on GitHub" -# Check a skill for problems -"Run doctor on my-custom-workflow" +# Bump the version of an existing plugin +"publisher: bump version" -# Audit your current session -"Audit my loaded skills" +# Release a new version +"publisher: release" ``` -Claude activates the appropriate sub-skill automatically based on context, or you can invoke them explicitly by name. +Claude activates publisher automatically when the context matches, or you can invoke it explicitly by name. --- ## Sub-Skills Overview -| Sub-skill | One-line description | -|---|---| -| `manager` | Unified inventory of all installed skills (plugins + local), bulk updates, update notifications | -| `publisher` | Scaffold, version, and ship any skill to GitHub as an installable plugin | -| `doctor` | Analyze individual skill files for quality, structure, and safety — Curator and Guardian modes | -| `auditor` | Cross-skill session analysis: conflicts, overlaps, token budget, and session health | +| Sub-skill | Status | One-line description | +|---|---|---| +| `publisher` | ✅ v1 | Scaffold, version, and ship any skill to GitHub as an installable plugin | +| `doctor` | 🚧 coming in v1 | Analyze individual skill files for quality, structure, and safety — Curator and Guardian modes | +| `manager` | 🔜 v1.1 | Unified inventory of all installed skills (plugins + local), bulk updates, update notifications | +| `auditor` | 🔜 v1.1 | Cross-skill session analysis: conflicts, overlaps, token budget, and session health | --- @@ -90,43 +87,7 @@ Claude activates the appropriate sub-skill automatically based on context, or yo ### manager — Unified Inventory -`manager` is your single pane of glass for everything installed. It unifies plugin-installed skills (managed by Claude Code) and local custom skills (raw markdown files in `~/.claude/skills/`) into one view. From the user's perspective, there is one inventory — not two. - -#### List All Installed Skills - -Ask: *"What skills do I have installed?"* or *"Show me my skill inventory."* - -``` -┌─────────────────────────────────────────────────────────────────────┐ -│ INSTALLED SKILLS 2 plugins │ -├──────────────────────┬────────────┬────────────┬───────────────────┤ -│ Skill │ Source │ Version │ Last Updated │ -├──────────────────────┼────────────┼────────────┼───────────────────┤ -│ manager │ plugin │ 1.2.0 │ 3 days ago │ -│ publisher │ plugin │ 1.2.0 │ 3 days ago │ -│ doctor │ plugin │ 1.2.0 │ 3 days ago │ -│ auditor │ plugin │ 1.2.0 │ 3 days ago │ -│ my-custom-workflow │ local │ (untracked)│ 12 days ago │ -│ commit │ plugin │ 2.0.1 │ 1 week ago │ -└──────────────────────┴────────────┴────────────┴───────────────────┘ - -[!] 1 update available: commit (2.0.1 → 2.1.0) -``` - -Local skills without git history show version as `(untracked)`. Skills in a git repo show the short SHA. - -#### Bulk Updates - -``` -# Update all plugins in one pass -"Update all my skills" -``` - -Manager runs updates across all installed plugins and shows a consolidated summary of what changed, including RELEASE-NOTES.md diffs where available. Individual install/remove operations use Claude Code's built-in `/plugin install` and `/plugin remove` directly. - -#### Update Notifications - -Manager can help set up a Claude Code hook that checks for updates at session start. This is optional and user-initiated — ask *"Set up update notifications"* to get started. +> 🔜 **Coming in v1.1.** See [issue #1](https://github.com/ngouy/upskill/issues/1) for the design. --- @@ -200,19 +161,12 @@ raw .md file ### doctor — Quality and Safety Analysis -`doctor` analyzes skill files for quality, structure, safety, and behavioral correctness. It operates in two modes: **Curator** for skills you own, and **Guardian** for third-party skills you're evaluating. - -The name is intentional: a doctor diagnoses, treats, prescribes, and discharges. doctor does the same for skills — it finds what's wrong, recommends a fix, applies it with your approval, and clears the skill. *The doctor will see your skill now.* +> 🚧 **In progress — coming in v1.** See [issue #3](https://github.com/ngouy/upskill/issues/3) for the design. -Doctor never modifies skill files without explicit approval for each change. It recommends — it does not act unilaterally. +Doctor will analyze skill files for quality, structure, safety, and behavioral correctness in two modes: **Curator** (your own skills) and **Guardian** (third-party skills). Doctor never modifies skill files without explicit approval. #### Curator Mode — Improve Your Own Skills -``` -"Run doctor on my-custom-workflow" -"Check the quality of my commit skill" -``` - Curator analyzes for: - Clear purpose statement and scope - Trigger conditions (when should this skill fire?) and exit signals (when is it done?) @@ -287,49 +241,7 @@ Severity levels: `CRITICAL` / `HIGH` / `MEDIUM` / `LOW` for Curator mode. `RED F ### auditor — Cross-Skill Session Analysis -`auditor` analyzes how your loaded skills interact with each other and affect your session. It answers: *"How are my skills working together right now?"* - -Auditor focuses on **cross-skill** analysis — conflicts, overlaps, and token budget distribution. It does not duplicate doctor's per-skill quality checks. It does not read your conversation, codebase, or project files. - -#### Run an Audit - -``` -"Audit my session" -"What are my loaded skills costing me in tokens?" -"Are any of my skills conflicting with each other?" -``` - -#### Report Structure - -**1. Token Inventory** — all loaded skills with estimated token cost: - -``` -LOADED SKILLS -───────────────────────────────────────────────────────────────────── -Skill Source Tokens (est.) % of total -───────────────────────────────────────────────────────────────────── -manager plugin ~180 8% -doctor plugin ~520 23% -my-custom-workflow local ~840 37% -... -───────────────────────────────────────────────────────────────────── -TOTAL ~2,240 -``` - -**2. Cross-Skill Analysis** — conflicts between skills, overlapping triggers, CLAUDE.md contradictions: - -``` -[CONFLICT] my-custom-workflow ↔ CLAUDE.md - CLAUDE.md says "always use TypeScript". - my-custom-workflow says "use JavaScript for scripts". - -[OVERLAP] my-custom-workflow ↔ commit - Both trigger on "when I am working on code changes". -``` - -**3. Session Health Summary** — overall rating with prioritized actions. - -Overall ratings: `HEALTHY` / `NEEDS ATTENTION` / `CRITICAL`. +> 🔜 **Coming in v1.1.** See [issue #4](https://github.com/ngouy/upskill/issues/4) for the design. --- From 18eeb2e3afb1023bada6155d177c4f0521ba1ccd Mon Sep 17 00:00:00 2001 From: ngouy Date: Mon, 9 Mar 2026 08:02:31 -0400 Subject: [PATCH 3/3] refactor(publisher): split into skill-publisher-wizard/release/marketplace MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rename skills/publisher/SKILL.md → skills/skill-publisher-wizard/SKILL.md - Update frontmatter name and description (triggers: 'publisher wizard', 'new skill wizard') - Strip version bump, release, and project-level sections (→ skill-publisher-release) - Strip marketplace step (→ skill-publisher-marketplace) - Add handoff references to the two sibling skills - Fix template path reference (now skills/publisher/templates/) - Update CLAUDE.md project structure Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 9 +++++---- .../SKILL.md | 19 ++++++------------- 2 files changed, 11 insertions(+), 17 deletions(-) rename skills/{publisher => skill-publisher-wizard}/SKILL.md (52%) diff --git a/CLAUDE.md b/CLAUDE.md index 8e0b734..d559303 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -47,12 +47,13 @@ upskill/ ├── .claude-plugin/ │ └── plugin.json # Plugin metadata — minimal, no skills array ├── skills/ -│ ├── manager/SKILL.md +│ ├── skill-publisher-wizard/SKILL.md # First-publish wizard (scaffold → git → GitHub) +│ ├── skill-publisher-release/SKILL.md # Ongoing release cycle (bump → PR → tag → release) +│ ├── skill-publisher-marketplace/SKILL.md # Marketplace registry management │ ├── publisher/ -│ │ ├── SKILL.md -│ │ └── templates/ # Scaffold templates — read on demand, not loaded every session +│ │ └── templates/ # Shared scaffold templates — read on demand, not loaded every session │ ├── doctor/SKILL.md -│ └── auditor/SKILL.md +│ └── manager/SKILL.md ├── CLAUDE.md # This file ├── VISION.md # North star — read before doing anything ├── README.md diff --git a/skills/publisher/SKILL.md b/skills/skill-publisher-wizard/SKILL.md similarity index 52% rename from skills/publisher/SKILL.md rename to skills/skill-publisher-wizard/SKILL.md index 17ecd48..7ee1ef8 100644 --- a/skills/publisher/SKILL.md +++ b/skills/skill-publisher-wizard/SKILL.md @@ -1,10 +1,10 @@ --- -name: publisher -description: "Use when a user wants to publish, share, or version a skill — creating a plugin from a raw skill file, sharing a skill on GitHub, releasing a new version, bumping semver, or managing/versioning a project-level skill in .claude/skills/. Also use immediately after skill-creator completes." +name: skill-publisher-wizard +description: "Use when a user says 'publisher wizard' or 'new skill wizard', wants to publish or share a skill for the first time, scaffold a raw skill into a plugin, set up a GitHub repo for a skill, or just completed skill-creator and wants to ship it." version: 1.0.0 --- -Publisher takes a skill in any state and handles the full publication pipeline: scaffolding a plugin structure, git/GitHub setup, versioning, and releasing. It is the bridge between creating a skill and sharing it with the world. +skill-publisher-wizard takes a raw or partially structured skill and walks through the full first-publish pipeline: scaffolding a plugin structure, git/GitHub setup, and handing off to skill-publisher-release for versioning and skill-publisher-marketplace for registry registration. ## Prerequisites @@ -30,7 +30,7 @@ Show detected state. Route by the user's stated intent. If ambiguous, ask: "What ## Actions **Scaffold (raw → scaffolded):** -Ask: "Add to an existing plugin you own, or create a new one?" List only plugins where `plugin.json` author matches the user's GitHub username. If new, ask for the destination directory (suggest cwd). Read each template from the `templates/` directory adjacent to this skill file. Prompt user for `{{PLUGIN_NAME}}`, `{{PLUGIN_DESCRIPTION}}`, `{{KEYWORDS}}`; fill `{{AUTHOR_NAME}}` and `{{GITHUB_OWNER}}` from `gh api user`. Write filled templates to target. Fill README sections from context (skill names from `skills/`, descriptions from SKILL.md frontmatter, repo URL from `plugin.json`); flag only sections that require user-specific content Claude cannot infer. Move skill to `skills//SKILL.md`. Check `~/.claude/upskill-state.json` for `watermark.enabled`; if absent, ask once: "Add upskill attribution? [y/N]" and store the answer. If enabled, add `maintained-with: upskill (github.com/ngouy/upskill)` to SKILL.md frontmatter. +Ask: "Add to an existing plugin you own, or create a new one?" List only plugins where `plugin.json` author matches the user's GitHub username. If new, ask for the destination directory (suggest cwd). Read each template from `skills/publisher/templates/` in the upskill plugin directory. Prompt user for `{{PLUGIN_NAME}}`, `{{PLUGIN_DESCRIPTION}}`, `{{KEYWORDS}}`; fill `{{AUTHOR_NAME}}` and `{{GITHUB_OWNER}}` from `gh api user`. Write filled templates to target. Fill README sections from context (skill names from `skills/`, descriptions from SKILL.md frontmatter, repo URL from `plugin.json`); flag only sections that require user-specific content Claude cannot infer. Move skill to `skills//SKILL.md`. Check `~/.claude/upskill-state.json` for `watermark.enabled`; if absent, ask once: "Add upskill attribution? [y/N]" and store the answer. If enabled, add `maintained-with: upskill (github.com/ngouy/upskill)` to SKILL.md frontmatter. **Git init (scaffolded → git-tracked):** `git init`, stage all files, commit: `feat: initial plugin scaffold`. @@ -38,11 +38,8 @@ Ask: "Add to an existing plugin you own, or create a new one?" List only plugins **GitHub setup (git-tracked → github-hosted):** Ask visibility (public / private / org). Confirm before acting. Run `gh repo create --[public|private] --source=. --push`. Suggest next step: version bump. -**Version bump:** -Diff since last tag. Suggest: new capabilities → minor, breaking changes → major, docs/typos → patch. Explain reasoning. User can override. Create branch `upskill/bump-v`, update `plugin.json` version, prompt user to review/update `RELEASE-NOTES.md`, commit both as `chore: bump version to vX.Y.Z`, push, create PR. - -**Release (after version bump PR is merged):** -Confirm current branch is main and the version bump PR is merged. Confirm, then create git tag `vX.Y.Z` on main, push tag, and run `gh release create`. +**First release:** +After GitHub setup, hand off to skill-publisher-release to tag v1.0.0 and create the initial release. After release, hand off to skill-publisher-marketplace to register the plugin. ## Docs & Upgrades @@ -50,10 +47,6 @@ Confirm current branch is main and the version bump PR is merged. Confirm, then **Docs:** After scaffold or on request, flag any README sections still containing template stubs. Offer to fill them using context: skill names from `skills/`, descriptions from SKILL.md frontmatter, repo URL from `plugin.json`. List unfilled sections explicitly — never leave stubs silently. -## Project-Level Skills - -For skills in `/.claude/skills/`: version management only. Stop if the repo has uncommitted changes — ask to commit or stash first. Read `version` from frontmatter (default `1.0.0` if absent). Suggest bump level with reasoning. Update frontmatter version. Create branch `upskill/bump--v`. Spawn a sub-agent to create the PR, instructing it to read the project's CLAUDE.md and match its commit and PR conventions. - ## Must Never Do - Overwrite existing SKILL.md content