skm-cli 0.1.0__tar.gz

skm_cli-0.1.0/.gitignore

@@ -0,0 +1 @@
+.venv/

skm_cli-0.1.0/AGENTS.md

@@ -0,0 +1,175 @@
+# SKM - Skill Manager
+
+A CLI tool that manages AI agent skills by cloning GitHub repos, detecting skills via `SKILL.md`, and symlinking them to agent directories based on a central YAML config.
+
+## Tech Stack
+
+- Python 3.12+, uv, click, pyyaml, pydantic
+- Git operations via subprocess (unified `run_cmd` helper raises `click.ClickException` on failure)
+- Tests: pytest
+
+## Project Structure
+
+```
+src/skm/
+├── cli.py              # Click CLI entry point (group + subcommands)
+├── types.py            # Pydantic data models + constants
+├── config.py           # Load skills.yaml → SkmConfig
+├── lock.py             # Read/write skills-lock.yaml
+├── detect.py           # Walk cloned repos for SKILL.md files
+├── git.py              # Clone, pull, fetch, commit SHA helpers (unified run_cmd error handling)
+├── utils.py            # Utility functions (compact_path)
+├── linker.py           # Symlink skills to agent dirs, resolve includes/excludes
+└── commands/
+    ├── install.py      # Clone repos, detect skills, link to agents, update lock
+    ├── list_cmd.py     # Print installed skills from lock file
+    ├── check_updates.py # Fetch remotes, compare commits, show available updates
+    └── update.py       # Pull latest for a skill's repo, re-link, update lock
+tests/
+├── test_types.py        # Pydantic model validation
+├── test_config.py       # Config loading, error handling
+├── test_lock.py         # Lock file I/O
+├── test_detect.py       # Skill detection logic (local + network tests against real repos)
+├── test_git.py          # Git operations (clone, commit retrieval, clone failure handling)
+├── test_linker.py       # Symlink creation, agent filtering
+├── test_install.py      # Install command unit tests
+└── test_cli_e2e.py      # End-to-end CLI tests for all commands
+```
+
+## Key Paths
+
+- **Config:** `~/.config/skm/skills.yaml` — YAML dict with `packages` (repo list) and optional `agents.default`
+- **Lock:** `~/.config/skm/skills-lock.yaml` — tracks installed skills, commits, symlink paths
+- **Store:** `~/.local/share/skm/skills/` — cloned repos cached here
+- **Agent dirs:** Skills are symlinked into each agent's skill directory (e.g. `~/.claude/skills/`, `~/.codex/skills/`)
+
+## Architecture
+
+Config-driven: parse `skills.yaml` → clone repos to store → detect skills by walking for `SKILL.md` → symlink to agent dirs → write lock file.
+
+Each command function (`run_install`, `run_list`, etc.) accepts explicit paths and agent dicts as parameters, making them testable with `tmp_path` fixtures without touching real filesystem locations.
+
+## Error Handling
+
+All git subprocess calls go through `run_cmd()` in `git.py`, which captures stdout/stderr and raises `click.ClickException` on non-zero exit codes. This produces user-friendly error messages instead of raw `CalledProcessError` tracebacks.
+
+## Path Handling
+
+Paths stored in `skills-lock.yaml` (e.g. `linked_to`) use `compact_path()` from `utils.py` to replace the home directory with `~`, avoiding exposure of usernames. When reading these paths back for filesystem operations, `Path.expanduser()` is used.
+
+## CLI Commands
+
+- `skm install` — Clone repos (idempotent: skips pull if already cloned), detect skills, create symlinks, remove stale links, update lock. Treats `skills.yaml` as declarative state: removes links for skills dropped from config or agents changed by includes/excludes. Only removes links tracked in the lock file — manually created files in agent dirs are never touched.
+- `skm list` — Show installed skills and their linked paths from lock file
+- `skm check-updates` — Fetch remotes, compare against locked commits, show changelog
+- `skm update <skill_name>` — Pull latest for a skill's repo, re-link, update lock
+
+## Config Format (skills.yaml)
+
+Top-level YAML dict with `packages` and optional `agents`:
+
+```yaml
+agents:
+  default:                   # optional: select which KNOWN_AGENTS are active (omit = all)
+    - claude
+    - standard
+
+packages:
+  - repo: https://github.com/vercel-labs/agent-skills
+    skills:                  # optional: filter to specific skills (omit = all)
+      - react-best-practices
+    agents:                  # optional: further filter agents for this package
+      excludes:
+        - standard
+  - repo: https://github.com/blader/humanizer   # installs all detected skills to default agents
+```
+
+`agents.default` selects which agents from `KNOWN_AGENTS` are used as the base set. Per-package `agents.includes/excludes` then filters from that base set.
+
+## Skill Detection
+
+A skill is a directory containing a `SKILL.md` file with YAML frontmatter including a `name` field. Detection order:
+1. Root `SKILL.md` → singleton skill (the repo itself is the skill)
+2. `./skills/` subdirectory exists → walk its children
+3. Otherwise → walk all subdirectories from repo root
+4. Stop descending once `SKILL.md` is found (no nested skill-in-skill)
+
+## Known Agents
+
+Defined in `src/skm/types.py` as `KNOWN_AGENTS`:
+- `standard` → `~/.agents/skills`
+- `claude` → `~/.claude/skills`
+- `codex` → `~/.codex/skills`
+- `openclaw` → `~/.openclaw/skills`
+
+## Testing
+
+### Running Tests
+
+```bash
+uv sync
+uv run pytest -v              # all tests
+uv run pytest tests/test_cli_e2e.py -v   # e2e only
+uv run pytest -k "install" -v            # filter by name
+```
+
+### Test Isolation
+
+All tests run entirely within pytest's `tmp_path` — no real agent directories, config files, or git repos are touched. This is achieved two ways:
+
+- **Unit tests** (`test_install.py`, `test_linker.py`, etc.): call `run_*` functions directly with explicit `config`/`lock_path`/`store_dir`/`known_agents` parameters pointing to `tmp_path` subdirectories.
+- **E2E tests** (`test_cli_e2e.py`): invoke the CLI through Click's `CliRunner` with `--config`, `--store`, `--lock`, and `--agents-dir` flags to redirect all I/O into `tmp_path`.
+
+Git repos used in tests are local repos created via `git init` inside `tmp_path` — no network access required. Tests marked with `@pytest.mark.network` clone real GitHub repos and require internet access.
+
+### CLI Path Overrides
+
+The CLI group accepts four flags to override default paths, useful for both testing and safe manual experimentation:
+
+```bash
+skm --config /tmp/test.yaml \
+    --store /tmp/store \
+    --lock /tmp/lock.yaml \
+    --agents-dir /tmp/agents \
+    install
+```
+
+- `--config` — path to `skills.yaml` (default: `~/.config/skm/skills.yaml`)
+- `--lock` — path to `skills-lock.yaml` (default: `~/.config/skm/skills-lock.yaml`)
+- `--store` — directory for cloned repos (default: `~/.local/share/skm/skills/`)
+- `--agents-dir` — base directory for agent symlinks; creates subdirs per agent name (overrides `KNOWN_AGENTS` paths)
+
+### E2E Test Helpers
+
+`test_cli_e2e.py` provides reusable helpers for writing new tests:
+
+- `_make_skill_repo(base, repo_name, skills)` — creates a local git repo with specified skills. Each skill is `{"name": str, "subdir": bool}` where `subdir=True` (default) puts it under `skills/<name>/`, `False` makes it a singleton at repo root.
+- `_cli_args(tmp_path)` — returns the common `--config/--store/--lock/--agents-dir` flags for full isolation.
+- `_write_config(tmp_path, repos, agents=None)` — writes a `skills.yaml` with `{"packages": repos}` format, optionally including `agents` config.
+- `_load_lock(tmp_path)` — loads the lock file as a plain dict for assertions.
+
+### Writing New Tests
+
+To add a new e2e test, follow this pattern:
+
+```python
+def test_my_scenario(self, tmp_path):
+    repo = _make_skill_repo(tmp_path, "my-repo", [{"name": "my-skill"}])
+    _write_config(tmp_path, [{"repo": str(repo)}])  # wraps in {"packages": ...}
+
+    runner = CliRunner()
+    result = runner.invoke(cli, [*_cli_args(tmp_path), "install"])
+
+    assert result.exit_code == 0, result.output
+    # assert on symlinks, lock contents, output text, etc.
+```
+
+## Development
+
+```bash
+uv sync
+uv run pytest -v      # run tests
+uv run skm --help     # run CLI
+```
+
+Do not run formatters or style linters on the code.

