agentic-skill-mill 1.0.3 → 1.0.4

package/install-local.sh

@@ -0,0 +1,265 @@
+#!/usr/bin/env bash
+# install-local.sh -- Local project setup: build companion CLI + install skills for AI coding tools
+# Run from the project root: bash install-local.sh [--claude] [--cursor] [--windsurf] [--opencode] [--codex] [--all]
+# No flags = auto-detect installed tools
+
+set -e
+
+# ===========================================================================
+# CONFIGURE: Change these values for your project
+# ===========================================================================
+
+PROJECT_NAME="agentic-skill-mill"        # Used in log messages
+CLI_BIN_NAME="skillmill"                 # The bin name from package.json
+MANAGED_MARKER="managed_by: agentic-skill-mill"  # Must match compile.mjs MANAGED_BY
+SKILLS=("agentic-skill-mill")            # All skill names from manifest.json
+
+# ===========================================================================
+# End configuration
+# ===========================================================================
+
+SKILL_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# --- Target directories ---
+CLAUDE_SKILLS_DIR="$HOME/.claude/skills"
+CURSOR_RULES_DIR="$HOME/.cursor/rules"
+CURSOR_SKILLS_DIR="$HOME/.cursor/skills"
+WINDSURF_RULES_DIR="$HOME/.windsurf/rules"
+WINDSURF_SKILLS_DIR="$HOME/.codeium/windsurf/skills"
+OPENCODE_AGENTS_DIR="$HOME/.config/opencode/agents"
+CODEX_HOME_DIR="${CODEX_HOME:-$HOME/.codex}"
+CODEX_SKILLS_DIR="$CODEX_HOME_DIR/skills"
+
+# --- Stale file cleanup (marker-based) ---
+
+cleanup_managed() {
+  local dir="$1"
+  [[ -d "$dir" ]] || return 0
+  grep -rl "$MANAGED_MARKER" "$dir" 2>/dev/null | while read -r f; do
+    rm -f "$f"
+    local parent; parent="$(dirname "$f")"
+    [[ "$parent" != "$dir" ]] && rmdir "$parent" 2>/dev/null || true
+    echo "    Removed: $f"
+  done
+}
+
+# --- Install functions (copy from compiled/ output) ---
+
+COMPILED_DIR="$SKILL_DIR/compiled"
+
+install_claude() {
+  local skill_name="$1"
+  local src="$COMPILED_DIR/claude/${skill_name}/SKILL.md"
+  local dest_dir="$CLAUDE_SKILLS_DIR/${skill_name}"
+  mkdir -p "$dest_dir"
+  cp "$src" "$dest_dir/SKILL.md"
+  echo "    Claude:   $dest_dir/SKILL.md"
+}
+
+install_cursor() {
+  local skill_name="$1"
+  local src="$COMPILED_DIR/cursor/rules/${skill_name}.mdc"
+  mkdir -p "$CURSOR_RULES_DIR"
+  cp "$src" "$CURSOR_RULES_DIR/${skill_name}.mdc"
+  echo "    Cursor (rule):  $CURSOR_RULES_DIR/${skill_name}.mdc"
+  local src2="$COMPILED_DIR/cursor/skills/${skill_name}/SKILL.md"
+  local dest_dir="$CURSOR_SKILLS_DIR/${skill_name}"
+  mkdir -p "$dest_dir"
+  cp "$src2" "$dest_dir/SKILL.md"
+  echo "    Cursor (skill): $dest_dir/SKILL.md"
+}
+
+install_windsurf() {
+  local skill_name="$1"
+  local src="$COMPILED_DIR/windsurf/rules/${skill_name}.md"
+  mkdir -p "$WINDSURF_RULES_DIR"
+  cp "$src" "$WINDSURF_RULES_DIR/${skill_name}.md"
+  echo "    Windsurf (rule):  $WINDSURF_RULES_DIR/${skill_name}.md"
+  local src2="$COMPILED_DIR/windsurf/skills/${skill_name}/SKILL.md"
+  local dest_dir="$WINDSURF_SKILLS_DIR/${skill_name}"
+  mkdir -p "$dest_dir"
+  cp "$src2" "$dest_dir/SKILL.md"
+  echo "    Windsurf (skill): $dest_dir/SKILL.md"
+}
+
+install_opencode() {
+  local skill_name="$1"
+  local src="$COMPILED_DIR/opencode/${skill_name}.md"
+  mkdir -p "$OPENCODE_AGENTS_DIR"
+  cp "$src" "$OPENCODE_AGENTS_DIR/${skill_name}.md"
+  echo "    OpenCode: $OPENCODE_AGENTS_DIR/${skill_name}.md"
+}
+
+install_codex() {
+  local skill_name="$1"
+  local src="$COMPILED_DIR/codex/${skill_name}/SKILL.md"
+  local dest_dir="$CODEX_SKILLS_DIR/${skill_name}"
+  mkdir -p "$dest_dir"
+  cp "$src" "$dest_dir/SKILL.md"
+  echo "    Codex:    $dest_dir/SKILL.md"
+}
+
+# --- Uninstall ---
+
+uninstall_claude()   { for skill in "${SKILLS[@]}"; do rm -rf "$CLAUDE_SKILLS_DIR/$skill"; done; echo "    Claude:   removed"; }
+uninstall_cursor()   { for skill in "${SKILLS[@]}"; do rm -f "$CURSOR_RULES_DIR/${skill}.mdc"; rm -rf "$CURSOR_SKILLS_DIR/$skill"; done; echo "    Cursor:   removed"; }
+uninstall_windsurf() { for skill in "${SKILLS[@]}"; do rm -f "$WINDSURF_RULES_DIR/${skill}.md"; rm -rf "$WINDSURF_SKILLS_DIR/$skill"; done; echo "    Windsurf: removed"; }
+uninstall_opencode() { for skill in "${SKILLS[@]}"; do rm -f "$OPENCODE_AGENTS_DIR/${skill}.md"; done; echo "    OpenCode: removed"; }
+uninstall_codex()    { for skill in "${SKILLS[@]}"; do rm -rf "$CODEX_SKILLS_DIR/$skill"; done; echo "    Codex:    removed"; }
+
+# --- Auto-detection ---
+
+detect_editors() {
+  local detected=()
+  [[ -d "$HOME/.claude" ]] && detected+=("claude")
+  [[ -d "$HOME/.cursor" ]] && detected+=("cursor")
+  [[ -d "$HOME/.windsurf" || -d "$HOME/.codeium/windsurf" ]] && detected+=("windsurf")
+  [[ -d "$HOME/.config/opencode" || -d "$HOME/.opencode" ]] && detected+=("opencode")
+  [[ -n "${CODEX_HOME:-}" || -d "$CODEX_HOME_DIR" ]] && detected+=("codex")
+  echo "${detected[@]}"
+}
+
+# --- CLI parsing ---
+
+TARGETS=()
+DO_BUILD=true
+DO_UNINSTALL=false
+DO_COMPILE_ONLY=false
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --claude)    TARGETS+=("claude"); shift ;;
+    --cursor)    TARGETS+=("cursor"); shift ;;
+    --windsurf)  TARGETS+=("windsurf"); shift ;;
+    --opencode)  TARGETS+=("opencode"); shift ;;
+    --codex)     TARGETS+=("codex"); shift ;;
+    --all)       TARGETS=("claude" "cursor" "windsurf" "opencode" "codex"); shift ;;
+    --skills-only) DO_BUILD=false; shift ;;
+    --uninstall) DO_UNINSTALL=true; shift ;;
+    --compile-only) DO_COMPILE_ONLY=true; shift ;;
+    --help|-h)
+      echo "Usage: bash install-local.sh [options]"
+      echo ""
+      echo "Options:"
+      echo "  --claude        Install skills for Claude Code"
+      echo "  --cursor        Install skills for Cursor"
+      echo "  --windsurf      Install skills for Windsurf"
+      echo "  --opencode      Install skills for OpenCode"
+      echo "  --codex         Install skills for Codex"
+      echo "  --all           Install for all five tools"
+      echo "  --skills-only   Skip npm install/build/link (just copy skills)"
+      echo "  --uninstall     Remove installed skills from target tools"
+      echo "  --compile-only  Generate compiled/ output directory (no install)"
+      echo "  -h, --help      Show this help"
+      echo ""
+      echo "No flags = auto-detect installed tools."
+      exit 0
+      ;;
+    *)
+      echo "Unknown option: $1"
+      echo "Run: bash install-local.sh --help"
+      exit 1
+      ;;
+  esac
+done
+
+# --- Compile-only path ---
+
+if [[ "$DO_COMPILE_ONLY" == true ]]; then
+  echo "==> Delegating to compile.mjs..."
+  node "$SKILL_DIR/skill/build/compile.mjs"
+  exit $?
+fi
+
+# Auto-detect if no targets specified
+if [[ ${#TARGETS[@]} -eq 0 ]]; then
+  read -ra TARGETS <<< "$(detect_editors)"
+fi
+
+if [[ ${#TARGETS[@]} -eq 0 ]]; then
+  echo "ERROR: No supported tools detected. Use --claude, --cursor, --windsurf, --opencode, or --codex."
+  exit 1
+fi
+
+# --- Uninstall path ---
+
+if [[ "$DO_UNINSTALL" == true ]]; then
+  echo "==> Uninstalling $PROJECT_NAME"
+  echo "    Targets: ${TARGETS[*]}"
+  echo ""
+  for target in "${TARGETS[@]}"; do
+    "uninstall_${target}"
+  done
+
+  echo "--> Removing $CLI_BIN_NAME CLI..."
+  npm unlink "$PROJECT_NAME" 2>/dev/null || true
+  hash -r 2>/dev/null || true
+  if command -v "$CLI_BIN_NAME" &>/dev/null; then
+    echo "    WARNING: $CLI_BIN_NAME still in PATH at $(which "$CLI_BIN_NAME")"
+  else
+    echo "    $CLI_BIN_NAME removed"
+  fi
+
+  echo ""
+  echo "==> Done. Skills and CLI removed."
+  exit 0
+fi
+
+# --- Install path ---
+
+echo "==> $PROJECT_NAME setup"
+echo "    Project: $SKILL_DIR"
+echo "    Targets: ${TARGETS[*]}"
+echo ""
+
+if [[ "$DO_BUILD" == true ]]; then
+  echo "--> Installing dependencies..."
+  npm install
+
+  echo "--> Cleaning previous build..."
+  rm -rf "$SKILL_DIR/dist"
+
+  echo "--> Building TypeScript..."
+  npm run build
+  chmod +x "$SKILL_DIR/dist/cli/index.js"
+
+  echo "--> Compiling skills..."
+  npm run compile
+
+  echo "--> Installing $CLI_BIN_NAME CLI globally..."
+  npm link
+
+  NPM_BIN="$(npm prefix -g)/bin"
+  if [[ -x "$NPM_BIN/$CLI_BIN_NAME" ]]; then
+    echo "    $CLI_BIN_NAME: $NPM_BIN/$CLI_BIN_NAME"
+    echo "    version:  $("$NPM_BIN/$CLI_BIN_NAME" --version 2>/dev/null || echo 'unknown')"
+  else
+    echo "    WARNING: $CLI_BIN_NAME not found in $NPM_BIN after npm link."
+    echo "    Try running: npm link"
+  fi
+fi
+
+echo "--> Cleaning stale $PROJECT_NAME files..."
+for target in "${TARGETS[@]}"; do
+  case "$target" in
+    claude)   cleanup_managed "$CLAUDE_SKILLS_DIR" ;;
+    cursor)   cleanup_managed "$CURSOR_RULES_DIR"; cleanup_managed "$CURSOR_SKILLS_DIR" ;;
+    windsurf) cleanup_managed "$WINDSURF_RULES_DIR"; cleanup_managed "$WINDSURF_SKILLS_DIR" ;;
+    opencode) cleanup_managed "$OPENCODE_AGENTS_DIR" ;;
+    codex)    cleanup_managed "$CODEX_SKILLS_DIR" ;;
+  esac
+done
+
+echo "--> Installing skills..."
+for skill in "${SKILLS[@]}"; do
+  echo "  ${skill}:"
+  for target in "${TARGETS[@]}"; do
+    "install_${target}" "$skill"
+  done
+done
+
+echo ""
+echo "==> Done."
+echo ""
+echo "Skills installed for: ${TARGETS[*]}"
+echo "CLI available as: $CLI_BIN_NAME"

package/install.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# install.sh -- Remote-friendly bootstrap installer (for curl|bash use)
+# Installs the npm package globally, then runs install-local.sh in skills-only mode.
+
+set -euo pipefail
+
+PACKAGE_NAME="${SKILLMILL_PACKAGE_NAME:-agentic-skill-mill}"
+PACKAGE_VERSION="${SKILLMILL_PACKAGE_VERSION:-latest}"
+
+if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
+  echo "Usage: bash install.sh [tool flags]"
+  echo ""
+  echo "This script installs ${PACKAGE_NAME}@${PACKAGE_VERSION} globally and then"
+  echo "runs install-local.sh --skills-only with the flags you provide."
+  echo ""
+  echo "Examples:"
+  echo "  bash install.sh --all"
+  echo "  bash install.sh --cursor"
+  echo ""
+  echo "Environment overrides:"
+  echo "  SKILLMILL_PACKAGE_NAME    Package to install (default: agentic-skill-mill)"
+  echo "  SKILLMILL_PACKAGE_VERSION Version tag (default: latest)"
+  exit 0
+fi
+
+echo "==> Installing utility library: ${PACKAGE_NAME}@${PACKAGE_VERSION}"
+npm install -g "${PACKAGE_NAME}@${PACKAGE_VERSION}"
+
+GLOBAL_NODE_MODULES="$(npm root -g)"
+PACKAGE_DIR="${GLOBAL_NODE_MODULES}/${PACKAGE_NAME}"
+LOCAL_INSTALLER="${PACKAGE_DIR}/install-local.sh"
+
+if [[ ! -f "$LOCAL_INSTALLER" ]]; then
+  echo "ERROR: Could not find install-local.sh at: $LOCAL_INSTALLER"
+  echo "Check the package 'files' list to ensure install-local.sh is published."
+  exit 1
+fi
+
+echo "==> Installing skills via local installer (skills-only mode)"
+bash "$LOCAL_INSTALLER" --skills-only "$@"
+
+echo ""
+echo "==> Done."
+echo "Utility and skills installed."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-skill-mill",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Forge and refine agent skill projects -- fragment-composed skills compiled to 7 IDE targets with a companion CLI",
   "type": "module",
   "bin": {
@@ -16,8 +16,11 @@
   },
   "files": [
     "dist",
+    "compiled",
     "skill",
-    "README.md"
+    "README.md",
+    "install.sh",
+    "install-local.sh"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
@@ -26,10 +29,10 @@
     "test:coverage": "vitest run --coverage",
     "lint": "eslint src",
     "typecheck": "tsc --noEmit",
-    "setup": "bash install.sh",
-    "setup:all": "bash install.sh --all",
-    "install-skills": "bash install.sh --skills-only",
-    "uninstall-skills": "bash install.sh --uninstall",
+    "setup": "bash install-local.sh",
+    "setup:all": "bash install-local.sh --all",
+    "install-skills": "bash install-local.sh --skills-only",
+    "uninstall-skills": "bash install-local.sh --uninstall",
     "compile": "node skill/build/compile.mjs",
     "compile:validate": "node skill/build/compile.mjs --validate",
     "compile:watch": "node skill/build/compile.mjs --watch"

package/skill/fragments/meta/architecture-overview.md

@@ -25,7 +25,7 @@ Skills (what to do)          CLI Companion (tools to do it with)
 - `src/errors/types.ts` — Typed error hierarchy (AppError, NotFoundError, etc.)
 - `src/cache/cache-manager.ts` — Two-tier cache (memory + disk) with TTL
 
-**The installer** (`install.sh`) builds the CLI, compiles skills, and copies compiled outputs to IDE-specific directories (~/.claude/skills, ~/.cursor/rules, etc.) with marker-based stale file cleanup. The installer uses `set -e` for fail-fast behavior. Any function that uses an early-exit guard (`[[ -d ... ]] || return`, `[[ -z ... ]] && return`) **must** use `return 0`, never bare `return`. Bare `return` inherits the exit code of the last command, which for a failed conditional test is 1 -- and `set -e` treats that as a script-terminating failure with no error message.
+**The local installer** (`install-local.sh`) builds the CLI, compiles skills, and copies compiled outputs to IDE-specific directories (~/.claude/skills, ~/.cursor/rules, etc.) with marker-based stale file cleanup. The bootstrap installer (`install.sh`) is remote-friendly and installs the npm utility first, then delegates to `install-local.sh --skills-only`. Local installer functions use `set -e` for fail-fast behavior. Any function that uses an early-exit guard (`[[ -d ... ]] || return`, `[[ -z ... ]] && return`) **must** use `return 0`, never bare `return`. Bare `return` inherits the exit code of the last command, which for a failed conditional test is 1 -- and `set -e` treats that as a script-terminating failure with no error message.
 
 ### Key files to modify when augmenting a project
 
@@ -33,5 +33,5 @@ Skills (what to do)          CLI Companion (tools to do it with)
 |------|---------|
 | Add a CLI command | `src/core/<name>.ts`, `src/cli/commands/<name>.ts`, `src/cli/index.ts`, `src/index.ts` |
 | Add a fragment | `skill/fragments/<category>/<name>.md`, `skill/build/manifest.json`, skill source |
-| Add a skill | `skill/skills/<name>/<name>.md`, `skill/build/manifest.json`, `install.sh` SKILLS array |
+| Add a skill | `skill/skills/<name>/<name>.md`, `skill/build/manifest.json`, `install-local.sh` SKILLS array |
 | Rename the project | See the rename workflow |

package/skill/fragments/meta/rename-workflow.md

@@ -22,7 +22,7 @@ When the project, skill, or CLI needs a new name, update all touchpoints in one
 
 4. **Compiler marker** (`skill/build/compile.mjs`) -- update the `MANAGED_BY` constant
 
-5. **Installer** (`install.sh`) -- update `PROJECT_NAME`, `CLI_BIN_NAME`, `MANAGED_MARKER`, `SKILLS` array
+5. **Installer** (`install-local.sh`) -- update `PROJECT_NAME`, `CLI_BIN_NAME`, `MANAGED_MARKER`, `SKILLS` array
 
 6. **Package metadata** (`package.json`) -- update `name` and `bin` key
 

package/skill/skills/agentic-skill-mill/agentic-skill-mill.md

@@ -5,7 +5,7 @@ description: "Build, augment, and maintain skill projects that follow the skill-
 
 # Agentic Skill Mill
 
-Forge and refine skill projects that follow the skill-system-template architecture: fragment-composed skills compiled to multiple IDE targets, paired with a TypeScript companion CLI (`skillmill`) that provides structured commands for agents and humans.
+Forge and refine skill projects that follow the skill-system-template architecture: fragment-composed skills compiled to multiple IDE targets, paired with a TypeScript companion CLI (`skillmill`) that provides structured commands for agents and humans. Prefer `npx --yes agentic-skill-mill@latest <command>` when the utility is not globally installed.
 
 ---
 
@@ -83,7 +83,7 @@ Direct content or more includes.
 Then register it:
 
 1. Add the skill entry to `skill/build/manifest.json` with its source path and fragment dependencies
-2. Add the skill name to the `SKILLS` array in `install.sh`
+2. Add the skill name to the `SKILLS` array in `install-local.sh`
 3. Compile: `npm run compile`
 
 ### Step 8: If Renaming the Project
@@ -98,15 +98,15 @@ After any change, run the full verification sequence:
 npm run build              # TypeScript CLI compiles cleanly
 npm run compile            # Skills compile to all 7 IDE targets
 npm run compile:validate   # Cross-validates manifest vs source includes
-node dist/cli/index.js --help  # CLI shows expected commands
+npx --yes agentic-skill-mill@latest --help  # CLI command surface works via npx
 ```
 
 If adding a new CLI command, also verify it runs:
 
 ```bash
-node dist/cli/index.js <command> --help     # Options are correct
-node dist/cli/index.js <command> <args>     # Human output works
-node dist/cli/index.js <command> --json     # JSON output works
+npx --yes agentic-skill-mill@latest <command> --help  # Options are correct
+npx --yes agentic-skill-mill@latest <command> <args>  # Human output works
+npx --yes agentic-skill-mill@latest <command> --json  # JSON output works
 ```
 
 ### Step 10: Commit
@@ -130,4 +130,4 @@ The commit body should list every file category changed (core modules, CLI wrapp
 - **Stale compiled outputs.** Always recompile after changing skills or fragments. Run `npm run compile:validate` to detect staleness.
 - **Partial renames.** When renaming, update every touchpoint in one pass (see rename workflow). A grep sweep with zero results confirms completeness.
 - **Missing --json support.** Every CLI command must support `--json` for structured agent consumption. Agents cannot parse chalk-colored terminal output.
-- **Bare `return` in `set -e` scripts.** In `install.sh`, never write `[[ condition ]] || return` or `grep ... || return`. Bare `return` inherits the exit code of the failed test (1), which `set -e` treats as fatal -- killing the script silently. Always use `return 0` for early-exit guards: `[[ -d "$dir" ]] || return 0`, `[[ -z "$var" ]] && return 0`.
+- **Bare `return` in `set -e` scripts.** In `install-local.sh`, never write `[[ condition ]] || return` or `grep ... || return`. Bare `return` inherits the exit code of the failed test (1), which `set -e` treats as fatal -- killing the script silently. Always use `return 0` for early-exit guards: `[[ -d "$dir" ]] || return 0`, `[[ -z "$var" ]] && return 0`.