📖 Full documentation: jjfantini.github.io/humblSKILLS

A personal skill registry and a single-binary Go CLI (humblskills) that installs agentskills.io-format skills into whichever agent platform you use — Claude Code, Cursor, Codex, and friends.

1. Skill registry — a monorepo of agent skills authored in the agentskills.io format with light humblSKILLS frontmatter extensions (requires, platforms, tags, preserve).
2. humblskills CLI — fetches a skill directory and drops it in the right place for your agent platform. Zero servers, zero accounts, zero telemetry.

Recommended: send this to your agent so it loads the published install + CLI SKILL.md and walks through setup on your machine (works from any OS the docs cover):

Read https://jjfantini.github.io/humblSKILLS/getting_started/installation/SKILL.md and install humblskills on this machine following those instructions. When finished, run humblskills doctor and fix anything it reports until it passes.

If you use Homebrew, install and upgrade with:

brew install jjfantini/humbl/humblskills

Formulas live in jjfantini/homebrew-humbl and are bumped automatically by the release workflow. Upgrade with brew upgrade humblskills.

For machines without Homebrew, or for scripted installs:

curl -fsSL https://raw.githubusercontent.com/jjfantini/humblSKILLS/main/scripts/install.sh | sh

Installs to /usr/local/bin by default (uses sudo if needed). Override with INSTALL_DIR:

curl -fsSL https://raw.githubusercontent.com/jjfantini/humblSKILLS/main/scripts/install.sh | INSTALL_DIR=$HOME/.local/bin sh

Pin a specific version with VERSION=0.1.0 sh.

go install github.com/jjfantini/humblSKILLS/cli/cmd/humblskills@latest

Grab the archive for your platform from the releases page (including Windows):

• humblskills_<version>_linux_amd64.tar.gz
• humblskills_<version>_linux_arm64.tar.gz
• humblskills_<version>_macos_amd64.tar.gz
• humblskills_<version>_macos_arm64.tar.gz
• humblskills_<version>_windows_amd64.zip
• humblskills_<version>_windows_arm64.zip

Each release also publishes checksums.txt with SHA-256 sums.

In a terminal, run humblskills or humblskills start to open the interactive dashboard (tile grid with fuzzy search into every command). Use explicit subcommands below for scripts, CI, or non-TTY environments.

humblskills doctor                    # verify the environment
humblskills search                    # browse the registry
humblskills install smart-skill
humblskills list
humblskills update                    # pick which drifted skills to upgrade
humblskills update --all --yes        # non-interactive bulk upgrade
humblskills uninstall smart-skill
humblskills export                    # snapshot installed skills to humblskills.json
humblskills sync                      # install everything in humblskills.json

Point the CLI at any registry, and — when it's backed by a private GitHub repo — give it a token (a GitHub PAT with read access). The token authenticates both the registry.json fetch and each skill download, sent as a Bearer header; it's ignored for file:// registries and the public default.

Durable, no env vars (recommended). Persist the registry URL in your profile and store the token in your OS keychain once — then plain humblskills commands just work:

humblskills profile set registry https://raw.githubusercontent.com/<owner>/<repo>/main/registry.json
humblskills registry login          # prompts for the token (masked); stored in the OS keychain
humblskills search                  # uses the saved registry + token automatically
humblskills install <skill>
humblskills registry logout         # remove the stored token

registry login also accepts the token via --token <t> or piped stdin (echo "$TOK" | humblskills registry login), and falls back to a 0600 file if no keychain is available.

Or ad-hoc / CI, via flags or env vars (highest precedence, in this order: --token → HUMBLSKILLS_TOKEN → keychain → file; and --registry → HUMBLSKILLS_REGISTRY → profile → hosted default):

export HUMBLSKILLS_REGISTRY=https://raw.githubusercontent.com/<owner>/<repo>/main/registry.json
export HUMBLSKILLS_TOKEN=<github token with read access>
humblskills search

Register several registries and search/browse show them together, grouped by registry (each skill tagged with its source). Each registry keeps its own token.

# Shorthand: pass owner/repo (or a github.com URL) — it expands to the raw
# registry.json URL. owner/repo@branch selects a branch.
humblskills registry add public    jjfantini/humblSKILLS
humblskills registry add happyrobot happyrobot-ai/happySKILLS
humblskills registry add                       # no args → prompts for name, URL, and (optional) token
humblskills registry login --name happyrobot   # token for the private one; verifies it can read the registry
humblskills registry list                      # show configured registries + token state
humblskills registry rename happyrobot hr      # rename (moves its stored token too)
humblskills registry add happyrobot <new-url>  # re-add with an existing name to change its URL
humblskills search                             # grouped: "── happyrobot ──" then "── public ──"
humblskills install <skill>                    # resolves to whichever registry has it
humblskills install <skill> --from public      # disambiguate when a name is in several registries
humblskills registry remove happyrobot         # drop it (and its stored token)

