skillpull 0.4.6 → 0.4.8

package/README.md

@@ -8,33 +8,51 @@ npx skillpull tianhaocui/ai-skills
 
 ## Install
 
+```bash
+npm i -g skillpull
+```
+
+Or clone and install manually:
+
 ```bash
 git clone https://github.com/tianhaocui/skillpull.git
 cd skillpull
 bash install.sh
 ```
 
-Or via npm:
+## Quick Start
 
 ```bash
-npm i -g skillpull
-```
+# Interactive setup: configure default repo and project scope
+skillpull init
 
-## Usage
+# Pull skills (uses registry if configured)
+skillpull
 
-```bash
-# GitHub shortname
+# Pull from a specific repo
 skillpull user/repo
 
 # Pull a specific skill
 skillpull user/repo my-skill
+```
 
-# List available skills in a repo
-skillpull list user/repo
+## Commands
 
-# Search GitHub for skill repos
-skillpull search coding-standards
-```
+| Command | Description |
+|---|---|
+| `skillpull init` | Interactive setup: default repo + project scope |
+| `skillpull <source> [skill]` | Pull skills from a Git repo |
+| `skillpull list [source]` | List available skills in a repo |
+| `skillpull search <keyword>` | Search GitHub for skill repos |
+| `skillpull update` | Update all installed skills to latest |
+| `skillpull push [target-repo]` | Push local skills back to a remote repo |
+| `skillpull installed` | Show locally installed skills |
+| `skillpull remove <skill>` | Remove an installed skill |
+| `skillpull registry <repo>` | Set or view default skill repo |
+| `skillpull alias add <name> <url>` | Save a repo shortcut |
+| `skillpull alias list` | List saved aliases |
+| `skillpull alias rm <name>` | Remove an alias |
+| `skillpull uninstall` | Remove skillpull from system |
 
 ## Source Formats
 
@@ -48,7 +66,7 @@ skillpull search coding-standards
 
 ## Targets
 
-By default, skills install to `.claude/skills/`. Use flags to target other tools:
+First run will show an interactive menu to select target tools. Use flags to skip the prompt:
 
 ```bash
 skillpull user/repo --claude    # .claude/skills/ (default)
@@ -58,28 +76,60 @@ skillpull user/repo --cursor    # .cursor/rules/ (auto-converts to .mdc)
 skillpull user/repo --all       # All of the above
 ```
 
-## Registry
+Global (user-level) install:
+
+```bash
+skillpull user/repo --global    # ~/.claude/skills/, ~/.codex/skills/, etc.
+```
+
+## Project Scope
+
+Skill repos can organize skills into common and project-specific folders:
+
+```
+skill-repo/
+  skills/                          # common, pulled for all projects
+    common-skill-a/SKILL.md
+    common-skill-b/SKILL.md
+  my-app/                          # project-specific
+    app-skill/SKILL.md
+  backend/                         # project-specific
+    api-skill/SKILL.md
+```
+
+The `skills/` folder at the repo root holds shared skills. Other folders are project-specific — only pulled when matching the configured project name.
 
-Set a default skill repo so you can pull by skill name alone:
+Configure a default project during `skillpull init`, or pass it per-command:
 
 ```bash
-# Set default registry
-skillpull registry tianhaocui/ai-skills
+# Uses default project from config
+skillpull
 
-# Now just use the skill name
-skillpull my-skill
+# Override for a specific pull
+skillpull user/repo --project my-app
 ```
 
-## Aliases
+Both `skills/` (common) and the project subfolder's skills are pulled together.
 
-Save frequently used repos as aliases:
+## Registry & Aliases
 
 ```bash
+# Set a default repo so you can pull by skill name alone
+skillpull registry tianhaocui/ai-skills
+skillpull my-skill              # pulls from registry
+
+# Save frequently used repos as aliases
 skillpull alias add work git@github.com:myorg/skills.git
 skillpull @work my-skill