skm_cli-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: skm-cli
+Version: 0.1.0
+Summary: Skill Manager - manage agent skills from GitHub repos
+Author-email: Reorx <novoreorx@gmail.com>
+Requires-Python: >=3.12
+Requires-Dist: click>=8.1
+Requires-Dist: pydantic>=2.0
+Requires-Dist: ruamel-yaml>=0.18
+Description-Content-Type: text/markdown
+
+# SKM - Skill Manager
+
+A CLI tool that manages **global** AI agent skills from GitHub repos or local directories. Clone repos or link local paths, detect skills via `SKILL.md`, and symlink them into agent directories — all driven by a single YAML config.
+
+> **Note:** skm manages skills at the user level (e.g. `~/.claude/skills/`), not at the project level. It is not intended for installing skills into project-scoped directories.
+
+![skm install](images/skm-install.png)
+
+## Install
+
+```bash
+uv tool install git+https://github.com/reorx/skm
+```
+
+## Quick Start
+
+1. Create `~/.config/skm/skills.yaml`:
+
+```yaml
+packages:
+  - repo: https://github.com/vercel-labs/agent-skills
+    skills:
+      - vercel-react-best-practices
+      - vercel-react-native-skills
+  - repo: https://github.com/blader/humanizer
+  - local_path: ~/Code/my-custom-skills       # use a local directory instead of a git repo
+```
+
+2. Run install (`skm i` for short):
+
+```bash
+skm install
+```
+
+Skills are cloned (or symlinked from local paths) into your agent directories (`~/.claude/skills/`, `~/.codex/skills/`, etc.).
+
+### Install from a source directly
+
+You can also install skills directly from a repo URL or local path — no need to edit `skills.yaml` first:
+
+```bash
+# Install from a GitHub repo (interactive skill & agent selection)
+skm install https://github.com/vercel-labs/agent-skills
+
+# Install a specific skill by name
+skm install https://github.com/vercel-labs/agent-skills vercel-react-best-practices
+
+# Install from a local directory
+skm install ~/Code/my-custom-skills
+
+# Skip interactive prompts with --agents-includes / --agents-excludes
+skm install https://github.com/blader/humanizer --agents-includes claude,codex
+```
+
+This detects available skills, lets you pick which ones to install (unless a specific skill name is given), and automatically adds the package to your `skills.yaml` config.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `skm install` (or `skm i`) | Install all packages from config. Clone repos (or link local paths), detect skills, symlink to agents, write lock file. Idempotent — also removes stale links (see below). |
+| `skm install <source> [skill]` (or `skm i`) | Install directly from a repo URL or local path without editing config. Interactively select skills and agents, then auto-update config. |
+| `skm list` | Show installed skills and their linked paths. |
+| `skm list --all` | Show all skills across all agent directories, marking which are managed by skm. |
+| `skm view <source>` | Browse and preview skills from a repo URL or local path without installing. |
+| `skm check-updates` | Fetch remotes and show available updates (skips `local_path` packages). |
+| `skm update <skill>` | Pull latest for a skill's repo, re-detect, re-link, update lock (skips `local_path` packages). |
+
+## Config Format
+
+`~/.config/skm/skills.yaml`:
+
+```yaml
+agents:
+  default:                   # optional: select which agents are active (omit = all)
+    - claude
+    - standard
+
+packages:
+  - repo: https://github.com/vercel-labs/agent-skills
+    skills:                  # optional: install only these skills (omit = all)
+      - vercel-react-best-practices
+    agents:                  # optional: further filter agents for this package
+      excludes:
+        - standard
+
+  - repo: https://github.com/blader/humanizer   # installs all detected skills to default agents
+
+  - local_path: ~/Code/my-custom-skills         # use a local directory as package source
+    skills:
+      - my-skill
+```
+
+Each package must specify exactly one of `repo` or `local_path`. Local path packages use the directory directly (no cloning) and are skipped by `check-updates` and `update`.
+
+## Install Sync Behavior
+
+`skm install` treats `skills.yaml` as a declarative state file. Each run syncs the agent directories to match the config:
+
+- **New skills** are linked to agent directories.
+- **Removed skills** (dropped from a package's `skills:` list, or entire package removed) have their links deleted.
+- **Agent config changes** (e.g. adding `excludes: [openclaw]`) remove links from excluded agents while keeping links in others.
+
+Only links tracked in `skills-lock.yaml` are affected. Manually created files or skills installed by other tools in agent directories are never touched.
+
+## Skill Detection
+
+A skill is a directory containing a `SKILL.md` file with YAML frontmatter (`name` field required). Detection order:
+
+1. Root `SKILL.md` — the repo itself is a singleton skill
+2. `./skills/` subdirectory exists — scan its children
+3. Otherwise — walk all subdirectories from repo root
+4. Stop descending once `SKILL.md` is found (no nested skills)
+
+## Known Agents
+
+Skills are symlinked into these directories by default:
+
+| Agent | Path |
+|---|---|
+| `standard` | `~/.agents/skills/` |
+| `claude` | `~/.claude/skills/` |
+| `codex` | `~/.codex/skills/` |
+| `openclaw` | `~/.openclaw/skills/` |
+
+## CLI Path Overrides
+
+Override default paths for testing or custom setups:
+
+```bash
+skm --config /tmp/test.yaml \
+    --store /tmp/store \
+    --lock /tmp/lock.yaml \
+    --agents-dir /tmp/agents \
+    install
+```
+
+## Key Paths
+
+- **Config:** `~/.config/skm/skills.yaml`
+- **Lock:** `~/.config/skm/skills-lock.yaml`
+- **Store:** `~/.local/share/skm/skills/`
+
+## Development
+
+```bash
+uv sync
+uv run pytest -v      # run tests
+uv run skm --help     # run CLI
+```

skm_cli-0.1.0/README.md

@@ -0,0 +1,150 @@
+# SKM - Skill Manager
+
+A CLI tool that manages **global** AI agent skills from GitHub repos or local directories. Clone repos or link local paths, detect skills via `SKILL.md`, and symlink them into agent directories — all driven by a single YAML config.
+
+> **Note:** skm manages skills at the user level (e.g. `~/.claude/skills/`), not at the project level. It is not intended for installing skills into project-scoped directories.
+
+![skm install](images/skm-install.png)
+
+## Install
+
+```bash
+uv tool install git+https://github.com/reorx/skm
+```
+
+## Quick Start
+
+1. Create `~/.config/skm/skills.yaml`:
+
+```yaml
+packages:
+  - repo: https://github.com/vercel-labs/agent-skills
+    skills:
+      - vercel-react-best-practices
+      - vercel-react-native-skills
+  - repo: https://github.com/blader/humanizer
+  - local_path: ~/Code/my-custom-skills       # use a local directory instead of a git repo
+```
+
+2. Run install (`skm i` for short):
+
+```bash
+skm install
+```
+
+Skills are cloned (or symlinked from local paths) into your agent directories (`~/.claude/skills/`, `~/.codex/skills/`, etc.).
+
+### Install from a source directly
+
+You can also install skills directly from a repo URL or local path — no need to edit `skills.yaml` first:
+
+```bash
+# Install from a GitHub repo (interactive skill & agent selection)
+skm install https://github.com/vercel-labs/agent-skills
+
+# Install a specific skill by name
+skm install https://github.com/vercel-labs/agent-skills vercel-react-best-practices
+
+# Install from a local directory
+skm install ~/Code/my-custom-skills
+
+# Skip interactive prompts with --agents-includes / --agents-excludes
+skm install https://github.com/blader/humanizer --agents-includes claude,codex
+```
+
+This detects available skills, lets you pick which ones to install (unless a specific skill name is given), and automatically adds the package to your `skills.yaml` config.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `skm install` (or `skm i`) | Install all packages from config. Clone repos (or link local paths), detect skills, symlink to agents, write lock file. Idempotent — also removes stale links (see below). |
+| `skm install <source> [skill]` (or `skm i`) | Install directly from a repo URL or local path without editing config. Interactively select skills and agents, then auto-update config. |
+| `skm list` | Show installed skills and their linked paths. |
+| `skm list --all` | Show all skills across all agent directories, marking which are managed by skm. |
+| `skm view <source>` | Browse and preview skills from a repo URL or local path without installing. |
+| `skm check-updates` | Fetch remotes and show available updates (skips `local_path` packages). |
+| `skm update <skill>` | Pull latest for a skill's repo, re-detect, re-link, update lock (skips `local_path` packages). |
+
+## Config Format
+
+`~/.config/skm/skills.yaml`:
+
+```yaml
+agents:
+  default:                   # optional: select which agents are active (omit = all)
+    - claude
+    - standard
+
+packages:
+  - repo: https://github.com/vercel-labs/agent-skills
+    skills:                  # optional: install only these skills (omit = all)
+      - vercel-react-best-practices
+    agents:                  # optional: further filter agents for this package
+      excludes:
+        - standard
+
+  - repo: https://github.com/blader/humanizer   # installs all detected skills to default agents
+
+  - local_path: ~/Code/my-custom-skills         # use a local directory as package source
+    skills:
+      - my-skill
+```
+
+Each package must specify exactly one of `repo` or `local_path`. Local path packages use the directory directly (no cloning) and are skipped by `check-updates` and `update`.
+
+## Install Sync Behavior
+
+`skm install` treats `skills.yaml` as a declarative state file. Each run syncs the agent directories to match the config:
+
+- **New skills** are linked to agent directories.
+- **Removed skills** (dropped from a package's `skills:` list, or entire package removed) have their links deleted.
+- **Agent config changes** (e.g. adding `excludes: [openclaw]`) remove links from excluded agents while keeping links in others.
+
+Only links tracked in `skills-lock.yaml` are affected. Manually created files or skills installed by other tools in agent directories are never touched.
+
+## Skill Detection
+
+A skill is a directory containing a `SKILL.md` file with YAML frontmatter (`name` field required). Detection order:
+
+1. Root `SKILL.md` — the repo itself is a singleton skill
+2. `./skills/` subdirectory exists — scan its children
+3. Otherwise — walk all subdirectories from repo root
+4. Stop descending once `SKILL.md` is found (no nested skills)
+
+## Known Agents
+
+Skills are symlinked into these directories by default:
+
+| Agent | Path |
+|---|---|
+| `standard` | `~/.agents/skills/` |
+| `claude` | `~/.claude/skills/` |
+| `codex` | `~/.codex/skills/` |
+| `openclaw` | `~/.openclaw/skills/` |
+
+## CLI Path Overrides
+
+Override default paths for testing or custom setups:
+
+```bash
+skm --config /tmp/test.yaml \
+    --store /tmp/store \
+    --lock /tmp/lock.yaml \
+    --agents-dir /tmp/agents \
+    install
+```
+
+## Key Paths
+
+- **Config:** `~/.config/skm/skills.yaml`
+- **Lock:** `~/.config/skm/skills-lock.yaml`
+- **Store:** `~/.local/share/skm/skills/`
+
+## Development
+
+```bash
+uv sync
+uv run pytest -v      # run tests
+uv run skm --help     # run CLI
+```

skm_cli-0.1.0/draft.md

@@ -0,0 +1,35 @@
+build skm, which is a skill manager that manage agent skills by a certral yaml config.
+
+skm should be build with uv and python, use python modern packaing best practices. use click library to implement CLI.
+
+skm can detect skills from a github repo. follow the patterns:
+- find ./skills dir, if exists, start walk through  from ./skills; if not exists, start walk through from ./
+- how to walk through: iterate the sub dirs, if a dir has SKILL.md, it's a skill, stop digging down that dir
+- note that ./ may also contain a SKILL.md, in this case the repo itself is a singleton skill, and no need to start the walk through
+
+## Config
+
+config path: `~/.config/skm/skills.yaml`
+
+see @skills.example.yaml for the config example:
+- repo: github repo url
+- skills: list of skill name to use in this repo. note that this is the name in skill frontmatter, not the skill dir's name.
+- agents: configure which agents to install this skill. either `includes` or `excludes` is configured, by default install to all the known agents.
+
+skills should be cloned to a central path `~/.local/share/skm/skills/`, then soft link to agents according to `agents:` option. when linking skills from the central path to the agent's skill dir, you should always use the skill's frontmatter name as the target dir name.
+
+
+## Agents
+
+currently support agents:
+- standard dir: `~/.agents/skills`
+- claude: `~/.claude/skills`
+- codex: `~/.codex/skills`
+- openclaw: `~/.openclaw/skills`
+
+## CLI
+
+- `skm install`: install/remove skills based on config, this command does not update an installed skill. a lock file (~/.config/skm/skills-lock.yaml`) will be generated or updated after install, representing the version (commit), linked pathes, and other states of installed skills.
+- `skm check-updates`: check for each skills' repo to see if there's any updates, list the git log for each skill with new commits, similar to some nvim plugin managers like how lazyvim does
+- `skm update <skill-name>`: update a skill and show changes, reflect on skills-lock.yaml
+- `skm list`: list each installed skill with the pathes they are linked to.