@mcowger/skillfu 0.1.0

package/README.md

@@ -0,0 +1,221 @@
+# skillfu
+
+A minimal CLI for installing agent skills. Symlink-only, lockfile-driven.
+
+**skillfu** gives your agents new capabilities instantly — _"I know kung fu."_
+
+It's a focused replacement for the Vercel `skills` CLI — it does one thing well: install, track, and update skills via symlinks with a lockfile as the source of truth.
+
+## Install
+
+```bash
+# npm
+npm install -g @mcowger/skillfu
+
+# From source
+git clone <repo-url> skillfu && cd skillfu
+bun install
+bun run build
+```
+
+## Commands
+
+### `skillfu add <source>`
+
+Install skills from a GitHub repo or local path.
+
+```bash
+# Install all skills from a repo (global)
+skillfu add vercel-labs/agent-skills
+
+# Install specific skills
+skillfu add vercel-labs/agent-skills --skill frontend-design --skill skill-creator
+
+# Install to project directory (local scope)
+skillfu add vercel-labs/agent-skills --skill frontend-design -l
+
+# Install from a local path
+skillfu add ./my-skills
+
+# Install from a specific branch
+skillfu add vercel-labs/agent-skills --ref develop --skill frontend-design
+
+# Shorthand: @skill-name filter
+skillfu add vercel-labs/agent-skills@frontend-design
+
+# Shorthand: #branch reference
+skillfu add vercel-labs/agent-skills#develop
+```
+
+| Option | Description |
+|---|---|
+| `-s, --skill <name>` | Install specific skill(s) by name. Repeatable. |
+| `-l, --local` | Install to project directory (`.agents/skills/`) |
+| `-y, --yes` | Skip confirmation prompts |
+| `--ref <branch>` | Git branch or tag to install from |
+
+### `skillfu remove <skill-name>...`
+
+Remove installed skills.
+
+```bash
+skillfu remove frontend-design
+skillfu remove frontend-design skill-creator
+skillfu remove frontend-design -l    # from project scope
+skillfu remove frontend-design -y    # skip confirmation
+```
+
+| Option | Description |
+|---|---|
+| `-l, --local` | Remove from project scope |
+| `-y, --yes` | Skip confirmation prompts |
+
+### `skillfu install`
+
+Ensure installed skills match the lockfile. Idempotent — safe to run repeatedly (like `npm ci`).
+
+```bash
+skillfu install       # restore global skills from lockfile
+skillfu install -l    # restore project skills from lockfile
+```
+
+| Option | Description |
+|---|---|
+| `-l, --local` | Install from project lockfile |
+
+This is the primary command for:
+- Setting up a new machine after cloning a repo (with `.agents/skills.lock` committed)
+- Recovering from accidentally deleted symlinks
+- CI/CD environments
+- Removing orphaned skills not tracked in the lockfile
+
+### `skillfu update`
+
+Check for and install updated versions of skills.
+
+```bash
+skillfu update                          # update all global skills
+skillfu update -l                       # update all project skills
+skillfu update --skill frontend-design   # update a specific skill
+```
+
+| Option | Description |
+|---|---|
+| `-l, --local` | Update project-scoped skills |
+| `-s, --skill <name>` | Update only specific skill(s) |
+| `-y, --yes` | Skip confirmation prompts |
+
+Update detection uses the [skills.sh API](https://skills.sh/docs/api) for hash comparison, falling back to the GitHub Trees API when unavailable. Local path skills cannot be updated remotely.
+
+### `skillfu completions <shell>`
+
+Output shell completion script.
+
+```bash
+# bash
+skillfu completions bash > ~/.local/share/bash-completion/completions/skillfu
+
+# zsh
+skillfu completions zsh > ~/.zfunc/_skillfu
+
+# fish
+skillfu completions fish > ~/.config/fish/completions/skillfu.fish
+```
+
+## Storage
+
+### Global scope (default)
+
+```
+~/.config/skillfu/
+├── skills.lock                                 # Lockfile
+└── skills/                                      # Canonical skill files
+    └── frontend-design/
+        └── SKILL.md
+
+~/.agents/skills/                                # Symlinks (where agents look)
+└── frontend-design → ~/.config/skillfu/skills/frontend-design/
+```
+
+### Local scope (`-l` flag)
+
+```
+<project>/
+├── .agents/
+│   ├── skills.lock                              # Project lockfile (commit this!)
+│   └── skills/                                  # Skill files (no symlinks needed)
+│       └── frontend-design/
+│           └── SKILL.md
+```
+
+Any agent that reads from `~/.agents/skills/` (global) or `.agents/skills/` (local) picks up installed skills automatically — no agent-specific configuration needed.
+
+## Source Formats
+
+| Format | Example |
+|---|---|
+| GitHub shorthand | `vercel-labs/agent-skills` |
+| Shorthand with skill filter | `vercel-labs/agent-skills@frontend-design` |
+| Shorthand with branch | `vercel-labs/agent-skills#develop` |
+| Shorthand with branch + skill | `vercel-labs/agent-skills#develop@frontend-design` |
+| Full GitHub URL | `https://github.com/vercel-labs/agent-skills` |
+| GitHub URL with branch/path | `https://github.com/vercel-labs/agent-skills/tree/main/skills/design` |
+| Local path | `./my-skills` or `/absolute/path` |
+
+## Lockfile
+
+Skills are tracked in a lockfile that serves as the source of truth:
+
+- **Global**: `~/.config/skillfu/skills.lock`
+- **Project**: `.agents/skills.lock`
+
+The project lockfile is designed to be committed to version control. Skills are sorted alphabetically and timestamps are omitted to minimize merge conflicts — two branches adding different skills produce non-overlapping JSON keys that git can auto-merge.
+
+## What Are Agent Skills?
+
+Agent skills are reusable instruction sets that extend your coding agent's capabilities. They're defined in `SKILL.md` files with YAML frontmatter:
+
+```markdown
+---
+name: my-skill
+description: What this skill does and when to use it
+---
+
+# My Skill
+
+Instructions for the agent to follow when this skill is activated.
+```
+
+Discover more skills at [skills.sh](https://skills.sh).
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `SKILLFU_CONFIG_DIR` | Override config directory (`~/.config/skillfu/`) |
+| `SKILLFU_CLONE_TIMEOUT_MS` | Git clone timeout in ms (default: 300000) |
+| `GITHUB_TOKEN` / `GH_TOKEN` | GitHub API token for higher rate limits |
+| `INSTALL_INTERNAL_SKILLS` | Set to `1` to include skills marked `internal: true` |
+| `SKILLFU_SKILLS_SH_KEY` | API key for skills.sh (higher rate limits) |
+
+## Differences from Vercel `skills`
+
+| | `skills` | `skillfu` |
+|---|---|---|
+| Scope | 50+ agents with per-agent symlinks | Single target: `~/.agents/skills` or `.agents/skills` |
+| Install methods | Symlink or copy | Symlink only |
+| Discovery | `find`, `list`, search API | None |
+| Lockfile | Global only, separate format per scope | Separate lockfiles per scope, co-located |
+| Update detection | GitHub Trees API | skills.sh API with Trees API fallback |
+| Source formats | GitHub, GitLab, well-known, git URLs, local | GitHub, GitHub URLs, local paths |
+| Agent detection | Auto-detects 50+ agents | No agent detection |
+| Telemetry | Anonymous usage tracking | None |
+
+## Development
+
+```bash
+bun install          # Install dependencies
+bun run dev add ...  # Run locally
+bun test             # Run tests
+bun run build        # Compile to dist/skillfu
+```

package/completions/_skillfu

@@ -0,0 +1,83 @@
+#compdef skillfu
+# skillfu shell completions for zsh
+# Install: skillfu completions zsh > ~/.zfunc/_skillfu
+# Then:     add ~/.zfunc to your fpath in ~/.zshrc
+
+_skillfu() {
+  local -a commands
+  commands=(
+    'add:Install skills from a GitHub repo or local path'
+    'remove:Remove installed skills'
+    'install:Ensure installed skills match the lockfile'
+    'update:Update skills to their latest versions'
+    'completions:Output shell completion script'
+    'help:Display help for a command'
+  )
+
+  _arguments -C \
+    '1:command:->command' \
+    '*::arg:->args'
+
+  case $state in
+    command)
+      _describe 'command' commands
+      ;;
+    args)
+      case ${words[1]} in
+        add)
+          _arguments \
+            '-s+[Install specific skill(s) by name]:skill:' \
+            '--skill+[Install specific skill(s) by name]:skill:' \
+            '-l[Install to project directory]' \
+            '--local[Install to project directory]' \
+            '-y[Skip confirmation prompts]' \
+            '--yes[Skip confirmation prompts]' \
+            '--ref+[Git branch or tag to install from]:branch:' \
+            '1:source:_files'
+          ;;
+        remove)
+          local -a installed_skills
+          local lockfile="$HOME/.config/skillfu/skills.lock"
+          if [[ -f "$lockfile" ]]; then
+            installed_skills=(${(f)"$(grep -o '"[a-z0-9-]*":' "$lockfile" | tr -d '":' | grep -v version)"})
+          fi
+          _arguments \
+            '-l[Remove from project scope]' \
+            '--local[Remove from project scope]' \
+            '-y[Skip confirmation prompts]' \
+            '--yes[Skip confirmation prompts]' \
+            '*:skill:->skills'
+
+          if [[ $state == skills ]]; then
+            _describe 'installed skill' installed_skills
+          fi
+          ;;
+        install)
+          _arguments \
+            '-l[Install from project lockfile]' \
+            '--local[Install from project lockfile]'
+          ;;
+        update)
+          local -a installed_skills
+          local lockfile="$HOME/.config/skillfu/skills.lock"
+          if [[ -f "$lockfile" ]]; then
+            installed_skills=(${(f)"$(grep -o '"[a-z0-9-]*":' "$lockfile" | tr -d '":' | grep -v version)"})
+          fi
+          _arguments \
+            '-l[Update project-scoped skills]' \
+            '--local[Update project-scoped skills]' \
+            '-s+[Update only specific skill(s)]:skill:' \
+            '--skill+[Update only specific skill(s)]:skill:' \
+            '-y[Skip confirmation prompts]' \
+            '--yes[Skip confirmation prompts]'
+          ;;
+        completions)
+          _arguments \
+            '1:shell:(bash zsh fish)'
+          ;;
+      esac
+      ;;
+  esac
+}
+
+_skillfu "$@"

