Use a GitHub skill

#Complete workflow

1. Choose a public skill

   Choose a repository and the path to a skill file or directory. The resolved skill root must contain a file named exactly SKILL.md (uppercase); resolution uses the GitHub API and does not execute remote content.

2. Declare repo, path, and ref

   Add an entry with a github source. The repo can be owner/name or a GitHub URL; path must not start with a slash or contain . or .. segments. Prefer a fixed ref to reduce unexpected changes.

   json

   {
     "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"
     },
     "description": "Review code before shipping."
   }

3. Run maleta validate

   bash

   maleta validate --file ./maleta.json

   Validation checks the schema, limits, and source rules without making network requests.

4. Run a dry run

   bash

   maleta install --file ./maleta.json --tool claude --dry-run

   The simulation does not access the network or write files; it shows [dry-run] would install <label> -> <dest>.

5. Install

   bash

   maleta install --file ./maleta.json --tool claude

   The resolved skill is materialized in ~/.claude/skills/<skill.name>/.

#Refs and the default branch

Without a ref, the API URL has no ref 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 classifying a 404 response.

#Optional authentication

• In the CLI, GITHUB_TOKEN is optional and is sent as authorization: Bearer <token> only to api.github.com, github.com, and raw.githubusercontent.com.
• The token reaches the child process through stdin, never through arguments. It is not persisted to disk or printed.
• A host outside this list rejects the token with refusing GitHub token on a non-GitHub host.

#Limits and failures

The GitHub HTTP response can be up to 10 MiB; each skill can total up to 5 MiB and contain up to 200 files; each request has a 10-second timeout; a directory listing at the API cap of 1000 entries is a hard failure. Failures are named distinctively: 401 prints GitHub authentication failed; check GITHUB_TOKEN, a rate-limited 403 prints the reset time and set GITHUB_TOKEN to increase the limit, another 403 prints GitHub access denied; check repository access and GITHUB_TOKEN and a 404 on a private repository suggests set GITHUB_TOKEN. There is no retry or backoff; the rate-limit headers are read to name the failure, not to wait.