skillup 0.3.2__tar.gz → 0.4.0__tar.gz

skillup-0.4.0/.github/workflows/docs.yml

@@ -0,0 +1,42 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'zensical.toml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/configure-pages@v5
+        with:
+          enablement: true
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install Zensical
+        run: pip install zensical
+      - name: Build docs
+        run: zensical build --clean
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+      - uses: actions/deploy-pages@v4
+        id: deployment

skillup-0.4.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: skillup
+Version: 0.4.0
+Summary: A minimal CLI to manage agent skills from GitHub releases.
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: questionary
+Requires-Dist: requests
+Requires-Dist: rich
+Requires-Dist: typer
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/logo-wordmark.svg" alt="skillup" height="72" />
+</p>
+
+<p align="center">
+  <strong>Skill your agents up.</strong><br/>
+  A minimal CLI to install, version, and sync skills for your AI agents.<br/>
+  Local-first · GitHub-backed · Works with Claude, Gemini, and more.
+</p>
+
+<p align="center">
+  <code>pip install skillup</code> &nbsp;·&nbsp; <code>uv tool install skillup</code>
+</p>
+
+---
+
+## Features
+
+- **Interactive install** — pick skills from any GitHub repo release
+- **Multi-repo** — manage skills from multiple sources independently
+- **Lock file** — pins commit SHAs for reproducible installs (`~/.agents/skills.lock.json`)
+- **Auto-update** — upgrade all or specific repos to their latest release or branch head
+- **Smart cache** — skips redundant downloads; override with `SKILLUP_CACHE_DIR`
+- **gh integration** — uses `gh` CLI when available, falls back to `requests`
+
+## Installation
+
+```bash
+pip install skillup
+# or
+uv tool install skillup
+```
+
+## Usage
+
+### Add skills
+
+```bash
+skillup add google/gemini-cli-skills
+```
+
+No releases? Falls back to `main` automatically. Pin a branch explicitly:
+
+```bash
+skillup add anthropics/skills --branch main --skill pdf
+```
+
+### Remove skills
+
+```bash
+skillup remove
+```
+
+### Update skills
+
+```bash
+skillup update                              # all repos
+skillup update --repo google/gemini-cli-skills  # one repo
+```
+
+### Sync (restore from lock file)
+
+```bash
+skillup sync
+```
+
+Installs skills at the exact pinned SHAs from the lock file — useful for new machines.
+
+### Migrate from NPX skills CLI
+
+```bash
+skillup migrate                       # reads skills-lock.json from repo root
+skillup migrate path/to/skills-lock.json
+```
+
+## Skill definition
+
+A folder is recognized as a skill when it lives inside a `skills/` directory at the repo root and contains a `SKILL.md` file.
+
+## Development
+
+```bash
+uv sync          # install deps
+uv run skillup --help
+uv run pytest
+uv run pyright skillup
+```
+
+## License
+
+MIT

skillup-0.4.0/README.md

