Skip to content

fix: make the skills installer work on a clean Mac, add community skills and selection flags#46

Merged
DevOpsAIguru123 merged 3 commits into
mainfrom
fix/skills-installer-catalog-json
Jul 19, 2026
Merged

fix: make the skills installer work on a clean Mac, add community skills and selection flags#46
DevOpsAIguru123 merged 3 commits into
mainfrom
fix/skills-installer-catalog-json

Conversation

@DevOpsAIguru123

Copy link
Copy Markdown
Owner

Why

The install command in the README fails on a clean Mac:

$ /usr/bin/python3 scripts/install_skills.py --agent claude-code --source all --dry-run
Reading the catalog needs PyYAML. Either 'pip install pyyaml' or pass --source owner/repo

install.sh requires python3, macOS's /usr/bin/python3 has no PyYAML, and --source all is the one path that reads the catalog. Anyone following the documented instructions on a stock interpreter hit this.

Two related problems turned up while fixing it: community skills were unreachable by any command, and one official source was undocumented.

What changed

The PyYAML failure. Adds data/catalog.json, a generated stdlib-readable projection of the skill entries in data/repos.yaml, read in preference to the YAML. PyYAML is now only a fallback. All 12 install/ scripts fetch it alongside repos.yaml — that is the step that gets the fix to users. scripts/sync_catalog_json.py regenerates it and CI checks it, mirroring the existing sync_readme_counts.py pattern.

Community skills were uninstallable. CATALOG_CATEGORY was a single hardcoded string, so the three community-agent-skills entries could not be selected by any command.

Selection flags. Picking a whole set previously required knowing that --source doubles as a keyword argument:

Flag Installs
--official 361 skills
--community 26 skills
--all 387 skills

The flags compose, so --official --community equals --all. --source owner/repo still works for a single repo. Note --source all remains a published alias for official and so, unlike the --all flag, excludes community skills — both catalog docs call that out. Combining --source with a selection flag is rejected rather than silently resolved.

TLS from a virtualenv. A python.org build looks for a cert.pem inside its own framework directory that does not exist until Install Certificates.command has been run, and a venv created from one inherits that empty store, failing every download with CERTIFICATE_VERIFY_FAILED. _ssl_context now tries certifi, then the interpreter's own store, then the CA bundle the OS ships. An empty store is detectable via get_ca_certs() with no network call, so the healthy path is unchanged.

Docs. harness/harness-skills had no section at all despite being one of five official sources. Every count in the catalog doc was stale — Google 72→80, Microsoft 191→188, Azure 33→32, Azure DevOps 6→7, Google cloud filter 59→67, analytics 2→3, Microsoft core skills 13→11. All re-measured and verified against live downloads. Adds docs/community-skills-catalog.md.

Verification

Run on macOS 26.2 (arm64).

  • The failing command above now resolves 361 skills on /usr/bin/python3.
  • Clean-Mac simulation — stripped environment, no virtualenv, PyYAML confirmed absent — installs 26 real skill folders.
  • The genuine install.sh run end to end against a local HTTP server (since these changes are not on main yet): fetches all three files including catalog.json, installs 26 skills, idempotent on re-run.
  • All six agent installers resolve to their correct skills directories; install/all hits all five.
  • All 20 documented commands checked against live downloads; every stated count matches.
  • An interpreter whose default context loads 0 certs went from failing outright to installing 26 skills, picking up 128 certs from /etc/ssl/cert.pem.
  • Tests 45 → 60. New regression tests were mutation-checked: disabling the catalog.json branch fails three of them, disabling the empty-store check fails the TLS fallback test.

Not verified

  • Windows. PowerShell is not installed on the test machine, so install.ps1 has had static checks only (same three fetches, @args splat intact). It is unaffected by the TLS change, since Invoke-WebRequest uses the OS trust store.
  • Linux. Should behave identically, but untested here. The Debian, RHEL and SUSE CA bundle paths are included on that basis.
  • Skill counts in the docs are point-in-time; upstream repos change.

Vinod V added 3 commits July 18, 2026 22:50
The README's headline command failed on a clean machine:

    $ /usr/bin/python3 scripts/install_skills.py --source all --dry-run
    Reading the catalog needs PyYAML.

install.sh requires python3, macOS's /usr/bin/python3 has no PyYAML, and
--source all is the one path that reads the catalog. Anyone following the
documented instructions on a stock interpreter hit this.

Add data/catalog.json, a generated stdlib-readable projection of the skill
entries in data/repos.yaml, and read it in preference to the YAML. PyYAML
is now only a fallback. All 12 install/ scripts fetch it alongside repos.yaml,
which is what gets the fix to users. scripts/sync_catalog_json.py regenerates
it and CI checks it, mirroring sync_readme_counts.py.

Community skills were also unreachable: CATALOG_CATEGORY was a single
hardcoded string, so the three community-agent-skills entries could not be
installed by any command. --source now takes official, community, or
everything. 'all' stays an alias for 'official' rather than silently widening
what an already-published command installs.

Docs: harness/harness-skills had no section at all, and every skill count in
the catalog doc was stale (google 72->80, microsoft 191->188, azure 33->32,
azure devops 6->7). All counts re-measured with --list and verified against
real downloads. Adds docs/community-skills-catalog.md.

Verified: the failing command now resolves 361 skills on /usr/bin/python3;
official/community/everything return 361/26/387; a real install of the 26
community skills into a scratch dir produces 26 SKILL.md folders and is
idempotent on re-run. Windows untested locally (this machine is macOS).
Selecting a whole set required knowing that --source doubles as a keyword
argument (--source official). Promote that to explicit flags, which is what
the install commands now use:

    install.sh --official     361 skills
    install.sh --community     26 skills
    install.sh --all          387 skills

The flags compose, so --official --community is the same as --all.

--source keeps working for a specific repo (--source google/skills) and still
accepts the official/community/everything keywords. Note --source all remains
a published alias for official and so, unlike the --all flag, excludes
community skills; both catalog docs call that difference out. Combining
--source with a selection flag is rejected rather than silently resolved.

The 12 install/ scripts forward arguments verbatim, so the flags work through
them unchanged; only their header hints needed updating.
…icates

Running the installer from a virtualenv could fail every download with
CERTIFICATE_VERIFY_FAILED. A python.org build looks for a cert.pem inside its
own framework directory that does not exist until "Install Certificates.command"
has been run, and a venv created from one inherits that empty store. certifi is
the existing fallback, but a bare venv does not have it either.

_ssl_context now tries certifi, then the interpreter's own store, then the CA
bundle the OS ships (/etc/ssl/cert.pem on macOS, plus the usual Debian, RHEL and
SUSE paths). An empty store is detectable with get_ca_certs() and no network
call, so the healthy case is unchanged.

If TLS still fails, the error now names the interpreter and says how to fix it
rather than surfacing a bare urllib traceback.

Verified on macOS 26.2: an interpreter whose default context loads 0 certs went
from failing outright to installing all 26 community skills, picking up 128
certs from /etc/ssl/cert.pem. /usr/bin/python3, which loads 128 certs on its
own, is unaffected.
@DevOpsAIguru123
DevOpsAIguru123 merged commit 1cd739f into main Jul 19, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant