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"
  }
}

GitHub is one of three skill source types. Use builtin for packaged catalog files or inline when the files travel inside maleta.json and should materialize without a GitHub request.

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 the file that marks the skill root must be named exactly SKILL.md — uppercase. A nested or lowercase marker is rejected with skill path not found: <path> (uppercase SKILL.md is required at the skill root).

#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. Failures are named distinctively — 401 prints GitHub authentication failed; check GITHUB_TOKEN; 403 after the rate limit prints the reset time and set GITHUB_TOKEN to increase the limit; other 403 prints GitHub access denied; check repository access and GITHUB_TOKEN; a 404 on a private repository suggests set GITHUB_TOKEN. There is no retry or backoff. A listing at the API cap of 1000 entries fails with directory listing reached the GitHub API limit (1000 entries).