fix: make the skills installer work on a clean Mac, add community skills and selection flags#46
Merged
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The install command in the README fails on a clean Mac:
install.shrequirespython3, macOS's/usr/bin/python3has no PyYAML, and--source allis 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 indata/repos.yaml, read in preference to the YAML. PyYAML is now only a fallback. All 12install/scripts fetch it alongsiderepos.yaml— that is the step that gets the fix to users.scripts/sync_catalog_json.pyregenerates it and CI checks it, mirroring the existingsync_readme_counts.pypattern.Community skills were uninstallable.
CATALOG_CATEGORYwas a single hardcoded string, so the threecommunity-agent-skillsentries could not be selected by any command.Selection flags. Picking a whole set previously required knowing that
--sourcedoubles as a keyword argument:--official--community--allThe flags compose, so
--official --communityequals--all.--source owner/repostill works for a single repo. Note--source allremains a published alias forofficialand so, unlike the--allflag, excludes community skills — both catalog docs call that out. Combining--sourcewith a selection flag is rejected rather than silently resolved.TLS from a virtualenv. A python.org build looks for a
cert.peminside its own framework directory that does not exist untilInstall Certificates.commandhas been run, and a venv created from one inherits that empty store, failing every download withCERTIFICATE_VERIFY_FAILED._ssl_contextnow tries certifi, then the interpreter's own store, then the CA bundle the OS ships. An empty store is detectable viaget_ca_certs()with no network call, so the healthy path is unchanged.Docs.
harness/harness-skillshad 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. Addsdocs/community-skills-catalog.md.Verification
Run on macOS 26.2 (arm64).
/usr/bin/python3.install.shrun end to end against a local HTTP server (since these changes are not onmainyet): fetches all three files includingcatalog.json, installs 26 skills, idempotent on re-run.install/allhits all five./etc/ssl/cert.pem.catalog.jsonbranch fails three of them, disabling the empty-store check fails the TLS fallback test.Not verified
install.ps1has had static checks only (same three fetches,@argssplat intact). It is unaffected by the TLS change, sinceInvoke-WebRequestuses the OS trust store.