chore: npm publish setup, fallback docs, release workflow (fixes #49)

- package.json: yaml in devDependencies, repo url/bin from npm pkg fix
- README, GETTING_STARTED, FAQ: fallback npx github:sickn33/antigravity-awesome-skills on 404
- publish-npm.yml: workflow on release published + workflow_dispatch
- MAINTENANCE: bump package.json, publish to npm (manual + NPM_TOKEN CI)
- release_cycle.sh: catalog step, version check, npm publish reminder
- ISSUE_49_COMMENT.md: suggested reply for issue #49

.github/ISSUE_49_COMMENT.md

@@ -0,0 +1,15 @@
+Suggested comment for [Issue #49](https://github.com/sickn33/antigravity-awesome-skills/issues/49). Paste this on the issue:
+
+---
+
+The 404 happens because the package wasn’t published to npm yet. We’ve addressed it in two ways:
+
+1. **Publish to npm** – We’re set up to publish so `npx antigravity-awesome-skills` will work after the first release. You can also trigger a manual publish via the “Publish to npm” workflow (Actions tab) if you have `NPM_TOKEN` configured.
+
+2. **Fallback** – Until then (or if you hit a 404 for any reason), use:
+   ```bash
+   npx github:sickn33/antigravity-awesome-skills
+   ```
+   The README, GETTING_STARTED, and FAQ now mention this fallback.
+
+Thanks for reporting.

.github/MAINTENANCE.md

@@ -173,12 +173,22 @@ When cutting a new version (e.g., V4):
 
 1.  **Run Full Validation**: `python3 scripts/validate_skills.py --strict`
 2.  **Update Changelog**: Add the new release section to `CHANGELOG.md`.
-3.  **Bump Version**: Update header in `README.md`.
+3.  **Bump Version**:
+    - Update `package.json` → `"version": "X.Y.Z"` (source of truth for npm).
+    - Update version header in `README.md` if it displays the number.
+    - One-liner: `npm version patch` (or `minor`/`major`) — bumps `package.json` and creates a git tag; then amend if you need to tag after release.
 4.  **Tag Release**:
     ```bash
     git tag -a v4.0.0 -m "V4 Enterprise Edition"
     git push origin v4.0.0
     ```
+5.  **Publish to npm** (so `npx antigravity-awesome-skills` works):
+    - **Option A (manual):** From repo root, with npm logged in and 2FA/token set up:
+      ```bash
+      npm publish
+      ```
+      You cannot republish the same version; always bump `package.json` before publishing.
+    - **Option B (CI):** On GitHub, create a **Release** (tag e.g. `v4.6.1`). The workflow [Publish to npm](.github/workflows/publish-npm.yml) runs on **Release published** and runs `npm publish` if the repo secret `NPM_TOKEN` is set (npm → Access Tokens → Granular token with Publish, then add as repo secret `NPM_TOKEN`).
 
 ### 📋 Changelog Entry Template
 

.github/workflows/publish-npm.yml

@@ -0,0 +1,28 @@
+# Publish antigravity-awesome-skills to npm on release.
+# Requires NPM_TOKEN secret (npm → Access Tokens → Granular token with Publish).
+# Before creating a Release: bump package.json "version" (npm forbids republishing the same version).
+# Release tag (e.g. v4.6.1) should match package.json version.
+
+name: Publish to npm
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Publish
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

README.md

@@ -155,6 +155,8 @@ npx antigravity-awesome-skills --path ./my-skills
 
 Run `npx antigravity-awesome-skills --help` for all options. If the directory already exists, the installer runs `git pull` to update.
 
+> **If you see a 404 error:** the package may not be published to npm yet. Use: `npx github:sickn33/antigravity-awesome-skills`
+
 ### Option B: git clone
 
 ```bash

docs/FAQ.md

@@ -62,7 +62,11 @@ _Always check the Risk label and review the code._
 
 ### Where should I install the skills?
 
-The universal path that works with most tools is `.agent/skills/`:
+The universal path that works with most tools is `.agent/skills/`.
+
+**Using npx:** `npx antigravity-awesome-skills` (or `npx github:sickn33/antigravity-awesome-skills` if you get a 404).
+
+**Using git clone:**
 
 ```bash
 git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills

docs/GETTING_STARTED.md

@@ -30,6 +30,8 @@ npx antigravity-awesome-skills
 
 This clones to `~/.agent/skills` by default. Use `--cursor`, `--claude`, or `--gemini` to install for a specific tool, or `--path <dir>` for a custom location. Run `npx antigravity-awesome-skills --help` for details.
 
+If you see a 404 error, use: `npx github:sickn33/antigravity-awesome-skills`
+
 **Option B — git clone:**
 
 ```bash

package.json

@@ -12,15 +12,15 @@
     "catalog": "node scripts/build-catalog.js",
     "build": "npm run chain && npm run catalog"
   },
-  "dependencies": {
+  "devDependencies": {
     "yaml": "^2.8.2"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/sickn33/antigravity-awesome-skills.git"
+    "url": "git+https://github.com/sickn33/antigravity-awesome-skills.git"
   },
   "bin": {
-    "antigravity-awesome-skills": "./bin/install.js"
+    "antigravity-awesome-skills": "bin/install.js"
   },
   "files": [
     "bin"

scripts/release_cycle.sh

@@ -21,8 +21,12 @@ python3 scripts/generate_index.py
 echo "Running update_readme.py..."
 python3 scripts/update_readme.py
 
-# 2. Stats Consistency Check
+# 2. Catalog (required for CI)
-echo -e "\n${YELLOW}Step 2: verifying Stats Consistency...${NC}"
+echo -e "\n${YELLOW}Step 2: Build catalog...${NC}"
+npm run catalog
+
+# 3. Stats Consistency Check
+echo -e "\n${YELLOW}Step 3: Verifying Stats Consistency...${NC}"
 JSON_COUNT=$(python3 -c "import json; print(len(json.load(open('skills_index.json'))))")
 echo "Skills in Registry (JSON): $JSON_COUNT"
 
@@ -36,8 +40,14 @@ if [[ "$README_CONTENT" != *"$JSON_COUNT high-performance"* ]]; then
 fi
 echo -e "${GREEN}✅ Stats Consistent.${NC}"
 
-# 3. Contributor Check
+# 4. Version check (package.json is source of truth for npm)
-echo -e "\n${YELLOW}Step 3: Contributor Check${NC}"
+echo -e "\n${YELLOW}Step 4: Version check${NC}"
+PKG_VERSION=$(node -p "require('./package.json').version")
+echo "package.json version: $PKG_VERSION"
+echo "Ensure this version is bumped before 'npm publish' (npm forbids republishing the same version)."
+
+# 5. Contributor Check
+echo -e "\n${YELLOW}Step 5: Contributor Check${NC}"
 echo "Recent commits by author (check against README 'Repo Contributors'):"
 git shortlog -sn --since="1 month ago" --all --no-merges | head -n 10
 
@@ -52,4 +62,5 @@ if [ "$CONFIRM_CONTRIB" != "yes" ]; then
 fi
 
 echo -e "\n${GREEN}✅ Release Cycle Checks Passed. You may now commit and push.${NC}"
+echo -e "${YELLOW}After tagging a release: run \`npm publish\` from repo root (or use GitHub Release + NPM_TOKEN for CI).${NC}"
 exit 0