Tab-completion (skill names, registry names, --from/--name) works after installing the completion script — e.g. humblskills completion zsh (see humblskills completion --help).

Run bare humblskills registry (or the dashboard's registry tile) to open the interactive registry manager — add, rename, login, logout, remove, and refresh from one screen (falls back to registry list when not on a TTY).

Configured registries also show up in humblskills profile show (under Registries). list tags each installed skill with the registry it came from, update checks each skill against its registry, and doctor reports each registry's reachability, token, and skill count. When none are configured, everything falls back to the single registry above (--registry/HUMBLSKILLS_REGISTRY/profile set registry/hosted default).

humblskills export snapshots the skills you have installed into a humblskills.json file (override with -o). Commit it to a repo, and every teammate runs humblskills sync to install the same set — a single, version-controlled source of truth for "which skills does this project want".

humblskills init                         # scaffold an empty ./humblskills.json to fill in
humblskills init --from-installed        # scaffold it from the skills you already have
humblskills export -o humblskills.json   # write the skillset
humblskills sync                         # install missing skills from ./humblskills.json
humblskills sync path/to/set.json --force  # reinstall everything from a specific file
humblskills sync https://example.com/humblskills.json  # sync from a hosted skillset
humblskills sync --prune                 # also uninstall skills not in the file

init bootstraps a new skillset file (default ./humblskills.json); it writes an empty set to fill in, or seeds it from your installed skills with --from-installed, and refuses to clobber an existing file unless you pass --force.

sync accepts a local path, a file:// URL, or an http(s):// URL, so a team can host one canonical skillset and everyone runs humblskills sync https://…/humblskills.json. It pulls the current registry version of each skill (like install), skips skills already up-to-date, and warns (without failing) about any skill in the file that the registry doesn't know about. Add --prune to make your local set match the file exactly — any installed skill the skillset doesn't list is uninstalled (you're asked to confirm unless --yes). Platforms/scope follow the same rules as install.

Every command accepts --json for machine-readable output and --yes to skip confirmation prompts.

eval runs an up-to-four-arm benchmark of any skill — no_skill vs flat_skill vs flat_skill_wiki vs smart_skill — grades the outputs, and emits a single-file HTML dashboard. For smart skills the same harness runs sessions in order so the brain state (patterns, decisions, log, wiki) carries across sessions and you get a longitudinal trajectory that proves the skill compounds over time. Drop flat_skill_wiki if you only want the 3-arm baseline; include it to separate "brain value" from "static wiki value" in an ablation.

Latest published showcase: adaptive-brand-voice-discovery · 2026-04-20 — a 6-session compounding scenario over 10 idiosyncratic brand-voice rules. On cursor-agent, smart_skill scored pass_rate 0.935 vs no_skill 0.740 (+26.3%) and flat_skill 0.679 (+37.7%), while using 67% fewer tokens than no_skill. Reproduce locally with humblskills eval brand-voice. Full index: live docs · source.

4-arm ablation showcase: indie-launch-copy-iteration — 6 sessions over 13 indie-launch voice rules, three runs per arm (72 sessions total) on claudecode. Separates brain value (smart_skill vs flat_skill_wiki) from wiki value (flat_skill_wiki vs flat_skill) with identical preamble and scaffolding. The cumulative-retention outcome assertion (S5 + S6 violations ≤ 1) passes 3/3 for smart_skill and 0/3 for every other arm. smart_skill hits 43% fewer violations than flat_skill_wiki while using 2.6% fewer tokens and 8.9% less wall time. Surprising finding surfaced by the ablation: flat_skill_wiki is the worst of the four arms — static wiki knowledge adjacent to the task can distract without helping. Reproduce with humblskills eval run smart-humanize-text --scenario indie-launch-copy-iteration. Full analysis: docs/eval/indie-launch-analysis.md.

Six runners ship behind one interface - pick whichever agent you already use, or point an API key directly at the hosted model:

humblskills doctor                          # check runner availability
humblskills eval set-key anthropic          # store key in the OS keyring
humblskills eval runners                    # one-liner per-runner status
humblskills eval                            # dashboard entry → Eval Home TUI
humblskills eval run smart-skill        # non-TUI run
humblskills eval showcase                   # the canonical smart-skill demo
humblskills eval brand-voice                # the adaptive-brand-voice-discovery showcase (3-arm compounding)
humblskills eval ls                         # iterations per skill
humblskills eval prune smart-skill --keep-last 5

Secrets never land in the profile JSON. eval set-key resolves env > OS keyring > $XDG_CONFIG_HOME/humblskills/secrets.json (perm 0600) in that order, and the TUI prompts with a masked input.

Iteration artifacts under $XDG_STATE_HOME/humblskills/evals/<skill>/iteration-N/:

iteration-N/
├── benchmark.json      cross-section stats + deltas
├── trajectory.json     per-session time series (smart arm compounds here)
├── report.html         single-file Plotly dashboard
├── report.md           plaintext mirror (PR-friendly)
├── report.json         machine-readable
├── smart_skill/
│   └── session-NN/
│       ├── outputs/           files the agent wrote
│       ├── transcript.txt     full agent transcript
│       ├── timing.json        tokens + duration + cost
│       ├── metrics.json       tool-call counts + brain reads
│       ├── brain-snapshot-before/   brain state seeded into this session
│       └── brain-snapshot-after/    brain state after this session — feeds N+1
├── flat_skill/...
└── no_skill/...

Iterations are persistent and append-only. humblskills eval prune is the retention knob.

Each skill ships an evals/scenarios.json. Sessions run in order; assertions are either llm (sent to a judge model) or scripted (path_exists, exec, regex, script, json_valid) - scripted beats LLM-judge for determinism. humblskills eval init <skill> scaffolds a template. See skills/smart-skill/evals/ for the canonical example with retention checks across sessions.

Smart skills often accumulate user-owned content over time - raw sources, append-only memory (log.md, decisions.md, patterns.md), LLM-curated wiki pages. By default humblskills update and humblskills install overwrite the skill directory with whatever the registry ships. Skills that need to keep user content around on update declare a preserve list under metadata: in their SKILL.md frontmatter.

Entries are relative paths inside the skill directory. A trailing / makes the entry a directory; anything else is a file. Globs are not supported.

Fresh installs always seed everything from the registry - preserve only kicks in when replacing an existing install. Running humblskills uninstall wipes everything, including preserved content.

---
name: my-smart-skill
description: ...
metadata:
  version: 0.2.0
  preserve:
    - references/log.md
    - references/patterns.md
    - references/decisions.md
    - references/raw/
    - references/wiki/
---

Skill authors who declare a preserve directory should note in their skill docs that any files shipped inside that directory may be overwritten on update - that's the deep-merge contract.

The preserve list under metadata.preserve in the registry is the seed

• what ships on first install. After that, the list belongs to you. humblskills update reads metadata.preserve from the installed SKILL.md on disk (per target, so each platform + scope is independent), not from the upstream registry entry.

That means:

• Add an entry locally -> that path survives your next humblskills update, even if upstream never listed it.
• Remove an entry locally -> that path gets overwritten by upstream bytes on the next update.
• Empty metadata.preserve -> the update is a clean overwrite for every path.

Use this to pin author-shipped files in place, protect notes you stash inside the skill directory, or stop preserving a directory the author reorganized.

Only metadata.preserve is treated as user-owned. Top-level agent-skills fields (name, description, and the rest), every other key under metadata: (version, requires, platforms, tags, and so on), and the full markdown body flow through from upstream on every update. So when the author ships a new description, version bump, or prose rewrite, you get it; your preserve list rides along untouched. This also means your preserve edits survive indefinitely - you don't need to re-edit after each update, because the rewritten SKILL.md carries your list forward.

A few nuances:

• If you'd rather freeze the entire SKILL.md (maybe you've made prose edits you don't want overwritten), add SKILL.md itself to metadata.preserve. That makes user-wins on the file, so upstream changes to the description/version/body stop flowing - opt-in only.
• If the installed SKILL.md is missing, unparseable, or carries an invalid preserve list (e.g. a .. traversal), the engine falls back to the registry's list and prints a warning. It won't wipe your data over broken YAML.
• The YAML round-trip on update normalizes whitespace and drops comments inside the frontmatter block. Keys and their values stay intact; only formatting inside the YAML mapping is rewritten.

humblskills update --force <skill>          # bypass local preserve, reinstall cleanly
humblskills install --force <skill>         # same effect outside update flow
humblskills uninstall <skill> && humblskills install <skill>   # equivalent

--force ignores your local preserve edits and replaces the on-disk skill with exactly what the registry ships. This is the escape hatch for "throw away my customizations and give me the author's version."

The CLI source lives under cli/ as a nested Go module.

make build           # builds ./bin/humblskills
make test            # runs go test ./...
make registry        # regenerates registry.json from skills/ + embedded adapters

Releases are cut by pushing a semver tag (e.g. git tag v0.1.0 && git push origin v0.1.0); the workflow in .github/workflows/release.yml runs GoReleaser, uploads archives + checksums to GitHub Releases, and also pushes a sibling cli/v0.1.0 tag so go install works against the nested module.

Content is licensed under CC-BY-4.0. If Go source code licensing becomes a concern later, the CLI code under cli/ may be dual-licensed MIT — but that has not been done yet.