@@ -0,0 +1,91 @@
+<p align="center">
+  <img src="assets/logo-wordmark.svg" alt="skillup" height="72" />
+</p>
+
+<p align="center">
+  <strong>Skill your agents up.</strong><br/>
+  A minimal CLI to install, version, and sync skills for your AI agents.<br/>
+  Local-first · GitHub-backed · Works with Claude, Gemini, and more.
+</p>
+
+<p align="center">
+  <code>pip install skillup</code> &nbsp;·&nbsp; <code>uv tool install skillup</code>
+</p>
+
+---
+
+## Features
+
+- **Interactive install** — pick skills from any GitHub repo release
+- **Multi-repo** — manage skills from multiple sources independently
+- **Lock file** — pins commit SHAs for reproducible installs (`~/.agents/skills.lock.json`)
+- **Auto-update** — upgrade all or specific repos to their latest release or branch head
+- **Smart cache** — skips redundant downloads; override with `SKILLUP_CACHE_DIR`
+- **gh integration** — uses `gh` CLI when available, falls back to `requests`
+
+## Installation
+
+```bash
+pip install skillup
+# or
+uv tool install skillup
+```
+
+## Usage
+
+### Add skills
+
+```bash
+skillup add google/gemini-cli-skills
+```
+
+No releases? Falls back to `main` automatically. Pin a branch explicitly:
+
+```bash
+skillup add anthropics/skills --branch main --skill pdf
+```
+
+### Remove skills
+
+```bash
+skillup remove
+```
+
+### Update skills
+
+```bash
+skillup update                              # all repos
+skillup update --repo google/gemini-cli-skills  # one repo
+```
+
+### Sync (restore from lock file)
+
+```bash
+skillup sync
+```
+
+Installs skills at the exact pinned SHAs from the lock file — useful for new machines.
+
+### Migrate from NPX skills CLI
+
+```bash
+skillup migrate                       # reads skills-lock.json from repo root
+skillup migrate path/to/skills-lock.json
+```
+
+## Skill definition
+
+A folder is recognized as a skill when it lives inside a `skills/` directory at the repo root and contains a `SKILL.md` file.
+
+## Development
+
+```bash
+uv sync          # install deps
+uv run skillup --help
+uv run pytest
+uv run pyright skillup
+```
+
+## License
+
+MIT

skillup-0.4.0/assets/logo-wordmark.svg

@@ -0,0 +1,12 @@
+<svg viewBox="0 0 288 64" xmlns="http://www.w3.org/2000/svg">
+  <!-- Mark -->
+  <rect x="2" y="2" width="60" height="60" rx="14" fill="#0a0a0a"/>
+  <path d="M14 22 L23 32 L14 42" stroke="#ffffff" stroke-width="4" fill="none" stroke-linecap="square" stroke-linejoin="miter"/>
+  <rect x="27" y="40" width="11" height="3.5" fill="#ffffff"/>
+  <rect x="42" y="34" width="4" height="8" fill="#00d26a"/>
+  <rect x="48" y="28" width="4" height="14" fill="#00d26a"/>
+  <rect x="54" y="22" width="4" height="20" fill="#00d26a"/>
+  <!-- Wordmark -->
+  <text x="79" y="46" font-family="'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, monospace" font-weight="700" font-size="40" letter-spacing="-1.6" fill="#0a0a0a">skill</text>
+  <text x="191" y="46" font-family="'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, monospace" font-weight="700" font-size="40" letter-spacing="-1.6" fill="#00d26a">up</text>
+</svg>

skillup-0.4.0/assets/logo.svg

@@ -0,0 +1,8 @@
+<svg viewBox="0 0 64 64" xmlns="http://www.w3.org/2000/svg">
+  <rect x="2" y="2" width="60" height="60" rx="14" fill="#0a0a0a"/>
+  <path d="M14 22 L23 32 L14 42" stroke="#ffffff" stroke-width="4" fill="none" stroke-linecap="square" stroke-linejoin="miter"/>
+  <rect x="27" y="40" width="11" height="3.5" fill="#ffffff"/>
+  <rect x="42" y="34" width="4" height="8" fill="#00d26a"/>
+  <rect x="48" y="28" width="4" height="14" fill="#00d26a"/>
+  <rect x="54" y="22" width="4" height="20" fill="#00d26a"/>
+</svg>

skillup-0.4.0/docs/assets/extra.css

