GitHub skills

#Declared source

{
  "id": "github:acme%2Fskills:skills%2Freviewer%2FSKILL.md@v1.2.0",
  "name": "reviewer",
  "source": {
    "type": "github",
    "repo": "acme/skills",
    "path": "skills/reviewer/SKILL.md",
    "ref": "v1.2.0"
  }
}

The repo field accepts owner/name or a https://github.com/owner/name URL (with optional .git); the CLI normalizes it to owner/name.

#Path and ref rules

• Each path segment may use only ASCII letters, numbers, periods, underscores, or hyphens. It cannot start with /, contain //, or include . and .. segments. Backslashes are also rejected.
• The ref is optional, may contain up to 160 characters, and uses segments with ASCII letters, numbers, periods, underscores, hyphens, or slashes. It does not accept backslashes, //, or ...

#SKILL.md and the resolved directory

If the declared path ends in SKILL.md (case-insensitive), the CLI resolves its parent directory. The directory is traversed and must contain a file named SKILL.md, also case-insensitive.

#Ref and default branch

Without a ref, the API URL omits that parameter and GitHub resolves the repository's default branch. The CLI warns [warn] <name> uses the mutable default branch (no ref declared). A ref that is not a 40-character hexadecimal SHA also triggers [warn] <name> uses mutable ref '<ref>'; a 40-character hexadecimal SHA is treated as immutable when resolving a 404.

#Limits and security

The GITHUB_TOKEN is optional. Remote content is resolved from the declared source and written as bytes; the CLI does not execute it. HTTP 401 and 403 responses use the single message GitHub access denied or rate limited. There is no retry or backoff.