Skip to content

docs: marketplace install flow + 24h availability note #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
ngouy wants to merge 3 commits into from
Closed

docs: marketplace install flow + 24h availability note #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5f3187b
docs: update installation with marketplace flow and 24h availability …
Mar 9, 2026
af3fd8e
docs: mark unbuilt sections as under construction
Mar 9, 2026
18eeb2e
refactor(publisher): split into skill-publisher-wizard/release/market…
Mar 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
130 changes: 22 additions & 108 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,99 +32,62 @@

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

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

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

---

## Detailed Usage

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

---

Expand Down Expand Up @@ -198,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?)
Expand Down Expand Up @@ -285,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.

---

Expand Down
19 changes: 6 additions & 13 deletions skills/publisher/SKILL.md → skills/skill-publisher-wizard/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -30,30 +30,23 @@ 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/<name>/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/<name>/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`.

**GitHub setup (git-tracked → github-hosted):**
Ask visibility (public / private / org). Confirm before acting. Run `gh repo create <name> --[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<new-version>`, 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

**Upgrade (partial plugin → complete):** If `.claude-plugin/plugin.json` exists but files are missing, generate only what's absent — never overwrite. For a new skill added to an existing plugin: create `skills/<name>/SKILL.md`, update the README skills table, suggest a minor version bump.

**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 `<project>/.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-<skill-name>-v<new-version>`. 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
Expand Down