Skills CLI Agent Rules

A command-line tool for discovering, installing, and updating agent skills.

Overview

The Skills CLI guide maps each command to its implementation and walks through the update algorithm. It also covers lockfile compatibility, why tests invoke the current CLI directly, and how supported-agent metadata is generated.

Architecture as narrative Generated file guards

Documents

└──

Techniques in this file

01 / Architecture as narrative

Keep fallback credentials inside GitHub CLI

The update algorithm starts anonymously, then checks explicit tokens, and finally delegates to GitHub CLI. The file states that the CLI credential stays inside that tool rather than being exported into the environment.

843. For each skill, call `fetchSkillFolderHash(source, skillPath, token)`. Tree requests start anonymously, then use an explicit `GITHUB_TOKEN`/`GH_TOKEN`, then `gh api` without exporting the GitHub CLI credential.

02 / Architecture as narrative

Explain the exact unit used to detect an update

Updates compare the latest skill folder tree SHA against the stored hash. That gives agents a precise model of what changed, rather than treating a repository commit as equivalent to a skill update.

865. Compare latest folder tree SHA with lock file `skillFolderHash`; mismatch means update available

Give the reason for bypassing a package launcher

Reinstallation invokes the current CLI entry point directly. The guide calls out nested npm exec and npx behavior as the problem that this choice avoids.

876. `skills update` reinstalls changed skills by invoking the current CLI entrypoint directly (`node <repo>/bin/cli.mjs add <source-tree-url> -g -y`) to avoid nested npm exec/npx behavior

04 / Generated file guards

Generate downstream metadata after adding an agent

The new-agent checklist starts with one source definition, then runs validation and synchronization. README content and package keywords are updated by that workflow rather than as independent edits.

1693. Run `pnpm run -C scripts sync-agents.ts` to update README.md and package keywords

Ideas for your repo

Document authentication fallback order and credential boundaries.
Name the precise content unit used for change detection.
Explain why a command bypasses familiar launch tooling.
Generate repeated metadata from one source definition.