feat(skill): install, update and check skills from the brevo-skills catalog

[piyushsarin-sib]

Stacked on #138 (feat/skill-install-any-agent): this PR generalises its skill:cli install --agent … into a brevo skill command group that installs from the brevo-skills catalog. It implements section 3 ("CLI installer") of the skill distribution framework design (brevo-skills PR #4), coding to the catalog shape from section 2 (the mcp block is tolerated when absent).

Commands

Command	Does
brevo skill install [names...]	Installs the named skills, or every catalog skill when none is named; skills marked default are always included
brevo skill update [names...]	Reinstalls installed skills whose version differs from the catalog
brevo skill uninstall [names...]	Removes skills the CLI installed; only directories carrying .brevo-skill.json are touched
brevo skill list	Installed skills per agent, and the catalog's available skills
brevo skill check	Outdated or tampered skills (marker hash vs files on disk); changes nothing; exit 1 when something is off

install and update take --agent claude,codex,gemini|all, --pin <release> (latest clears it), --mcp (runs claude|codex|gemini mcp add when the agent CLI is on the PATH, prints it otherwise), --force, --dry-run, --json. brevo skill:cli install|uninstall keep working as hidden aliases of brevo skill install|uninstall brevo-cli.

Behaviour

• Files are fetched from the release tag and hashed with the catalog contract (sha256 over <path>\0<bytes>\0 in sorted path order, verified against the real catalog.json); a mismatch skips that skill and the run exits 1.
• Platform fit (codex → openai) and min_cli_version filters, each with a message.
• Marker .brevo-skill.json per installed directory; lock file ~/.brevo/skills.lock.json with versions, releases and pins.
• Catalog cached at ~/.brevo/skills-catalog.json, 2 s fetch timeout. After any command, when something is installed and the cache is older than 12 h, one stderr line names the outdated unpinned skills and points to brevo skill update; nothing on disk changes. BREVO_SKILL_AUTOREFRESH=1 reinstalls them right away instead (what earlier releases did for the bundled skill); same skip rules as before (CI, --json, any skill command, BREVO_NO_SKILL_AUTOREFRESH=1); silent on network failure, and a failed attempt is recorded so an offline machine is not retried on every command.
• Offline, brevo skill install brevo-cli installs the bundled agent-context/SKILL.md with the CLI version; other skills fail with the URL and the cached release.
• A malformed catalog is rejected for install/update; list/check fall back to the cached copy.
• BREVO_SKILLS_CATALOG_URL and BREVO_SKILLS_FILES_URL override the sources; BREVO_CLAUDE_HOME/BREVO_AGENTS_HOME unchanged.

Tests

New suites: services/skill-catalog, services/skill, services/skill-mcp, commands/skill/{install,update,uninstall,list,check,aliases}, run against temp homes and a fetch stub serving a release from memory. 1875 tests pass. Coverage of the new files:

File	Stmts	Branch	Funcs	Lines
services/skill.ts	97.3%	86.2%	100%	98.4%
services/skill-catalog.ts	99.4%	88.8%	100%	100%
services/skill-mcp.ts	97.8%	87.5%	88.9%	97.6%
commands/skill/*	99.4%	86.6%	100%	99.3%

Also smoke-tested the public build against the real brevo-skills catalog.json served from a local stub: install/dry-run/list/check/tamper detection/forced update/uninstall/offline fallback all behave as specified (the real brevo-cli entry is skipped on 2.4.0 because its min_cli_version is 2.5.0, which this minor bump will satisfy).

Docs

README (new command group, env vars), agent-context/SKILL.md and agent-context/AGENTS.md (preflight now uses brevo skill check), CLAUDE.md, plus a minor changeset.

Hardening

• Catalog file and skill paths are validated as plain /-joined segments (no .., ., empty segments, backslashes, drive letters, control characters or the marker name) and re-checked at the write site (resolved destination must stay under the skill directory, no symlinked component), skipping the skill with exit 1 otherwise; --mcp resolves the agent CLI to an absolute path from absolute PATH entries only and spawns that path with no shell, printing the command instead of running a Windows .cmd/.bat launcher.

🤖 Generated with Claude Code

[piyushsarin-sib]

Note on CI: the CI workflow only runs for pull requests whose base is main, so this stacked PR (base feat/skill-install-any-agent) reports no checks. The same steps were run locally on this branch: yarn lint, yarn format:check, yarn test:ci (82 suites, 1875 tests), yarn build and node dist/bin/index.js --version, all passing. Checks will run once #138 merges and this PR is retargeted to main.

[sonarqubecloud]

Quality Gate failed

Failed conditions
C Reliability Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE