skillpull 0.4.7 → 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.7",
+  "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.7"
+VERSION="0.4.8"
 MANIFEST_FILE=".skillpull.json"
 TMPDIR_PREFIX="skillpull"
 CONFIG_DIR="$HOME/.config/skillpull"
@@ -325,14 +325,14 @@ discover_skills() {
     -exec dirname {} \; 2>/dev/null | sort -u
 }
 
-# Scoped discovery: root-level skills + optional project-specific skills
+# Scoped discovery: skills/ folder (common) + optional project-specific skills
 discover_skills_scoped() {
   local dir="$1" project="${2:-}"
   local results=()
 
-  # Root-level skills: $dir/*/SKILL.md (direct children only)
+  # Common skills: $dir/skills/*/SKILL.md
   local d
-  for d in "$dir"/*/SKILL.md; do
+  for d in "$dir/skills"/*/SKILL.md; do
     [[ -f "$d" ]] || continue
     local skill_dir; skill_dir="$(dirname "$d")"
     results+=("$skill_dir")