Use a GitHub skill

#Complete workflow

1. Choose a public skill

   Choose a repository and the path to a skill file or directory. 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. HTTP 401 and 403 use the single message GitHub access denied or rate limited. There is no retry, backoff, or rate-limit header processing.