English · 简体中文

ghs

Use a public GitHub-hosted Agent Skill for one task—without installing the remote Skill or cloning its repository.

Illustrative session; the remote Skill and the agent determine the actual response.

Install ghs

ghs itself must be installed once as a local Codex Skill. The “without installing” promise refers to the remote Skill you invoke afterward.

On macOS, Linux, or WSL:

mkdir -p ~/.codex/skills
git clone https://github.com/ninggele/ghs.git ~/.codex/skills/ghs

On Windows PowerShell:

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex\skills" | Out-Null
git clone https://github.com/ninggele/ghs.git "$env:USERPROFILE\.codex\skills\ghs"

Start a new Codex task after installation, then invoke $ghs as shown below. The expected entry file is ~/.codex/skills/ghs/SKILL.md (or %USERPROFILE%\.codex\skills\ghs\SKILL.md on Windows).

Git is used only by the installation commands above, not by the ghs runtime. If you do not have Git, download the repository’s source ZIP, extract it as a folder named ghs, and place that folder inside your Codex skills directory.

15-second quick start

In a Skill-aware agent chat, type:

$ghs ninggele/socratic-inquiry help me examine this decision

For a Skill in a subdirectory or at a specific ref:

$ghs owner/repo/skills/poster@v1.2.0 make a launch poster

That is the whole user-facing workflow. ghs loads the remote SKILL.md, applies it to the rest of the prompt, and fetches supporting files only if the selected workflow actually needs them.

What it does

GitHub reference
      ↓
normalize and validate
      ↓
load public SKILL.md over HTTPS
      ↓
validate frontmatter and trusted cache metadata
      ↓
follow the Skill for this task
      ↓
fetch individual referenced resources only when needed

Accepted input includes:

• owner/repo
• owner/repo/path/to/skill
• owner/repo/path/to/skill@tag-or-branch
• gh:owner/repo/path@ref
• ordinary public GitHub repository, tree, blob, raw, or SKILL.md URLs

If a branch or tag contains /, use the compact form, for example owner/repo/path@feature/name; GitHub tree URLs are ambiguous in that case.

Security model

Remote Skills are untrusted third-party instructions. ghs narrows the retrieval surface, but it cannot make an untrusted workflow inherently safe.

• Narrow network scope. The fast path makes a direct HTTPS request only to raw.githubusercontent.com, refuses redirects, and disables user curl configuration while preserving proxy settings.
• Strict input handling. Repository references and resource paths use an allowlist. They are passed as separate process arguments; raw prompt text is never interpolated into the loader command.
• Progressive retrieval. Startup fetches only SKILL.md. Scripts, references, templates, and assets are fetched one file at a time when the active workflow requires them. The loader does not clone or scan the whole repository at startup.
• Fail-closed cache. Cache entries must match the source and URL, be owned by the current user, have restrictive permissions, and pass a SHA-256 content check plus frontmatter validation.
• Bounded downloads. SKILL.md is limited to 1 MiB; each supporting resource is limited to 25 MiB.
• No downloaded code execution by the loader. The loader only retrieves files. The agent must inspect third-party code in the actual execution chain before running it and must still obey its normal permission boundaries.
• No credentials. The loader supports public GitHub content only and does not read Git credentials, GitHub CLI credentials, SSH keys, or tokens.
• No telemetry. ghs does not send usage events. Network traffic consists of the requested public GitHub content and ordinary HTTP validation headers.

Branches, tags, and HEAD use a one-hour cache TTL. An exact 40-character commit SHA is treated as immutable. Pin a reviewed commit when reproducibility matters.

Dependencies and compatibility

Requirement	Notes
Skill-aware agent host	Must be able to load this local Skill and run a command.
Python 3.9+	Standard library only; no pip packages and no PyYAML.
curl	Must support HTTPS and be available on PATH.
Network	raw.githubusercontent.com must be reachable on a cache miss or refresh.
Temporary storage	The current user must be able to create private files in the system temp directory.

Git, GitHub CLI, Node.js, npm, and Docker are not required. The cache locking implementation supports POSIX (fcntl) and Windows (msvcrt). Native Windows hosts also need a python3 command on PATH; WSL follows the POSIX path.

The built-in frontmatter reader intentionally implements a small, safe subset needed by Agent Skills: top-level name and description string fields, quotes, comments, block strings, and unrelated nested metadata. YAML tags, anchors, flow collections, duplicate top-level keys, and non-string required fields are rejected.

ghs vs. npx skills use

Both tools can use a Skill without permanently installing that remote Skill. They optimize for different environments.

	ghs	npx skills use
Primary interface	A compact invocation inside the current agent chat	A general-purpose terminal CLI that prints a prompt or launches a supported agent
Runtime	Python 3.9+ and curl	Node.js and npx
Sources	Public GitHub repositories and paths	GitHub, GitLab, generic Git URLs, local paths, and direct downloads
Private repositories	No	Yes, through configured Git/gh/SSH/token authentication
Retrieval strategy	One SKILL.md, then individual resources on demand	Resolves like skills add and materializes the selected Skill files in a temporary directory
Agent coverage	Depends on the host understanding this local Skill and allowing commands	Designed for many named coding agents; can emit a prompt for other consumers
Skill discovery and lifecycle	Minimal; focused on one explicit remote Skill	Includes find, list, add, update, and remove workflows
Credentials	Never consulted	Can use configured credentials for private sources
Telemetry	None	Anonymous telemetry is documented as enabled by default and can be disabled
Best fit	Lowest-dependency, public-GitHub, in-chat use with narrow retrieval	Broad source support, private repositories, multi-agent workflows, and Skill management

The comparison was checked against the upstream vercel-labs/skills documentation on 2026-09-03. See its sections on private repositories and telemetry for the current behavior. ghs is a focused alternative, not a drop-in replacement for the broader skills CLI.

Loader details

The bundled loader can also be run directly:

python3 scripts/fetch_skill.py -- owner/repo/path@ref

Fetch one resource relative to the remote Skill directory:

python3 scripts/fetch_skill.py \
  --resource references/guide.md \
  -- owner/repo/path@ref

The loader prints the full SKILL.md to stdout. Cache status (hit, miss, validated, or an explicitly allowed stale) is written to stderr.

Limitations

• Public GitHub only; no authenticated or private repositories.
• It is not a package manager and does not install or update Skills globally.
• A remote Skill may require tools or libraries beyond the loader's own two dependencies. ghs does not install those dependencies silently.
• Dynamic or broad resource dependency graphs may require a local checkout.
• Remote instructions remain untrusted even when transport and cache checks pass.

License

ghs is available under the MIT License.