package/completions/skillfu.bash

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# skillfu shell completions for bash
+# Install: skillfu completions bash > ~/.local/share/bash-completion/completions/skillfu
+# Or:       skillfu completions bash > /etc/bash_completion.d/skillfu
+
+_skillfu_completions() {
+  local cur prev words cword
+  _init_completion || return
+
+  # If completing the first word after 'skillfu', offer subcommands
+  if [[ ${#words[@]} -eq 2 ]]; then
+    COMPREPLY=($(compgen -W "add remove install update completions help" -- "${cur}"))
+    return
+  fi
+
+  local cmd="${words[1]}"
+
+  case "${cmd}" in
+    add)
+      # Complete options
+      case "${prev}" in
+        -s|--skill)
+          # No dynamic skill completion available
+          return
+          ;;
+        --ref)
+          return
+          ;;
+      esac
+
+      if [[ "${cur}" == -* ]]; then
+        COMPREPLY=($(compgen -W "-s --skill -l --local -y --yes --ref" -- "${cur}"))
+      fi
+      ;;
+    remove)
+      if [[ "${cur}" == -* ]]; then
+        COMPREPLY=($(compgen -W "-l --local -y --yes" -- "${cur}"))
+      else
+        # Offer installed skill names from lockfile
+        local lockfile="$HOME/.config/skillfu/skills.lock"
+        if [[ -f "${lockfile}" ]]; then
+          local skills=$(grep -o '"[a-z0-9-]*":' "${lockfile}" | tr -d '":' | grep -v version)
+          COMPREPLY=($(compgen -W "${skills}" -- "${cur}"))
+        fi
+      fi
+      ;;
+    install)
+      COMPREPLY=($(compgen -W "-l --local" -- "${cur}"))
+      ;;
+    update)
+      if [[ "${cur}" == -* ]]; then
+        COMPREPLY=($(compgen -W "-l --local -s --skill -y --yes" -- "${cur}"))
+      else
+        case "${prev}" in
+          -s|--skill)
+            local lockfile="$HOME/.config/skillfu/skills.lock"
+            if [[ -f "${lockfile}" ]]; then
+              local skills=$(grep -o '"[a-z0-9-]*":' "${lockfile}" | tr -d '":' | grep -v version)
+              COMPREPLY=($(compgen -W "${skills}" -- "${cur}"))
+            fi
+            ;;
+        esac
+      fi
+      ;;
+    completions)
+      COMPREPLY=($(compgen -W "bash zsh fish" -- "${cur}"))
+      ;;
+  esac
+}
+
+complete -F _skillfu_completions skillfu