+```
 
-skillpull alias list
-skillpull alias rm work
+## Push
+
+Push local skills back to a remote Git repo:
+
+```bash
+skillpull push user/repo
+skillpull push                  # uses registry if set
 ```
 
 ## Options
@@ -89,6 +139,7 @@ skillpull alias rm work
 | `--global, -g` | Install to user-level directory |
 | `--path <dir>` | Install to a custom directory |
 | `--branch <ref>` | Use a specific branch/tag/commit |
+| `--project <name>` | Include project-specific skills (defaults to `init` config) |
 | `--force, -f` | Overwrite existing skills |
 | `--dry-run` | Preview without making changes |
 | `--quiet, -q` | Suppress non-error output |
@@ -115,6 +166,20 @@ description: What this skill does
 Skill content here...
 ```
 
+## Config
+
+Config is stored at `~/.config/skillpull/config.json`:
+
+```json
+{
+  "aliases": {},
+  "registry": "https://github.com/user/repo",
+  "project": "my-app"
+}
+```
+
+Installed skills are tracked per-directory in `.skillpull.json` manifests.
+
 ## Requirements
 
 - macOS, Linux, or Windows (via [WSL](https://learn.microsoft.com/en-us/windows/wsl/) or [Git Bash](https://gitforwindows.org/))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillpull",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "description": "Sync AI agent skills from Git repositories to Claude, Codex, Kiro, and Cursor",
   "bin": {
     "skillpull": "./skillpull"

package/skillpull

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-VERSION="0.4.6"
+VERSION="0.4.8"
 MANIFEST_FILE=".skillpull.json"
 TMPDIR_PREFIX="skillpull"
 CONFIG_DIR="$HOME/.config/skillpull"
@@ -166,7 +166,11 @@ make_tmp() { _TMPDIR="$(mktemp -d "/tmp/${TMPDIR_PREFIX}.XXXXXX")"; }
 # ── Config helpers ──
 ensure_config() {
   mkdir -p "$CONFIG_DIR"
-  [[ -f "$CONFIG_FILE" ]] || echo '{"aliases":{},"registry":""}' > "$CONFIG_FILE"
+  [[ -f "$CONFIG_FILE" ]] || echo '{"aliases":{},"registry":"","project":""}' > "$CONFIG_FILE"
+  # Migrate: add "project" key if missing
+  if ! grep -q '"project"' "$CONFIG_FILE" 2>/dev/null; then
+    sedi 's/}$/,"project":""}/' "$CONFIG_FILE"
+  fi
 }
 
 read_config_key() {
@@ -246,6 +250,18 @@ set_registry() {
   info "Default registry set to: $url"
 }
 
+set_project() {
+  local name="$1"
+  ensure_config
+  local esc_name; esc_name="$(_json_escape "$name")"
+  sedi "s|\"project\":\"[^\"]*\"|\"project\":\"${esc_name}\"|" "$CONFIG_FILE"
+  if [[ -n "$name" ]]; then
+    info "Default project set to: $name"
+  else
+    info "Default project cleared"
+  fi
+}
+
 # ── URL resolution ──
 # Supports: full URL, user/repo shortname, @alias, bare skill name (from registry)
 resolve_repo_url() {
@@ -309,6 +325,31 @@ discover_skills() {
     -exec dirname {} \; 2>/dev/null | sort -u
 }
 
+# Scoped discovery: skills/ folder (common) + optional project-specific skills
+discover_skills_scoped() {
+  local dir="$1" project="${2:-}"
+  local results=()
+
+  # Common skills: $dir/skills/*/SKILL.md
+  local d
+  for d in "$dir/skills"/*/SKILL.md; do
+    [[ -f "$d" ]] || continue
+    local skill_dir; skill_dir="$(dirname "$d")"
+    results+=("$skill_dir")
+  done
+
+  # Project-specific skills: $dir/$project/*/SKILL.md
+  if [[ -n "$project" ]]; then
+    for d in "$dir/$project"/*/SKILL.md; do
+      [[ -f "$d" ]] || continue
+      local skill_dir; skill_dir="$(dirname "$d")"
+      results+=("$skill_dir")
+    done
+  fi
+
+  printf '%s\n' "${results[@]}" 2>/dev/null | sort -u
+}
+
 # ── SKILL.md → .mdc conversion (for Cursor) ──
 convert_skill_to_mdc() {
   local skill_md="$1" output_file="$2"
@@ -452,7 +493,7 @@ get_branch() {
 # ── Commands ──
 
 cmd_pull() {
-  local repo_url="$1" skill_filter="${2:-}" target_dir="$3" force="${4:-0}" dry_run="${5:-0}" agent="${6:-claude}"
+  local repo_url="$1" skill_filter="${2:-}" target_dir="$3" force="${4:-0}" dry_run="${5:-0}" agent="${6:-claude}" project="${7:-}"
   local fmt; fmt="$(agent_format "$agent")"
   make_tmp
   local tmpdir="$_TMPDIR"
@@ -464,9 +505,17 @@ cmd_pull() {
   local branch; branch="$(get_branch "$tmpdir")"
   local skills=()
 
-  while IFS= read -r d; do
-    [[ -n "$d" ]] && skills+=("$d")
-  done < <(discover_skills "$tmpdir")
+  # Use scoped discovery if project is set, otherwise discover all
+  if [[ -n "$project" ]]; then
+    while IFS= read -r d; do
+      [[ -n "$d" ]] && skills+=("$d")
+    done < <(discover_skills_scoped "$tmpdir" "$project")
+    [[ -n "$project" ]] && dim "Project scope: $project"
+  else
+    while IFS= read -r d; do
+      [[ -n "$d" ]] && skills+=("$d")
+    done < <(discover_skills "$tmpdir")
+  fi
 
   if [[ ${#skills[@]} -eq 0 ]]; then
     err "No skills found in repository"
@@ -551,7 +600,7 @@ cmd_pull() {
 }
 
 cmd_list() {
-  local repo_url="$1"
+  local repo_url="$1" project="${2:-}"
   make_tmp
   local tmpdir="$_TMPDIR"
 
@@ -559,9 +608,16 @@ cmd_list() {
   clone_repo "$repo_url" "${BRANCH:-}" "$tmpdir" || return 1
 
   local skills=()
-  while IFS= read -r d; do
-    [[ -n "$d" ]] && skills+=("$d")
-  done < <(discover_skills "$tmpdir")
+  if [[ -n "$project" ]]; then
+    while IFS= read -r d; do
+      [[ -n "$d" ]] && skills+=("$d")
+    done < <(discover_skills_scoped "$tmpdir" "$project")
+    dim "Project scope: $project"
+  else
+    while IFS= read -r d; do
+      [[ -n "$d" ]] && skills+=("$d")
+    done < <(discover_skills "$tmpdir")
+  fi
 
   if [[ ${#skills[@]} -eq 0 ]]; then
     err "No skills found in repository"
@@ -923,6 +979,33 @@ cmd_init() {
     set_registry "$resolved"
   fi
 
+  # ── Project scope ──
+  local current_project; current_project="$(read_config_key "project")"
+  echo ""
+  printf "  ${CYAN}Project scope${RESET} ${DIM}(optional)${RESET}\n"
+  printf "  ${DIM}If your skill repo has project-specific subfolders, set a default here.${RESET}\n"
+  printf "  ${DIM}Skills from both root level and the project subfolder will be pulled.${RESET}\n\n"
+
+  if [[ -n "$current_project" ]]; then
+    printf "  Current: ${GREEN}%s${RESET}\n\n" "$current_project"
+    printf "  Project name (Enter to keep, 'none' to clear): "
+  else
+    printf "  Project name (Enter to skip): "
+  fi
+
+  read -r project_input
+  project_input="$(echo "$project_input" | tr -d '[:cntrl:]' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
+
+  if [[ -z "$project_input" ]]; then
+    if [[ -n "$current_project" ]]; then
+      dim "Keeping current project: $current_project"
+    fi
+  elif [[ "$project_input" == "none" ]]; then
+    set_project ""
+  else
+    set_project "$project_input"
+  fi
+
   echo ""
   printf "  ${CYAN}What's next:${RESET}\n"
   printf "    skillpull list              List available skills\n"
@@ -1034,6 +1117,8 @@ OPTIONS:
   --global, -g          Install to user-level directory
   --path <dir>          Install to a custom directory
   --branch <ref>        Use a specific branch/tag/commit
+  --project <name>      Include project-specific skills from <name>/ subfolder
+                        (defaults to value set in 'skillpull init')
   --force, -f           Overwrite existing skills
   --dry-run             Preview without making changes
   --quiet, -q           Suppress non-error output
@@ -1041,7 +1126,7 @@ OPTIONS:
   --version             Show version
 
 EXAMPLES:
-  skillpull init                                    # Setup default skill repo
+  skillpull init                                    # Setup default skill repo & project
   skillpull tianhaocui/ai-skills                    # GitHub shortname
   skillpull @work plan-first-development --global   # From alias
   skillpull search coding-standards                 # Search GitHub
@@ -1051,13 +1136,14 @@ EXAMPLES:
   skillpull tianhaocui/ai-skills --cursor           # Convert to .mdc
   skillpull update                                  # Update all installed skills
   skillpull push tianhaocui/ai-skills               # Push local skills to remote
+  skillpull user/repo --project my-app              # Common + project-specific skills
 HELP
 }
 
 # ── Argument parsing & dispatch ──
 main() {
   local cmd="" repo_url="" skill_name="" custom_path=""
-  local force=0 dry_run=0 is_global=0 use_all=0 agent_explicit=0
+  local force=0 dry_run=0 is_global=0 use_all=0 agent_explicit=0 project_name=""
   local agents=()
   local alias_args=()
   QUIET=0; BRANCH=""
@@ -1092,6 +1178,7 @@ main() {
       --global|-g)  is_global=1; shift ;;
       --path)       [[ $# -lt 2 ]] && { err "--path requires a directory"; exit 1; }; custom_path="$2"; shift 2 ;;
       --branch)     [[ $# -lt 2 ]] && { err "--branch requires a ref"; exit 1; }; BRANCH="$2"; shift 2 ;;
+      --project)    [[ $# -lt 2 ]] && { err "--project requires a name"; exit 1; }; project_name="$2"; shift 2 ;;
       --force|-f)   force=1; shift ;;
       --dry-run)    dry_run=1; shift ;;
       --quiet|-q)   QUIET=1; shift ;;
@@ -1140,7 +1227,7 @@ main() {
   if [[ "$use_all" == "1" ]]; then
     agents=("claude" "codex" "kiro" "cursor")
   elif [[ ${#agents[@]} -eq 0 ]]; then
-    if [[ "$agent_explicit" == "0" && -t 0 && "$cmd" != "installed" && "$cmd" != "update" ]]; then
+    if [[ "$agent_explicit" == "0" && -t 0 && ( "$cmd" == "pull" || "$cmd" == "" || "$cmd" == "remove" || "$cmd" == "push" ) ]]; then
       # Interactive terminal, no agent flag -> let user choose
       select_menu "Install to which tools?" "claude (.claude/skills)" "codex (.codex/skills)" "kiro (.kiro/skills)" "cursor (.cursor/rules)"
       if [[ ${#SELECTED_ITEMS[@]} -eq 0 ]]; then
@@ -1158,6 +1245,10 @@ main() {
 
   case "${cmd:-}" in
     pull|"")
+      # Fall back to configured project if --project not specified
+      if [[ -z "$project_name" ]]; then
+        project_name="$(read_config_key "project")"
+      fi
       if [[ -z "$repo_url" ]]; then
         # No source given, try registry
         local reg; reg="$(read_config_key "registry")"
@@ -1177,10 +1268,14 @@ main() {
         local target_dir
         target_dir="$(resolve_target_dir "$agent" "$is_global" "$custom_path")" || continue
         dim "Target: $agent -> $target_dir"
-        cmd_pull "$resolved" "$skill_name" "$target_dir" "$force" "$dry_run" "$agent"
+        cmd_pull "$resolved" "$skill_name" "$target_dir" "$force" "$dry_run" "$agent" "$project_name"
       done
       ;;
     list)
+      # Fall back to configured project if --project not specified
+      if [[ -z "$project_name" ]]; then
+        project_name="$(read_config_key "project")"
+      fi
       if [[ -z "$repo_url" ]]; then
         local reg; reg="$(read_config_key "registry")"
         if [[ -z "$reg" ]]; then
@@ -1191,7 +1286,7 @@ main() {
         repo_url="$reg"
       fi
       local resolved; resolved="$(resolve_repo_url "$repo_url")" || exit 1
-      cmd_list "$resolved"
+      cmd_list "$resolved" "$project_name"
       ;;
     search)
       cmd_search "${skill_name:-}"