Skip to content
GSKILL

Add a skill from Git

Add a skill hosted in a Git repository, pinning it to a version constraint, branch/tag, or exact commit. GSKILL resolves a floating reference to an immutable commit before writing the lockfile, so the install is reproducible.

This guide is verified manually against a real Git remote; the example uses a placeholder source.

Before you start

Section titled “Before you start”
  • A project with an agent marker (gskill add initializes the rest automatically).
  • Network access to the Git host (or a warm cache — see Work offline).
  • A system git binary on PATH (gskill doctor checks this).

Steps

Section titled “Steps”
Terminal window
# Track a semver range (recommended):
gskill add github.com/<org>/<repo>/<skill> --version '^1.0.0'


# Or pin to a branch/tag:
gskill add github.com/<org>/<repo>/<skill> --ref main


# Or pin to an exact commit:
gskill add github.com/<org>/<repo>/<skill> --commit <sha>

Expected result

Section titled “Expected result”
  • GSKILL resolves the source, fetches it once into the clone cache, writes the skill into .agents/skills/<name>/ with a relative agent link, and records both intent (the gskill block) and resolved reality (skills-lock.json) — including the exact commit and content hash.
  • A mutable reference (like a branch) is resolved to an immutable commit in the lock and flagged as mutable.
  • gskill add exits 0. Adding a skill whose key already exists errors and points you to update or --force.
  • git status now lists .agents/skills/<name>/ and the agent link (e.g. .claude/skills/<name>) as addable alongside skills-lock.json — commit them; the content belongs in the repository.

See also

Section titled “See also”