@@ -0,0 +1,186 @@
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;700&display=swap');
+
+/* ── Brand tokens ─────────────────────────────── */
+:root {
+  --su-ink:        #0a0a0a;
+  --su-ink-2:      #141414;
+  --su-ink-3:      #1a1a1a;
+  --su-ink-4:      #262626;
+  --su-paper:      #fafaf9;
+  --su-bone:       #f5f5f4;
+  --su-line:       #e7e5e4;
+  --su-mute:       #78716c;
+  --su-green:      #00d26a;
+  --su-green-dark: #00a854;
+  --su-amber:      #fbbf24;
+  --su-cyan:       #22d3ee;
+}
+
+/* ── Typography ───────────────────────────────── */
+body,
+.md-typeset {
+  font-family: 'Inter', system-ui, sans-serif;
+}
+
+code,
+pre,
+kbd,
+.md-typeset code,
+.md-typeset pre {
+  font-family: 'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, monospace !important;
+}
+
+/* tight tracking on headings — matches brand */
+.md-typeset h1,
+.md-typeset h2,
+.md-typeset h3 {
+  font-family: 'JetBrains Mono', ui-monospace, monospace;
+  font-weight: 700;
+  letter-spacing: -0.03em;
+}
+
+/* ── Header — always ink ──────────────────────── */
+.md-header {
+  background-color: var(--su-ink) !important;
+  border-bottom: 1px solid var(--su-ink-4);
+  box-shadow: none;
+}
+
+.md-header__title {
+  font-family: 'JetBrains Mono', monospace;
+  font-weight: 700;
+  letter-spacing: -0.03em;
+}
+
+/* "up" green accent in site title */
+.md-header__title::after {
+  content: '';
+}
+
+/* ── Dark mode (slate scheme) ─────────────────── */
+[data-md-color-scheme="slate"] {
+  --md-default-bg-color:           var(--su-ink);
+  --md-default-bg-color--light:    var(--su-ink-2);
+  --md-default-fg-color:           #e5e5e5;
+  --md-default-fg-color--light:    #a3a3a3;
+  --md-default-fg-color--lighter:  #737373;
+  --md-default-fg-color--lightest: #404040;
+  --md-code-bg-color:              var(--su-ink-3);
+  --md-code-fg-color:              #e5e5e5;
+  --md-typeset-a-color:            var(--su-green);
+  --md-accent-fg-color:            var(--su-green);
+  --md-primary-fg-color:           var(--su-green);
+}
+
+/* nav sidebar in dark mode */
+[data-md-color-scheme="slate"] .md-sidebar {
+  background-color: var(--su-ink-2);
+}
+
+[data-md-color-scheme="slate"] .md-nav__link--active,
+[data-md-color-scheme="slate"] .md-nav__link:hover {
+  color: var(--su-green) !important;
+}
+
+/* ── Light mode (default scheme) ─────────────── */
+[data-md-color-scheme="default"] {
+  --md-default-bg-color:  var(--su-paper);
+  --md-code-bg-color:     var(--su-bone);
+  --md-typeset-a-color:   var(--su-green-dark);
+  --md-accent-fg-color:   var(--su-green-dark);
+  --md-primary-fg-color:  var(--su-green-dark);
+}
+
+[data-md-color-scheme="default"] .md-nav__link--active,
+[data-md-color-scheme="default"] .md-nav__link:hover {
+  color: var(--su-green-dark) !important;
+}
+
+/* ── Code blocks — terminal feel ─────────────── */
+.md-typeset .highlight {
+  border-radius: 4px;
+  border: 1px solid var(--su-ink-4);
+}
+
+[data-md-color-scheme="slate"] .md-typeset .highlight {
+  background-color: var(--su-ink-3) !important;
+}
+
+/* shell prompt color */
+[data-md-color-scheme="slate"] .md-typeset .highlight .gp {
+  color: #525252;
+}
+
+/* ── Inline code ──────────────────────────────── */
+[data-md-color-scheme="slate"] .md-typeset code:not(.highlight code) {
+  background-color: var(--su-ink-3);
+  border: 1px solid var(--su-ink-4);
+  color: var(--su-green);
+  padding: 0.1em 0.35em;
+  border-radius: 3px;
+}
+
+/* ── Admonition / callout accents ────────────── */
+.md-typeset .admonition,
+.md-typeset details {
+  border-radius: 4px;
+  border-left-width: 3px;
+}
+
+.md-typeset .note > .admonition-title,
+.md-typeset .note > summary {
+  border-left-color: var(--su-cyan);
+}
+
+.md-typeset .tip > .admonition-title,
+.md-typeset .tip > summary {
+  border-left-color: var(--su-green);
+}
+
+.md-typeset .warning > .admonition-title,
+.md-typeset .warning > summary {
+  border-left-color: var(--su-amber);
+}
+
+/* ── Tables ───────────────────────────────────── */
+[data-md-color-scheme="slate"] .md-typeset table:not([class]) th {
+  background-color: var(--su-ink-3);
+  color: var(--su-green);
+  font-family: 'JetBrains Mono', monospace;
+  font-size: 0.75rem;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+[data-md-color-scheme="slate"] .md-typeset table:not([class]) td {
+  border-color: var(--su-ink-4);
+}
+
+/* ── Footer ───────────────────────────────────── */
+.md-footer {
+  background-color: var(--su-ink) !important;
+  border-top: 1px solid var(--su-ink-4);
+}
+
+.md-footer-meta {
+  background-color: var(--su-ink) !important;
+}
+
+/* ── Scrollbar (dark) ─────────────────────────── */
+[data-md-color-scheme="slate"] ::-webkit-scrollbar {
+  width: 6px;
+  height: 6px;
+}
+
+[data-md-color-scheme="slate"] ::-webkit-scrollbar-track {
+  background: var(--su-ink-2);
+}
+
+[data-md-color-scheme="slate"] ::-webkit-scrollbar-thumb {
+  background: var(--su-ink-4);
+  border-radius: 3px;
+}
+
+[data-md-color-scheme="slate"] ::-webkit-scrollbar-thumb:hover {
+  background: #404040;
+}

skillup-0.4.0/docs/assets/logo.svg

@@ -0,0 +1,8 @@
+<svg viewBox="0 0 64 64" xmlns="http://www.w3.org/2000/svg">
+  <rect x="2" y="2" width="60" height="60" rx="14" fill="#0a0a0a"/>
+  <path d="M14 22 L23 32 L14 42" stroke="#ffffff" stroke-width="4" fill="none" stroke-linecap="square" stroke-linejoin="miter"/>
+  <rect x="27" y="40" width="11" height="3.5" fill="#ffffff"/>
+  <rect x="42" y="34" width="4" height="8" fill="#00d26a"/>
+  <rect x="48" y="28" width="4" height="14" fill="#00d26a"/>
+  <rect x="54" y="22" width="4" height="20" fill="#00d26a"/>
+</svg>

skillup-0.4.0/docs/changelog.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## Unreleased
+
+- Added Zensical documentation site
+- Added brand assets (`assets/logo.svg`, `assets/logo-wordmark.svg`)
+
+## v0.4.1
+
+- Renamed CLI from `bms-skills` to `skillup`
+- Added `migrate` command to import `skills-lock.json` from the NPX skills CLI
+- Fixed `migrate` default input path to repo root
+- Refactored `cli.py` into focused modules (`install`, `lock`, `settings`, `github`)

skillup-0.4.0/docs/commands.md

@@ -0,0 +1,135 @@
+# Commands
+
+## Global flag
+
+All commands accept a `--global` / `-g` flag that switches the lock file and base directory to your home directory instead of the current working directory.
+
+```bash
+skillup --global add myorg/skills
+```
+
+---
+
+## `add`
+
+Add skills from a GitHub release or branch.
+
+```bash
+skillup add <owner/repo> [OPTIONS]
+```
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--skill TEXT` | `-s` | Skill name to add (repeatable). Skips interactive picker. |
+| `--branch TEXT` | `-b` | Install from this branch instead of the latest release. |
+
+**Examples**
+
+```bash
+# Interactive picker — choose from all available skills
+skillup add google/gemini-cli-skills
+
+# Add one skill non-interactively
+skillup add anthropics/skills --skill pdf
+
+# Add multiple skills at once
+skillup add anthropics/skills --skill pdf --skill code-review
+
+# Pin to a branch
+skillup add myorg/skills --branch main
+```
+
+**Behavior**
+
+- Fetches the latest GitHub release. If none exists, falls back to `main`.
+- Downloads the release zip (cached in `TEMP`/`/tmp` or `SKILLUP_CACHE_DIR`).
+- Installs selected skills to `~/.agents/skills` and `~/.claude/skills`.
+- Writes the resolved tag/commit to the lock file.
+
+---
+
+## `remove`
+
+Interactively remove installed skills.
+
+```bash
+skillup remove
+```
+
+Shows a checkbox list of all installed skills across all tracked repos. Selected skills are deleted from disk and removed from the lock file. Repos with no remaining skills are dropped from the lock file entirely.
+
+---
+
+## `update`
+
+Update installed skills to the latest release or branch head.
+
+```bash
+skillup update [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--repo TEXT` | Update only this repository (`owner/repo`). |
+
+**Examples**
+
+```bash
+# Update everything
+skillup update
+
+# Update one repo
+skillup update --repo google/gemini-cli-skills
+```
+
+**Behavior**
+
+- Resolves the current latest source for each repo (release or branch head).
+- If the resolved commit/tag matches what's in the lock file, skips with "already up-to-date".
+- Re-installs all skills from the new source and updates the lock file.
+
+---
+
+## `sync`
+
+Install all skills exactly as defined in the lock file.
+
+```bash
+skillup sync
+```
+
+Uses the pinned commit SHAs from the lock file — no network resolution of "latest". Useful for:
+
+- Setting up a new machine from a shared or committed lock file.
+- CI environments that need deterministic installs.
+
+---
+
+## `migrate`
+
+Import a `skills-lock.json` from the Claude Code NPX skills CLI.
+
+```bash
+skillup migrate [INPUT_FILE]
+```
+
+| Argument | Description |
+|----------|-------------|
+| `INPUT_FILE` | Path to `skills-lock.json`. Defaults to `<base_dir>/skills-lock.json`. |
+
+**Example**
+
+```bash
+# Default path
+skillup migrate
+
+# Custom path
+skillup migrate path/to/skills-lock.json
+```
+
+**Behavior**
+
+- Reads each GitHub-sourced skill from the input file.
+- Resolves the current latest release/branch for each repo.
+- Merges into the skillup lock file without overwriting existing entries.
+- Skips skills with unsupported `sourceType` (non-GitHub).

skillup-0.4.0/docs/development.md

@@ -0,0 +1,65 @@
+# Development
+
+## Setup
+
+This project uses [uv](https://github.com/astral-sh/uv) for dependency management.
+
+```bash
+git clone https://github.com/bmsuisse/skillup
+cd skillup
+uv sync
+```
+
+## Running locally
+
+```bash
+uv run skillup --help
+```
+
+## Tests
+
+```bash
+uv run pytest
+```
+
+Run a specific test file:
+
+```bash
+uv run pytest tests/test_cli.py
+```
+
+## Type checking
+
+```bash
+uv run pyright skillup
+```
+
+## Project structure
+
+```
+skillup/
+├── skillup/
+│   ├── cli.py        # Typer commands (add, remove, update, sync, migrate)
+│   ├── install.py    # Download, unzip, and copy skill folders
+│   ├── lock.py       # Lock file read/write and source normalization
+│   ├── settings.py   # Paths and environment config
+│   └── github.py     # GitHub release/branch resolution
+├── tests/
+├── docs/             # This documentation (built with Zensical)
+├── zensical.toml     # Docs config
+└── pyproject.toml
+```
+
+## Building the docs locally
+
+```bash
+pip install zensical
+zensical serve       # live-reload dev server
+zensical build       # static output → site/
+```
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SKILLUP_CACHE_DIR` | system temp | Override the download cache directory. |