shipit-skill 0.1.0__tar.gz

shipit_skill-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## [0.1.0] - 2026-09-04
+
+Initial release.
+
+### Added
+
+- **SKILL.md** — one-pass launch pipeline for developer tools: Phase 0 recon,
+  Phase 1 engineering baseline, Phase 2 publish, Phase 3 directory listings,
+  Phase 4 promo. Includes an automation boundary and a "real-world scars"
+  gotcha list.
+- **scripts/**
+  - `ci.py` — CI workflow generator (Python with optional MCP-server Docker
+    handshake job, TypeScript).
+  - `publish.py` — prints build + registry publish commands, runs fresh-install
+    verification.
+  - `glama.py` — Glama listing/badge check with optional polling.
+  - `awesome_pr.py` — recipe for submitting to awesome directories (fork,
+    branch, Glama-badge entry, PR).
+  - `promo_check.py` — promo freshness check (stale versions / unknown PRs),
+    ignores IP-like version fragments.
+  - `mcp_smoke.py` — MCP initialize + tools/list smoke test over stdio.
+- **tests/** — 9 pytest cases covering the scripts.
+- **examples/mcp-server-launch.md** — end-to-end walkthrough using a toy MCP
+  server.
+- **pyproject.toml** — dev toolchain (pytest, ruff).
+- **.github/workflows/ci.yml** — lint + test.
+- **README.md**, **MIT LICENSE**.

shipit_skill-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 skyzhao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

shipit_skill-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: shipit-skill
+Version: 0.1.0
+Summary: One-pass launch pipeline Agent Skill for developer tools
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: PyYAML>=6.0; extra == "dev"
+Dynamic: license-file
+
+# ⚙️ shipit-skill
+
+[![CI](https://github.com/skyzhao1223/shipit-skill/actions/workflows/ci.yml/badge.svg)](https://github.com/skyzhao1223/shipit-skill/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Take an existing developer tool from "it works" to "published + listed + marketable" — one pass.**
+
+`shipit-skill` is an Agent Skill that runs the full launch pipeline for AI/developer tools
+(MCP servers, CLIs, libraries): engineering baseline → publish → directory listings →
+promo material. It was distilled from shipping [wheel-hub](https://github.com/skyzhao1223/wheel-hub),
+[zspace-cli](https://github.com/skyzhao1223/zspace-cli) and
+[media-manager-skill](https://github.com/skyzhao1223/media-manager-skill) — every gotcha
+below is one that actually bit during those releases.
+
+## Install
+
+Copy this folder into your project (or your agent's skills dir):
+
+```bash
+# for the current project
+cp -r shipit-skill/ ~/your-project/.opencode/skills/shipit-skill   # opencode
+# cp -r shipit-skill/ ~/your-project/skills/shipit-skill            # Claude Code, Cursor, etc.
+```
+
+## What it does
+
+| Phase | Exit criterion | Scripts |
+|-------|----------------|---------|
+| **0. Recon** | gap report (CI? Docker? Release? listed? promo?) | — |
+| **1. Baseline** | CI green, metadata right, Dockerfile present | `scripts/ci.py`, `scripts/mcp_smoke.py` |
+| **2. Publish** | on registry + GitHub Release + clean-env verified | `scripts/publish.py` |
+| **3. Listings** | Glama live + awesome PR open | `scripts/glama.py`, `scripts/awesome_pr.py` |
+| **4. Promo** | promo docs match reality | `scripts/promo_check.py` |
+
+See [`SKILL.md`](SKILL.md) for the full agent instructions and the automation
+boundary (what the agent runs vs. what needs a human/credential).
+
+## Example
+
+[`examples/mcp-server-launch.md`](examples/mcp-server-launch.md) walks all four
+phases against a toy `hello-mcp` server — reproduce it locally to learn the
+pipeline before applying it to a real project.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -q          # 9 tests
+ruff check .       # lint
+```
+
+## The scars (why this exists)
+
+- `mcp>=1.0` + a new SDK → fresh installs crash. Set dependency floors.
+- Python 3.9 can't install `mcp>=2.0` — split the CI matrix.
+- YAML block scalar + inline heredoc = broken workflow. Use a script file.
+- Glama introspection needs stdin held open (`sleep 1`) in smoke tests.
+- PyPI tokens start `pypi-`; UUID-style strings are wrong and 403.
+- npm typosquatting blocks similar names — scoped names dodge it.
+- Glama builds take minutes to hours — poll, don't panic.
+
+## License
+
+MIT

shipit_skill-0.1.0/README.md

@@ -0,0 +1,64 @@
+# ⚙️ shipit-skill
+
+[![CI](https://github.com/skyzhao1223/shipit-skill/actions/workflows/ci.yml/badge.svg)](https://github.com/skyzhao1223/shipit-skill/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Take an existing developer tool from "it works" to "published + listed + marketable" — one pass.**
+
+`shipit-skill` is an Agent Skill that runs the full launch pipeline for AI/developer tools
+(MCP servers, CLIs, libraries): engineering baseline → publish → directory listings →
+promo material. It was distilled from shipping [wheel-hub](https://github.com/skyzhao1223/wheel-hub),
+[zspace-cli](https://github.com/skyzhao1223/zspace-cli) and
+[media-manager-skill](https://github.com/skyzhao1223/media-manager-skill) — every gotcha
+below is one that actually bit during those releases.
+
+## Install
+
+Copy this folder into your project (or your agent's skills dir):
+
+```bash
+# for the current project
+cp -r shipit-skill/ ~/your-project/.opencode/skills/shipit-skill   # opencode
+# cp -r shipit-skill/ ~/your-project/skills/shipit-skill            # Claude Code, Cursor, etc.
+```
+
+## What it does
+
+| Phase | Exit criterion | Scripts |
+|-------|----------------|---------|
+| **0. Recon** | gap report (CI? Docker? Release? listed? promo?) | — |
+| **1. Baseline** | CI green, metadata right, Dockerfile present | `scripts/ci.py`, `scripts/mcp_smoke.py` |
+| **2. Publish** | on registry + GitHub Release + clean-env verified | `scripts/publish.py` |
+| **3. Listings** | Glama live + awesome PR open | `scripts/glama.py`, `scripts/awesome_pr.py` |
+| **4. Promo** | promo docs match reality | `scripts/promo_check.py` |
+
+See [`SKILL.md`](SKILL.md) for the full agent instructions and the automation
+boundary (what the agent runs vs. what needs a human/credential).
+
+## Example
+
+[`examples/mcp-server-launch.md`](examples/mcp-server-launch.md) walks all four
+phases against a toy `hello-mcp` server — reproduce it locally to learn the
+pipeline before applying it to a real project.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -q          # 9 tests
+ruff check .       # lint
+```
+
+## The scars (why this exists)
+
+- `mcp>=1.0` + a new SDK → fresh installs crash. Set dependency floors.
+- Python 3.9 can't install `mcp>=2.0` — split the CI matrix.
+- YAML block scalar + inline heredoc = broken workflow. Use a script file.
+- Glama introspection needs stdin held open (`sleep 1`) in smoke tests.
+- PyPI tokens start `pypi-`; UUID-style strings are wrong and 403.
+- npm typosquatting blocks similar names — scoped names dodge it.
+- Glama builds take minutes to hours — poll, don't panic.
+
+## License
+
+MIT

shipit_skill-0.1.0/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: shipit-skill
+description: >-
+  Ship a developer tool (AI agent tool, MCP server, CLI, or library) from
+  "it works" to "published + listed + marketable" in one pass. Triggers on
+  phrases like 上线 / 发布 / publish / release / 收录 / awesome PR / Glama /
+  launch / 宣传 / promo, or when a repo has code+tests but no CI, no package
+  release, no directory listing, or no promo material. Covers engineering
+  baseline → publish → directory listing → promo across Python/PyPI and
+  TypeScript/npm. Use whenever the goal is to take an existing open-source
+  project and ship it properly.
+---
+
+# shipit-skill — one-pass launch pipeline for developer tools
+
+Take an existing repo from "it works" to **published + listed + marketable**.
+Four phases, each with a hard exit criterion. Skipping a phase is allowed only
+if its exit criterion is already met.
+
+> Philosophy: **look before you build.** Check what already exists and what the
+> ecosystem requires *first* — the same way you'd advise any user not to
+> reinvent a wheel.
+
+---
+
+## Phase 0 — Recon (30s, always)
+
+Run these checks before touching anything:
+
+1. **Existing repo state** — `git status`, `git remote -v`, recent `git log`.
+2. **Package registration** — is the name taken? (`pip index versions <name>`,
+   `npm view <name>`, registry CDN). Names collide often; scoped names for npm
+   (`@org/pkg`) dodge typosquatting rules.
+3. **Similar projects** — search GitHub for direct competitors. If one exists,
+   note the differentiation explicitly; don't build a carbon copy.
+4. **The "exit criteria" gaps** — CI? Dockerfile? GitHub Release? listed on
+   Glama / awesome dirs? promo material current? Build a checklist of what's
+   missing. That checklist drives the rest.
+
+Output: a short gap report + plan. Get confirmation before Phase 1 if the
+gaps are large.
+
+---
+
+## Phase 1 — Engineering baseline
+
+Exit criterion: **CI green on the default branch**, package metadata correct,
+Dockerfile present (if it's an MCP/CLI server).
+
+- **CI**: add GitHub Actions. Python: matrix over supported versions, but mind
+  extras that require a newer interpreter (e.g. `mcp>=2.0` needs py3.10+ — run
+  the base on 3.9, extras on 3.12). Always include lint + tests + a
+  **container MCP handshake** job if a server ships.
+- **Dockerfile**: needed for Glama and container users. For stdio MCP servers:
+  base image + install the package + `CMD [the-server-command]`. Build **from
+  source** (COPY src) unless the published package is verified good — a stale
+  PyPI/npm release will silently break introspection.
+- **`.dockerignore`**: keep the image minimal (no `.git`, tests, promo, docs).
+- **Version from metadata**: MCP `serverInfo.version` and CLI `--version` must
+  read the package version, not a hardcoded string.
+- **Dependency floor**: if your code targets a new SDK API, set the dependency
+  floor (`mcp>=2.0`), don't leave `>=1.0` — pip/npm resolve to latest and break
+  fresh installs.
+
+Verify: clean `pip install .[extras]` / `npm install` in a temp venv, then run
+the MCP handshake (`initialize` + `tools/list`) against the *container*.
+
+---
+
+## Phase 2 — Publish
+
+Exit criterion: **package on the registry**, GitHub Release with tag + notes,
+clean-env install verified.
+
+- **Version bump** → build artifacts (`python -m build` / `npm pack`).
+- **Tag + GitHub Release**: title `vX.Y.Z`, notes with Changes / Install /
+  What-it-fixes. Let `gh release create` attach from the tag.
+- **Registry publish**:
+  - PyPI: needs a token (granular, scoped to the package, **Upload** perm).
+    If the token is malformed PyPI returns `403 Invalid or non-existent
+    authentication information` — UUID-style strings are wrong; real PyPI
+    tokens start `pypi-`. `twine upload` with `--username __token__`.
+  - npm: scoped names need the org to exist; granular token with bypass-2FA
+    for automation; `--//registry.npmjs.org/:_authToken` inline avoids writing
+    creds to disk.
+- **Fresh-install verification** (non-negotiable): create a venv / clean dir,
+  install from the *registry*, import the module / run the CLI / do the MCP
+  handshake. This catches "works on my machine" packaging bugs.
+- **Gotchas**:
+  - npm CDN serves cached 404s for minutes after first publish — don't panic,
+    cache-bust with a query param.
+  - `File already exists` on retry usually means the first attempt succeeded.
+  - Lockfile drift: rename packages → always `npm install` to regen the lock
+    or `npm ci` fails in CI.
+
+---
+
+## Phase 3 — Directory listings
+
+Exit criterion: **listed on Glama with a score badge** and **awesome PR open
+(or merged)**.
+
+- **Glama** (`glama.ai/mcp/servers`): user submits via browser (GitHub OAuth —
+  cannot be automated). Before submitting: Dockerfile must exist and pass
+  introspection (see Phase 1). After submit: the page takes **minutes to hours**
+  to appear — poll `https://glama.ai/mcp/servers/<owner>/<repo>` and
+  `/badges/score.svg`. Add the badge to the repo README once live:
+  `[![owner/repo MCP server](https://glama.ai/mcp/servers/owner/repo/badges/score.svg)](https://glama.ai/mcp/servers/owner/repo)`
+- **awesome-mcp-servers** (and similar curated lists): PRs are triaged by bots.
+  Format per the list's current convention (badge + lang + scope + OS + install
+  cmd). Maintainers now require the Glama badge in the entry — submit Glama
+  *first*. Add `🤖🤖🤖` to the PR title to opt into the agent fast-track.
+  Fork → branch off latest upstream main → add entry → PR. If a previous PR was
+  closed for inactivity, force-push the branch or recreate it.
+- **Other directories** (Smithery, PulseMCP, mcp.so…): Smithery reads a
+  `smithery.yaml` at repo root (stdio start command + optional env schema).
+
+---
+
+## Phase 4 — Promo material
+
+Exit criterion: **promo docs' versions/links/PR numbers match reality**; per-
+platform posts are *ready to paste* (user posts manually — no fake automation).
+
+- Maintain `promo/` with per-platform files (V2EX, 知乎, Reddit, X, community).
+- **Freshness check** (run whenever versions/PRs change): grep promo files for
+  old version numbers, dead PR links, stale release URLs. Update or mark stale.
+- **Fact discipline**: verify every number/claim before posting — rerun the
+  tool and compare output. Wrong claims get torn apart in comments (e.g. a
+  "no LICENSE" claim that's actually a GitHub metadata quirk).
+- Keep install commands unpinned (`pip install pkg`) so promo doesn't rot.
+
+---
+
+## Automation boundary
+
+| Step | Who runs it |
+|------|-------------|
+| CI files, Dockerfile, metadata, code fixes | Agent |
+| Build artifacts, fresh-install verification | Agent |
+| Registry publish (PyPI/npm) | Agent, **with a user-supplied token** |
+| Glama browser submit | User (OAuth) |
+| awesome/other PR create | Agent |
+| Posting to platforms | User |
+
+Never fabricate credentials; ask for the token explicitly and use it inline,
+never write it to a file.
+
+## Real-world scars (from shipping wheel-hub + zspace-cli)
+
+1. `mcp>=1.0` in extras + new SDK → fresh installs crash. Set floors.
+2. Python 3.9 can't install `mcp>=2.0`; CI matrix must split base vs extras.
+3. YAML block scalar + inline python heredoc = broken workflow. Use a script file.
+4. MCP 2.x `Server` object has no `list_tools` — use `@server.tool()` decorators.
+5. Glama introspection needs stdin held open for a beat (`sleep 1`) in smoke tests.
+6. PyPI token formats: `pypi-...` real, UUID = wrong.
+7. npm typosquatting blocks `wheel-hub` next to `wheelhub`; scoped names work.
+8. `.dockerignore` missing → giant images / secrets in build context.

shipit_skill-0.1.0/examples/mcp-server-launch.md

@@ -0,0 +1,80 @@
+# Example — shipping a minimal MCP server with shipit-skill
+
+This walks the 4 phases against a toy `hello-mcp` server so you can see exactly
+what shipit-skill produces at each step. Reproduce it locally to learn the pipeline,
+then apply the same steps to your real project.
+
+```
+hello-mcp/                  # your project (already has working code)
+├── pyproject.toml          # name=hello-mcp, extras mcp=["mcp>=2.0; python_version >= '3.10'"]
+├── src/hello_mcp/          # server.py with @server.tool() handlers
+├── tests/                  # passing tests
+└── scripts/mcp_smoke.py    # copy from shipit-skill/scripts/mcp_smoke.py
+```
+
+## Phase 1 — Baseline
+
+```bash
+# generate CI (python server → includes Docker handshake job)
+python3 shipit-skill/scripts/ci.py --lang python --server hello-mcp --pkg hello-mcp \
+  > hello-mcp/.github/workflows/ci.yml
+
+# Dockerfile (build from source so the image matches tested code)
+cat > hello-mcp/Dockerfile <<'EOF'
+FROM python:3.12-slim
+WORKDIR /app
+COPY pyproject.toml ./
+COPY src ./src
+RUN pip install --no-cache-dir ".[mcp]"
+CMD ["hello-mcp"]
+EOF
+cat > hello-mcp/.dockerignore <<'EOF'
+.git
+.github
+tests/
+dist/
+EOF
+```
+
+Exit check: CI green, `docker build` passes, handshake OK:
+
+```bash
+cd hello-mcp
+{ printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"s","version":"0"}}}\n{"jsonrpc":"2.0","method":"notifications/initialized"}\n{"jsonrpc":"2.0","id":2,"method":"tools/list"}\n'; sleep 1; } \
+  | docker run --rm -i hello-mcp 2>/dev/null | python3 scripts/mcp_smoke.py
+# → initialize OK ... / tools/list OK ...
+```
+
+## Phase 2 — Publish
+
+```bash
+python3 shipit-skill/scripts/publish.py --lang python --pkg hello-mcp --server hello-mcp --verify
+# prints build + twine commands; PYPI_TOKEN=<pypi-...> twine upload dist/...
+```
+
+## Phase 3 — Listings
+
+```bash
+python3 shipit-skill/scripts/glama.py --repo <you>/hello-mcp --poll 6
+# → LISTED ✅ once the build queue finishes (minutes to hours)
+
+python3 shipit-skill/scripts/awesome_pr.py \
+  --upstream punkpeye/awesome-mcp-servers \
+  --repo <you>/hello-mcp --fork <you>/awesome-mcp-servers \
+  --branch add-hello-mcp --title "Add <you>/hello-mcp to <Category>"
+```
+
+## Phase 4 — Promo
+
+```bash
+# keep promo/ with per-platform posts; when versions/PRs change:
+python3 shipit-skill/scripts/promo_check.py --dir promo --version 0.1.0 --prs 1234=open
+# → exit 1 lists every stale version / unknown PR before you paste anything
+```
+
+## Gotchas this example demonstrates
+
+- `mcp>=2.0` needs Python 3.10+ → CI matrix splits base (3.9) vs extras (3.12).
+- Dockerfile builds from `src/`, not the PyPI release → no stale-package surprises.
+- Glama needs stdin held open (`sleep 1`) during the handshake smoke test.
+- Promo versions rot fast → always run `promo_check.py` after a release.

shipit_skill-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "shipit-skill"
+version = "0.1.0"
+description = "One-pass launch pipeline Agent Skill for developer tools"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "ruff>=0.4",
+    "PyYAML>=6.0",
+]
+
+[tool.setuptools]
+# shipit-skill is a skill bundle, not a Python library — ship its files as data.
+include-package-data = false
+
+[tool.setuptools.data-files]
+"." = [
+    "SKILL.md",
+    "README.md",
+    "CHANGELOG.md",
+]
+"scripts" = ["scripts/*.py"]
+"examples" = ["examples/*.md"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

shipit_skill-0.1.0/scripts/awesome_pr.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""Helper for submitting to awesome lists (e.g. awesome-mcp-servers).
+
+Automates the mechanical parts; keeps the human-verifiable steps explicit.
+
+Usage:
+    python3 scripts/awesome_pr.py --upstream punkpeye/awesome-mcp-servers \
+        --repo skyzhao1223/zspace-cli --fork skyzhao1223/awesome-mcp-servers \
+        --branch add-zspace-cli --title "Add skyzhao1223/zspace-cli to File Systems"
+
+Steps printed (fork sync, branch, edit README, push, create PR). The README
+edit itself is intentionally manual — every list has its own format.
+"""
+
+# ruff: noqa: E501
+import argparse
+import subprocess
+import sys
+
+
+def sh(cmd: list[str]) -> str:
+    r = subprocess.run(cmd, capture_output=True, text=True)
+    if r.returncode != 0:
+        print(r.stderr.strip(), file=sys.stderr)
+    return r.stdout.strip()
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--upstream", required=True, help="punkpeye/awesome-mcp-servers")
+    ap.add_argument("--repo", required=True, help="your server repo, e.g. skyzhao1223/zspace-cli")
+    ap.add_argument("--fork", required=True, help="your fork of upstream")
+    ap.add_argument("--branch", required=True, help="branch to create, e.g. add-zspace-cli")
+    ap.add_argument("--title", default="", help="PR title; add ' 🤖🤖🤖' to opt into agent fast-track")
+    args = ap.parse_args()
+
+    print(f"""# awesome PR recipe — {args.repo}
+
+## 0. Prereqs
+- Glama listing live (run `python3 scripts/glama.py --repo {args.repo}`) — most
+  maintainers now REQUIRE the Glama score badge in the entry. Submit Glama first.
+
+## 1. Sync fork main
+    gh api repos/{args.fork}/merge-upstream -X POST -f branch=main
+
+## 2. Branch off latest upstream (in a fresh shallow clone)
+    cd /tmp && rm -rf ams
+    git clone --depth 1 https://github.com/{args.fork}.git ams && cd ams
+    git checkout -q -b {args.branch}
+    # if {args.branch} already exists from a closed PR: force push at the end
+
+## 3. Edit README
+    # find your category anchor, add the entry after it. Format (typical):
+    - [{args.repo}](https://github.com/{args.repo}) \\
+      [![{args.repo} MCP server](https://glama.ai/mcp/servers/{args.repo}/badges/score.svg)](https://glama.ai/mcp/servers/{args.repo}) \\
+      🐍 🏠 🍎 - <one-line description> \\`<install cmd>\\`
+
+## 4. Push + PR
+    git add README.md
+    git commit -m "Add {args.repo} to <Category>"
+    git push -f -u origin {args.branch}     # -f only if branch existed before
+    gh pr create --repo {args.upstream} --head {args.fork.split('/')[0]}:{args.branch} \\
+      --title "{args.title} 🤖🤖🤖" --body "<markdown body>"
+""")
+
+    print("# Commands above are guidance; nothing was executed.")
+
+
+if __name__ == "__main__":
+    main()

shipit_skill-0.1.0/scripts/ci.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""Generate a CI workflow for a Python or TypeScript project.
+
+Usage:
+    python3 scripts/ci.py --lang python  [--server zs-mcp]  [--pkg zspace-cli]
+    python3 scripts/ci.py --lang typescript
+
+Prints the YAML to stdout. Pipe to .github/workflows/ci.yml.
+"""
+
+# ruff: noqa: E501
+import argparse
+
+PY_CI = """name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [{py_versions}]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{{{ matrix.python-version }}}}
+          cache: pip
+      - run: pip install -e ".[dev]"
+        if: matrix.python-version == '{base_py}'
+      - run: pip install -e ".[mcp,dev]"
+        if: matrix.python-version != '{base_py}'
+      - run: ruff check src tests
+      - run: pytest -q
+{server_block}"""
+
+PY_SERVER_BLOCK = """
+  docker:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build image
+        run: docker build -t {pkg} .
+      - name: MCP handshake (initialize + tools/list)
+        run: |
+          set +e
+          {{
+            printf '{{"jsonrpc":"2.0","id":1,"method":"initialize","params":{{"protocolVersion":"2024-11-05","capabilities":{{}},"clientInfo":{{"name":"smoke","version":"0"}}}}}}\\n{{"jsonrpc":"2.0","method":"notifications/initialized"}}\\n{{"jsonrpc":"2.0","id":2,"method":"tools/list"}}\\n'
+            sleep 1
+          }} | docker run --rm -i {pkg} >/tmp/mcp-out.txt 2>/tmp/mcp-err.txt
+          rc=$?
+          echo "exit=$rc"; echo "--- stderr ---"; cat /tmp/mcp-err.txt
+          echo "--- stdout (first 500) ---"; head -c 500 /tmp/mcp-out.txt; echo
+          [ $rc -eq 0 ] && python3 scripts/mcp_smoke.py < /tmp/mcp-out.txt
+"""
+
+TS_CI = """name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: npm
+      - run: npm ci
+      - run: npm run build --workspaces --if-present
+      - run: npm test --workspaces --if-present
+"""
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--lang", required=True, choices=["python", "typescript"])
+    ap.add_argument("--server", help="MCP server console-script name (python only)")
+    ap.add_argument("--pkg", default="app", help="Docker image / package name")
+    ap.add_argument("--py-versions", default='"3.9", "3.12"', help="comma list")
+    ap.add_argument("--base-py", default="3.9", help="base interpreter for extras-free install")
+    args = ap.parse_args()
+
+    if args.lang == "typescript":
+        print(TS_CI)
+        return
+
+    server_block = ""
+    if args.server:
+        server_block = PY_SERVER_BLOCK.format(pkg=args.pkg)
+    print(PY_CI.format(
+        py_versions=args.py_versions,
+        base_py=args.base_py,
+        server_block=server_block,
+    ))
+
+
+if __name__ == "__main__":
+    main()

shipit_skill-0.1.0/scripts/glama.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+"""Check Glama listing status + badge availability for an MCP server.
+
+Usage:
+    python3 scripts/glama.py --repo skyzhao1223/zspace-cli [--poll 6] [--wait 40]
+
+Prints page status and badge status. With --poll, retries N times waiting
+--wait seconds between tries (Glama builds can take minutes to hours).
+Exit 0 if page is live (200), else 1.
+"""
+
+import argparse
+import time
+import urllib.request
+
+
+def status(url: str, ua: bool = True) -> int:
+    req = urllib.request.Request(url)
+    if ua:
+        req.add_header("User-Agent", "Mozilla/5.0")
+    try:
+        with urllib.request.urlopen(req, timeout=20) as r:
+            return r.status
+    except Exception:
+        return 404
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--repo", required=True, help="owner/repo")
+    ap.add_argument("--poll", type=int, default=0, help="poll attempts")
+    ap.add_argument("--wait", type=int, default=40, help="seconds between polls")
+    args = ap.parse_args()
+
+    page = f"https://glama.ai/mcp/servers/{args.repo}"
+    badge = f"{page}/badges/score.svg"
+
+    code = status(page)
+    print(f"page : {code}  {page}")
+    print(f"badge: {status(badge)}  {badge}")
+
+    tries = 0
+    while code != 200 and tries < args.poll:
+        tries += 1
+        print(f"waiting {args.wait}s (try {tries}/{args.poll})...")
+        time.sleep(args.wait)
+        code = status(page)
+        print(f"page : {code}  {page}")
+        if code == 200:
+            print(f"badge: {status(badge)}  {badge}")
+
+    if code != 200:
+        print("NOT LISTED YET — check the Glama dashboard for build/check status.")
+        raise SystemExit(1)
+    print("LISTED ✅")
+
+
+if __name__ == "__main__":
+    main()

shipit_skill-0.1.0/scripts/mcp_smoke.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+"""MCP smoke test: read initialize + tools/list over stdio and assert basics.
+
+Usage:
+    printf '<init>\n<notify>\n<tools-list>\n' \
+        | <server-cmd> | python3 scripts/mcp_smoke.py
+
+Exits 0 if initialize and tools/list were both received and parseable.
+"""
+
+import json
+import sys
+
+
+def main() -> None:
+    seen_init = False
+    seen_tools = False
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            d = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if d.get("id") == 1 and "result" in d:
+            assert "serverInfo" in d["result"], d
+            print("initialize OK:", d["result"]["serverInfo"])
+            seen_init = True
+        if d.get("id") == 2 and "result" in d:
+            names = [t["name"] for t in d["result"]["tools"]]
+            print("tools/list OK:", len(names), "tools:", names[:4], "...")
+            seen_tools = True
+    assert seen_init, "no initialize response received"
+    assert seen_tools, "no tools/list response received"
+
+
+if __name__ == "__main__":
+    main()

shipit_skill-0.1.0/scripts/promo_check.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""Check promo material freshness: versions, PR numbers, release URLs.
+
+Usage:
+    python3 scripts/promo_check.py --dir promo --version 0.1.1
+    python3 scripts/promo_check.py --dir promo --version 0.1.1 --prs 8262=closed,13600=open
+
+Scans *.md in --dir for:
+  - version numbers (semver) that differ from --version (reports old ones)
+  - GitHub PR/issue links (#NNNNN) not present in --prs
+  - github release/tag URLs (reports for manual eyeball)
+Exit code 1 if any stale version or unknown PR is found.
+"""
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+# Match "v0.1.0" / "0.1.1" / " 0.3.0" but NOT "127.0.0.1" (IPs) or "x.y.z".
+SEMVER = re.compile(r"(?<![\d.])(?:v)?0\.\d+\.\d+\b")
+PR_LINK = re.compile(r"#(\d{4,})")
+RELEASE_URL = re.compile(r"releases/tag/([\w.]+)")
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--dir", required=True)
+    ap.add_argument("--version", required=True, help="current version, e.g. 0.1.1")
+    ap.add_argument("--prs", default="", help="known PRs as id=state,... e.g. 13600=open")
+    args = ap.parse_args()
+
+    known_prs = {k: v for k, v in (kv.split("=") for kv in args.prs.split(",") if kv)}
+    target = tuple(int(x) for x in args.version.split("."))
+    errors: list[str] = []
+
+    for path in sorted(Path(args.dir).glob("*.md")):
+        text = path.read_text(encoding="utf-8")
+        for m in SEMVER.finditer(text):
+            v = m.group(0).lstrip("v")
+            cur = tuple(int(x) for x in v.split("."))
+            if cur != target:
+                line = text[: m.start()].count("\n") + 1
+                errors.append(f"{path.name}:{line}: stale version {v} (current {args.version})")
+        for m in PR_LINK.finditer(text):
+            pid = m.group(1)
+            if pid not in known_prs:
+                line = text[: m.start()].count("\n") + 1
+                errors.append(
+                    f"{path.name}:{line}: unknown PR/issue #{pid} (known: {sorted(known_prs)})"
+                )
+        for m in RELEASE_URL.finditer(text):
+            tag = m.group(1)
+            line = text[: m.start()].count("\n") + 1
+            print(
+        f"{path.name}:{line}: release tag {tag} (verify manually)"
+    )
+
+    if errors:
+        print("\n".join(errors))
+        sys.exit(1)
+    print("OK: no stale versions or unknown PRs.")
+
+
+if __name__ == "__main__":
+    main()

shipit_skill-0.1.0/scripts/publish.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+"""Publish helper: build, verify fresh install, and emit publish commands.
+
+Usage:
+    python3 scripts/publish.py --lang python [--pkg zspace-cli] [--server zs-mcp]
+    python3 scripts/publish.py --lang typescript [--pkg @org/cli]
+
+Prints the exact publish commands (needs a user-supplied token — never stored).
+Also runs a fresh-install verification in a temp venv when --verify.
+"""
+
+# ruff: noqa: E501
+import argparse
+import subprocess
+import sys
+import tempfile
+
+
+def run(cmd: list[str]) -> None:
+    subprocess.run(cmd, check=True)
+
+
+def verify_python(pkg: str, server: str | None, extras: str) -> None:
+    tmp = tempfile.mkdtemp(prefix="shipit-")
+    run([sys.executable, "-m", "venv", f"{tmp}/venv"])
+    pip = f"{tmp}/venv/bin/pip"
+    run([pip, "install", "-q", extras])
+    importlib = f"{tmp}/venv/bin/python"
+    subprocess.run([importlib, "-c", f"import importlib.metadata as m; print('installed', m.version('{pkg}'))"], check=True)
+    if server:
+        init = '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}\n{"jsonrpc":"2.0","method":"notifications/initialized"}\n{"jsonrpc":"2.0","id":2,"method":"tools/list"}\n'
+        handshake = f"printf '{init}' | {tmp}/venv/bin/{server} 2>/dev/null | python3 -c \"import sys,json; [print(json.loads(l)['result'].get('serverInfo')) for l in sys.stdin if l.strip()]\""
+        subprocess.run(["bash", "-c", handshake], check=True)
+    print(f"fresh-install OK (venv: {tmp}/venv)")
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--lang", required=True, choices=["python", "typescript"])
+    ap.add_argument("--pkg", required=True, help="package name")
+    ap.add_argument("--server", help="MCP console script name (python)")
+    ap.add_argument("--verify", action="store_true", help="run fresh-install check")
+    args = ap.parse_args()
+
+    if args.lang == "python":
+        print("# Build\npython3 -m build")
+        print(f"# Publish (set PYPI_TOKEN=<pypi-... token, Upload scope on {args.pkg}>)\n"
+              f"python3 -m twine upload --repository-url https://upload.pypi.org/legacy/ \\\n"
+              f"  --username __token__ --password \"$PYPI_TOKEN\" dist/{args.pkg}-*.tar.gz dist/{args.pkg}-*.whl")
+        if args.verify:
+            verify_python(args.pkg, args.server, args.pkg)
+    else:
+        print("# Publish (set NPM_TOKEN=<granular token, bypass-2fa>)\n"
+              "npm publish --//registry.npmjs.org/:_authToken=\"$NPM_TOKEN\" --access public")
+
+
+if __name__ == "__main__":
+    main()

shipit_skill-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

shipit_skill-0.1.0/shipit_skill.egg-info/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: shipit-skill
+Version: 0.1.0
+Summary: One-pass launch pipeline Agent Skill for developer tools
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: PyYAML>=6.0; extra == "dev"
+Dynamic: license-file
+
+# ⚙️ shipit-skill
+
+[![CI](https://github.com/skyzhao1223/shipit-skill/actions/workflows/ci.yml/badge.svg)](https://github.com/skyzhao1223/shipit-skill/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Take an existing developer tool from "it works" to "published + listed + marketable" — one pass.**
+
+`shipit-skill` is an Agent Skill that runs the full launch pipeline for AI/developer tools
+(MCP servers, CLIs, libraries): engineering baseline → publish → directory listings →
+promo material. It was distilled from shipping [wheel-hub](https://github.com/skyzhao1223/wheel-hub),
+[zspace-cli](https://github.com/skyzhao1223/zspace-cli) and
+[media-manager-skill](https://github.com/skyzhao1223/media-manager-skill) — every gotcha
+below is one that actually bit during those releases.
+
+## Install
+
+Copy this folder into your project (or your agent's skills dir):
+
+```bash
+# for the current project
+cp -r shipit-skill/ ~/your-project/.opencode/skills/shipit-skill   # opencode
+# cp -r shipit-skill/ ~/your-project/skills/shipit-skill            # Claude Code, Cursor, etc.
+```
+
+## What it does
+
+| Phase | Exit criterion | Scripts |
+|-------|----------------|---------|
+| **0. Recon** | gap report (CI? Docker? Release? listed? promo?) | — |
+| **1. Baseline** | CI green, metadata right, Dockerfile present | `scripts/ci.py`, `scripts/mcp_smoke.py` |
+| **2. Publish** | on registry + GitHub Release + clean-env verified | `scripts/publish.py` |
+| **3. Listings** | Glama live + awesome PR open | `scripts/glama.py`, `scripts/awesome_pr.py` |
+| **4. Promo** | promo docs match reality | `scripts/promo_check.py` |
+
+See [`SKILL.md`](SKILL.md) for the full agent instructions and the automation
+boundary (what the agent runs vs. what needs a human/credential).
+
+## Example
+
+[`examples/mcp-server-launch.md`](examples/mcp-server-launch.md) walks all four
+phases against a toy `hello-mcp` server — reproduce it locally to learn the
+pipeline before applying it to a real project.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -q          # 9 tests
+ruff check .       # lint
+```
+
+## The scars (why this exists)
+
+- `mcp>=1.0` + a new SDK → fresh installs crash. Set dependency floors.
+- Python 3.9 can't install `mcp>=2.0` — split the CI matrix.
+- YAML block scalar + inline heredoc = broken workflow. Use a script file.
+- Glama introspection needs stdin held open (`sleep 1`) in smoke tests.
+- PyPI tokens start `pypi-`; UUID-style strings are wrong and 403.
+- npm typosquatting blocks similar names — scoped names dodge it.
+- Glama builds take minutes to hours — poll, don't panic.
+
+## License
+
+MIT

shipit_skill-0.1.0/shipit_skill.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+CHANGELOG.md
+LICENSE
+README.md
+SKILL.md
+pyproject.toml
+examples/mcp-server-launch.md
+scripts/awesome_pr.py
+scripts/ci.py
+scripts/glama.py
+scripts/mcp_smoke.py
+scripts/promo_check.py
+scripts/publish.py
+shipit_skill.egg-info/PKG-INFO
+shipit_skill.egg-info/SOURCES.txt
+shipit_skill.egg-info/dependency_links.txt
+shipit_skill.egg-info/requires.txt
+shipit_skill.egg-info/top_level.txt
+tests/test_scripts.py

shipit_skill-0.1.0/shipit_skill.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

shipit_skill-0.1.0/shipit_skill.egg-info/requires.txt

@@ -0,0 +1,5 @@
+
+[dev]
+pytest>=7.0
+ruff>=0.4
+PyYAML>=6.0

shipit_skill-0.1.0/shipit_skill.egg-info/top_level.txt

@@ -0,0 +1 @@
+

shipit_skill-0.1.0/tests/test_scripts.py

@@ -0,0 +1,105 @@
+"""Tests for shipit-skill helper scripts."""
+
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SCRIPTS = ROOT / "scripts"
+
+
+def run_script(name: str, *args: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [sys.executable, str(SCRIPTS / name), *args],
+        capture_output=True,
+        text=True,
+        cwd=ROOT,
+    )
+
+
+def test_ci_python_yaml_valid():
+    r = run_script("ci.py", "--lang", "python", "--server", "zs-mcp", "--pkg", "app")
+    assert r.returncode == 0
+    import yaml
+
+    data = yaml.safe_load(r.stdout)
+    assert "test" in data["jobs"]
+    assert "docker" in data["jobs"]
+    assert "matrix" in data["jobs"]["test"]["strategy"]
+
+
+def test_ci_python_without_server_has_no_docker_job():
+    r = run_script("ci.py", "--lang", "python")
+    import yaml
+
+    data = yaml.safe_load(r.stdout)
+    assert "docker" not in data["jobs"]
+
+
+def test_ci_typescript_yaml_valid():
+    r = run_script("ci.py", "--lang", "typescript")
+    assert r.returncode == 0
+    import yaml
+
+    data = yaml.safe_load(r.stdout)
+    assert "build" in data["jobs"]
+
+
+def test_promo_check_detects_stale_version(tmp_path: Path):
+    (tmp_path / "post.md").write_text(
+        "# post\nInstall v0.1.0 and check PR #1234\n", encoding="utf-8"
+    )
+    r = run_script(
+        "promo_check.py", "--dir", str(tmp_path), "--version", "0.1.1", "--prs", "1234=open"
+    )
+    assert r.returncode == 1
+    assert "stale version 0.1.0" in r.stdout
+
+
+def test_promo_check_ignores_ip_like_versions(tmp_path: Path):
+    (tmp_path / "post.md").write_text(
+        "proxy at 127.0.0.1:13579 and version 0.1.1\n", encoding="utf-8"
+    )
+    r = run_script("promo_check.py", "--dir", str(tmp_path), "--version", "0.1.1")
+    assert r.returncode == 0
+
+
+def test_promo_check_unknown_pr(tmp_path: Path):
+    (tmp_path / "post.md").write_text("see PR #9999\n", encoding="utf-8")
+    r = run_script("promo_check.py", "--dir", str(tmp_path), "--version", "0.1.1")
+    assert r.returncode == 1
+    assert "unknown PR/issue #9999" in r.stdout
+
+
+def test_mcp_smoke_ok():
+    payload = (
+        '{"jsonrpc":"2.0","id":1,"result":{"serverInfo":{"name":"x","version":"1"}}}\n'
+        '{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"a"}]}}\n'
+    )
+    r = subprocess.run(
+        [sys.executable, str(SCRIPTS / "mcp_smoke.py")],
+        input=payload,
+        capture_output=True,
+        text=True,
+    )
+    assert r.returncode == 0
+    assert "initialize OK" in r.stdout
+
+
+def test_mcp_smoke_fails_on_missing_tools():
+    payload = '{"jsonrpc":"2.0","id":1,"result":{"serverInfo":{"name":"x","version":"1"}}}\n'
+    r = subprocess.run(
+        [sys.executable, str(SCRIPTS / "mcp_smoke.py")],
+        input=payload,
+        capture_output=True,
+        text=True,
+    )
+    assert r.returncode != 0
+    assert "tools/list" in r.stderr
+
+
+def test_glama_reports_not_listed():
+    # glama.py with a repo guaranteed to not be listed should exit 1.
+    r = run_script("glama.py", "--repo", "skyzhao1223/definitely-not-a-repo-xyz")
+    assert r.returncode == 1
+    assert "NOT LISTED YET" in r.stdout