skillship 1.0.0 → 1.0.2

package/README.md

@@ -16,11 +16,29 @@ registry. It adds the three things the ecosystem is missing:
 
 ## Install / usage
 
+Both commands below use `npx`, which ships with [Node.js](https://nodejs.org)
+(>= 18). If `npx` is not found, install Node.js first — e.g. download the LTS
+installer from [nodejs.org](https://nodejs.org), or use a version manager
+(`brew install node`, `nvm install --lts`, `winget install OpenJS.NodeJS.LTS`).
+Verify with `node -v` and `npx -v`.
+
+**Recommended:** install the bundled `/skillship` Agent Skill straight from
+GitHub. It drives the CLI for you — invoke `/skillship` (or ask to publish a
+skill) and the agent locates/scaffolds a `SKILL.md`, validates it, fixes issues,
+and installs or packages it for the chosen surface:
+
 ```bash
-npx skillship <command>
+npx skills add shivdeepak/skillship
 ```
 
-Requires Node.js >= 18.
+Add `-a <agent>` (e.g. `-a cursor`, repeatable) to target specific agents, or
+`-g` to install globally.
+
+Or run the CLI directly with `npx` (requires Node.js >= 18):
+
+```bash
+npx skillship <command>
+```
 
 ## Commands
 
@@ -148,9 +166,42 @@ src/
   lib/exec.ts             # spawn wrappers for npx skills / gh / agentskills
   lib/load.ts             # SKILL.md loader
 templates/                # CI + snippet + AGENTS/README/SKILL templates for init
+skillship/                # bundled Agent Skill (the /skillship skill)
 test/                     # vitest specs + fixtures
 ```
 
+## Releases
+
+Releases are automated via
+[release-please](https://github.com/googleapis/release-please-action) +
+[Conventional Commits](https://www.conventionalcommits.org/). On every push to
+`main`, release-please opens/updates a release PR that bumps the version in
+`package.json` and the `CHANGELOG.md` based on the commits since the last
+release (`feat:` -> minor, `fix:`/`perf:` -> patch, `feat!:`/`BREAKING CHANGE`
+-> major). Merging that PR tags the release and triggers `npm publish` from
+`.github/workflows/release.yml`. `chore:`/`ci:` commits do not trigger a
+release.
+
+Publishing uses **npm trusted publishing (OIDC)** — no `NPM_TOKEN` secret. The
+workflow requests a short-lived OIDC token (`id-token: write`) that npm verifies
+against the trusted-publisher config; provenance attestations are generated
+automatically.
+
+`.github/workflows/ci.yml` runs lint + test + build on every push and PR.
+
+One-time setup:
+
+1. Enable **Settings -> Actions -> General -> Workflow permissions**: "Read and
+   write" and "Allow GitHub Actions to create and approve pull requests" so
+   release-please can open release PRs.
+2. Publish `1.0.0` once manually (`npm publish --access public`) — trusted
+   publishing can only be configured for a package that already exists.
+3. On npmjs.com, open the package's **Access** page and add a **Trusted
+   Publisher** for GitHub Actions, matching repo `shivdeepak/skillship` and
+   workflow file `release.yml` exactly. After that, every release publishes
+   tokenlessly. Optionally set the package to "require 2FA and disallow tokens"
+   so only the workflow can publish.
+
 ## License
 
 MIT

package/package.json

@@ -1,14 +1,19 @@
 {
   "name": "skillship",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Make any Agent Skill (SKILL.md) portable across Cursor, Claude Code, Claude Web, and Claude Cowork.",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shivdeepak/skillship.git"
+  },
   "bin": {
     "skillship": "dist/cli.js"
   },
   "files": [
     "dist",
     "templates",
+    "skillship",
     "README.md"
   ],
   "engines": {

package/skillship/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: skillship
+description: Turn a project into a publishable Agent Skill via the skillship CLI. Use to scaffold, validate, package, install, or publish a SKILL.md for Cursor, Claude Code, Claude Web, or Cowork, or on /skillship
+---
+
+# skillship
+
+Drive the `skillship` CLI to convert the user's project into a portable Agent
+Skill and publish it. Run the CLI for the user; do not ask them to run commands
+manually.
+
+## Workflow
+
+Copy this checklist and track progress:
+
+```
+- [ ] 1. Locate or create the SKILL.md
+- [ ] 2. Validate (skillship validate)
+- [ ] 3. Fix any reported issues, re-validate until clean
+- [ ] 4. Confirm publish target with the user
+- [ ] 5. Install (filesystem) or package (Claude upload)
+```
+
+### Step 1 — Locate or create the SKILL.md
+
+A skill is a directory containing a `SKILL.md`. Find one in the project (search
+for `SKILL.md`). Determine `<dir>` = the folder that directly contains it.
+
+- **Already exists** → use it.
+- **Does not exist** → scaffold one:
+
+```bash
+npx skillship init <name> --ci --snippets
+```
+
+Then author the `SKILL.md` body following the `create-skill` skill's rules
+(third-person `description`, both WHAT and WHEN, under 500 lines). The skill
+`name` must be lowercase letters/numbers/hyphens and match the parent folder.
+
+### Step 2 — Validate
+
+```bash
+npx skillship validate <dir> --profile all
+```
+
+`--profile all` is the strictest (Claude's 200-char description cap). Use
+`--json` if you need to parse results programmatically.
+
+### Step 3 — Fix and re-validate
+
+Read each failure, edit the `SKILL.md`, and re-run validate until it exits 0.
+Common failures: description over 200 chars, `name` not matching the folder,
+`<`/`>` characters in the description, body over 500 lines (warning only).
+
+### Step 4 — Confirm the publish target
+
+Ask the user where to publish (use AskQuestion). Targets:
+
+| Target | Mechanism |
+| --- | --- |
+| `cursor`, `claude-code` | Filesystem install |
+| `claude-web`, `claude-cowork` | Upload-only `.skill` zip |
+
+### Step 5 — Install or package
+
+**Filesystem agents** (e.g. Cursor, Claude Code) — install with the `npx skills`
+convention that skillship wraps:
+
+```bash
+npx skillship install <dir> -a cursor,claude-code
+# equivalently: npx skills add <dir> -a cursor,claude-code
+```
+
+Add `--global` to install for all projects, `--copy` to copy instead of
+symlink.
+
+**Upload-only surfaces** (e.g. Claude Web / Cowork):
+
+```bash
+npx skillship package <dir>        # -> dist/<name>.skill
+```
+
+Then tell the user to upload `dist/<name>.skill`:
+- Claude Web: Settings → Capabilities → Upload skill → enable toggle.
+- Claude Cowork: Customize → Skills → Upload (desktop app only).
+
+## Publishing via CI (optional)
+
+If the skill repo was created with `init --ci`, it auto-releases via
+release-please + Conventional Commits. After pushing, tell the user to enable
+**Settings → Actions → Workflow permissions**: "Read and write" and "Allow
+GitHub Actions to create and approve pull requests" so release-please can open
+release PRs and attach the `.skill` asset.
+
+## Invoking the CLI
+
+Prefer `npx skillship <command>`. If `npx skillship` cannot resolve the package
+(not published / offline), run it from a local checkout instead:
+
+```bash
+npm run build            # in the skillship repo, produces dist/cli.js
+node dist/cli.js <command>
+```
+
+Run `npx skillship doctor` to verify the environment (Node >= 18, npx; optional
+gh and agentskills).