package/completions/skillfu.fish

@@ -0,0 +1,35 @@
+# skillfu shell completions for fish
+# Install: skillfu completions fish > ~/.config/fish/completions/skillfu.fish
+
+# Disable file completions by default
+complete -c skillfu -f
+
+# Top-level subcommands
+complete -c skillfu -n __fish_use_subcommand -a add -d 'Install skills from a GitHub repo or local path'
+complete -c skillfu -n __fish_use_subcommand -a remove -d 'Remove installed skills'
+complete -c skillfu -n __fish_use_subcommand -a install -d 'Ensure installed skills match the lockfile'
+complete -c skillfu -n __fish_use_subcommand -a update -d 'Update skills to their latest versions'
+complete -c skillfu -n __fish_use_subcommand -a completions -d 'Output shell completion script'
+
+# add command
+complete -c skillfu -n '__fish_seen_subcommand_from add' -s s -l skill -d 'Install specific skill(s) by name' -r
+complete -c skillfu -n '__fish_seen_subcommand_from add' -s l -l local -d 'Install to project directory'
+complete -c skillfu -n '__fish_seen_subcommand_from add' -s y -l yes -d 'Skip confirmation prompts'
+complete -c skillfu -n '__fish_seen_subcommand_from add' -l ref -d 'Git branch or tag' -r
+
+# remove command
+complete -c skillfu -n '__fish_seen_subcommand_from remove' -s l -l local -d 'Remove from project scope'
+complete -c skillfu -n '__fish_seen_subcommand_from remove' -s y -l yes -d 'Skip confirmation prompts'
+# Offer installed skill names
+complete -c skillfu -n '__fish_seen_subcommand_from remove' -a '(grep -o \'"[a-z0-9-]*":\' ~/.config/skillfu/skills.lock 2>/dev/null | tr -d \'\":\' | grep -v version)'
+
+# install command
+complete -c skillfu -n '__fish_seen_subcommand_from install' -s l -l local -d 'Install from project lockfile'
+
+# update command
+complete -c skillfu -n '__fish_seen_subcommand_from update' -s l -l local -d 'Update project-scoped skills'
+complete -c skillfu -n '__fish_seen_subcommand_from update' -s s -l skill -d 'Update only specific skill(s)' -r
+complete -c skillfu -n '__fish_seen_subcommand_from update' -s y -l yes -d 'Skip confirmation prompts'
+
+# completions command
+complete -c skillfu -n '__fish_seen_subcommand_from completions' -a 'bash zsh fish'