@arthai/agents 1.0.0 → 1.0.3

package/skills/publish/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: publish
+description: "Compile plugins, validate against Anthropic spec, publish to npm + marketplace. Usage: /publish [version], /publish patch, /publish minor, /publish major, /publish validate"
+user-invocable: true
+arguments: "version, patch, minor, major, or validate"
+---
+
+# /publish — Release Distribution Channels
+
+Compiles plugins, validates against the Anthropic Claude Code plugin spec, publishes to npm and updates the marketplace repo. Handles version bumping, tagging, and post-publish verification.
+
+## Argument Parsing
+
+| Input | Action |
+|-------|--------|
+| `/publish` | Validate + show current state, prompt for version |
+| `/publish validate` | Validate only — no publish, no tag |
+| `/publish patch` | Bump patch (1.0.0 → 1.0.1), compile, validate, tag, push |
+| `/publish minor` | Bump minor (1.0.0 → 1.1.0), compile, validate, tag, push |
+| `/publish major` | Bump major (1.0.0 → 2.0.0), compile, validate, tag, push |
+| `/publish 1.2.3` | Set exact version, compile, validate, tag, push |
+
+## Step 1: Read Current State
+
+```bash
+# Current version
+cat VERSION
+
+# Last published npm version
+npm view @arthai/agents version 2>/dev/null || echo "not published"
+
+# Last git tag
+git describe --tags --abbrev=0 2>/dev/null || echo "no tags"
+
+# Uncommitted changes
+git status --short
+```
+
+If there are uncommitted changes, STOP. Tell the user to commit first.
+
+## Step 2: Compile Plugins
+
+```bash
+chmod +x compiler.sh
+./compiler.sh
+```
+
+If the compiler fails, STOP and show the error.
+
+## Step 3: Validate Against Anthropic Plugin Spec
+
+Run ALL of these checks. Every failure is a blocker.
+
+### 3a. plugin.json validation
+
+For each plugin in `dist/plugins/*/`:
+
+```bash
+# plugin.json exists and is valid JSON
+jq empty "$plugin/.claude-plugin/plugin.json"
+
+# Required: name (string)
+jq -e '.name | type == "string"' "$plugin/.claude-plugin/plugin.json"
+
+# author must be object, not string
+AUTHOR_TYPE=$(jq -r '.author | type' "$plugin/.claude-plugin/plugin.json")
+if [ "$AUTHOR_TYPE" = "string" ]; then
+  echo "FAIL: author must be {\"name\": \"...\"}, not a string"
+fi
+
+# version must be valid semver
+jq -r '.version' "$plugin/.claude-plugin/plugin.json" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'
+```
+
+### 3b. Directory structure
+
+```bash
+# Components at plugin root, NOT inside .claude-plugin/
+for dir in agents skills hooks; do
+  if [ -d "$plugin/.claude-plugin/$dir" ]; then
+    echo "FAIL: $dir/ must be at plugin root, not inside .claude-plugin/"
+  fi
+done
+```
+
+### 3c. No symlinks (causes install failures)
+
+```bash
+# Zero symlinks in compiled output
+SYMLINKS=$(find "$plugin" -type l 2>/dev/null)
+if [ -n "$SYMLINKS" ]; then
+  echo "FAIL: symlinks found — Claude Code copies plugins to cache, symlinks break"
+  echo "$SYMLINKS"
+fi
+```
+
+### 3d. Hook format
+
+```bash
+if [ -f "$plugin/hooks/hooks.json" ]; then
+  # Valid JSON
+  jq empty "$plugin/hooks/hooks.json"
+
+  # Uses CLAUDE_PLUGIN_ROOT, not CLAUDE_PROJECT_DIR
+  if jq -r '.. | strings' "$plugin/hooks/hooks.json" | grep -q 'CLAUDE_PROJECT_DIR'; then
+    echo "FAIL: hooks.json must use \${CLAUDE_PLUGIN_ROOT}, not CLAUDE_PROJECT_DIR"
+  fi
+
+  # All referenced .sh files exist and are executable
+  jq -r '.. | objects | .command // empty' "$plugin/hooks/hooks.json" | grep '\.sh' | while read cmd; do
+    script=$(echo "$cmd" | sed 's|.*hooks/||')
+    [ -f "$plugin/hooks/$script" ] || echo "FAIL: $script not found"
+    [ -x "$plugin/hooks/$script" ] || echo "FAIL: $script not executable"
+  done
+fi
+```
+
+### 3e. Agent frontmatter
+
+```bash
+for agent in "$plugin/agents/"*.md; do
+  [ -f "$agent" ] || continue
+  head -1 "$agent" | grep -q "^---" || echo "FAIL: $(basename $agent) missing frontmatter"
+done
+```
+
+### 3f. Skill structure
+
+```bash
+for skill_dir in "$plugin/skills/"*/; do
+  [ -d "$skill_dir" ] || continue
+  # Skip container dirs (have nested SKILL.md)
+  if find "$skill_dir" -mindepth 2 -name "SKILL.md" -print -quit 2>/dev/null | grep -q .; then
+    continue
+  fi
+  [ -f "$skill_dir/SKILL.md" ] || echo "FAIL: $(basename $skill_dir) missing SKILL.md"
+done
+```
+
+### 3g. Marketplace format (if marketplace-README.md exists)
+
+```bash
+if [ -f ".claude-plugin/marketplace.json" ] || [ -f "marketplace-README.md" ]; then
+  # marketplace.json must be at .claude-plugin/marketplace.json
+  # NOT at repo root
+fi
+```
+
+If `/publish validate` was the command, show results and STOP here.
+
+## Step 4: Bump Version
+
+Based on the argument:
+- `patch`: increment patch (1.0.0 → 1.0.1)
+- `minor`: increment minor (1.0.0 → 1.1.0)
+- `major`: increment major (1.0.0 → 2.0.0)
+- `1.2.3`: use exact version
+
+```bash
+NEW_VERSION="<computed>"
+echo "$NEW_VERSION" > VERSION
+```
+
+## Step 5: Commit and Tag
+
+```bash
+git add VERSION
+git commit -m "chore: bump version to $NEW_VERSION"
+# Push via PR if branch protection exists, direct push otherwise
+git tag "v$NEW_VERSION"
+git push --tags
+```
+
+The tag push triggers `publish-npm.yml` which:
+1. Derives version from git tag (not VERSION file)
+2. Compiles all plugins
+3. Publishes to npm
+4. Updates marketplace repo (`.claude-plugin/marketplace.json` + `plugins/`)
+
+## Step 6: Verify Publish
+
+Wait for the publish workflow to complete, then verify:
+
+```bash
+# Check workflow status
+gh run list --workflow publish-npm.yml --limit 1
+
+# Verify npm
+npm view @arthai/agents version
+
+# Verify marketplace
+gh api repos/ArthTech-AI/arthai-marketplace/contents/.claude-plugin/marketplace.json \
+  --jq '.content' | base64 -d | jq '.version'
+```
+
+If the publish workflow fails, show the error logs:
+```bash
+gh run view <run-id> --log-failed | tail -20
+```
+
+## Step 7: Test Plugin Install
+
+Tell the user to test in Claude Code:
+
+```
+/plugin marketplace update arthai-marketplace
+/plugin install prime@arthai-marketplace
+```
+
+## Common Failures and Fixes
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `author: expected object, received string` | `"author": "Name"` in plugin.json | Change to `"author": {"name": "Name"}` in compiler.sh |
+| `symlink cycle` | `cp -r` copies circular symlinks from install.sh artifacts | Use `rsync --no-links` in compiler.sh |
+| `marketplace.json not found` | File at repo root instead of `.claude-plugin/` | Move to `.claude-plugin/marketplace.json` |
+| `E403 cannot publish over previous version` | VERSION not bumped | Derive from git tag, not VERSION file |
+| `Plugin directory not found at path` | `source` path in marketplace.json is wrong | Must be `./plugins/<name>` relative to marketplace root |