Skip to main content
You can ship a new GAIA capability as a folder with one file in it. Open a pull request into hub/skills/<name>/; once it passes the audit and review, the next final GAIA release publishes it to the hub, signed by AMD. You never handle a signing key or a hub token. A skill is a SKILL.md (a short header plus a procedure written for the model to follow), optionally with a tools.py of Python tools. Reach for a skill when you are teaching the agent how to do something; write a tool when it needs a new ability, and a custom agent only when you need your own process. Format details: Agent Skills.

1. Write it with Claude Code

1

Fork and clone

Fork amd/gaia, clone your fork, and open it in Claude Code. It picks up CLAUDE.md, the working skills in hub/skills/, and the format spec on its own.
2

Ask for the skill

Describe the job, where it goes, and what to follow:
3

Read what it wrote

You are the author of record. Check that the description says when to use the skill, that the steps are ones you would stand behind, and that any tools.py does only what the skill says.

What a skill looks like

The smallest useful SKILL.md:
  • name must equal the folder name (lowercase, hyphens). The hub publishes under name, and gaia skill import installs under it even if the folder differs.
  • description is how the agent decides to use the skill. Say what it does and when.
  • version is required to publish, as MAJOR.MINOR.PATCH; 0.0.0 is refused.
  • license: use MIT, like every skill in the repo.
  • tools_required names tools the agent already has. tools declares Python tools your own tools.py provides; each needs an entry that matches its signature, or the skill will not load. rss-digest is the worked example with a tools.py.

Or write it by hand

This only scaffolds a template: placeholder description and body, version 0.1.0, MIT. --with-tools adds a tools.py stub. Without --dir it writes to ~/.gaia/skills, which is not where a contribution goes. Replace every placeholder.

2. Try it locally

import audits the folder and copies it into ~/.gaia/skills/. A local import is always experimental, whatever the file claims: the tier records what has been verified, not what the author said. That is fine for trying it. A skill that asks for more than the experimental ceiling (network:read and scratch:write) is refused at import, and one that ships code needs --allow-experimental, because that code runs in your agent’s process. Then start gaia chat and ask the agent to load it (“load the csv-quality-report skill and check this file”). The agent’s list_skills and load_skill tools find anything in ~/.gaia/skills/. After you edit the folder, import again with --force.

3. Declare only the permissions you use

Permissions go under metadata.gaia.permissions as <domain>:<level>[:scope], for example network:read or shell:execute:gh. Declare nothing for a skill that only uses tools the agent already has.
  • Keep the list as short as the skill allows. Each extra grant is something a reviewer has to trust and a user has to approve. The audit notes permissions your code never uses.
  • Three tiers cap what a skill may ask for: experimental (network:read and scratch:write), community (adds network:write, mcp:connect, shell:execute:<binary>, and program:run; dangerous grants prompt the user), verified (everything, AMD-audited). Claim community, as every skill in hub/skills/ does.
  • filesystem, database, desktop, and env permissions are refused today: there is no sandbox for them yet.
  • Shell access is scoped to one named program, shell:execute:<binary>, and limited to that program’s allowed subcommands.
The full rules are in Agent Skills and the tier table.

4. Check it before you open the PR

audit is the same engine the PR check runs, and it never executes your code. Your skill must be ALLOW to merge. Publishing refuses anything else, so the PR check fails a REVIEW skill in hub/skills/ and no maintainer label overrides it. To test a tier before you claim it, run gaia skill audit <folder> --tier community.

5. Open the pull request

  1. Add only hub/skills/<name>/ on a branch of your fork and open a PR into main.
  2. Fill in the PR template; see CONTRIBUTING.
  3. The Skill Audit (deterministic gate) check runs on every PR that touches a skill. For a skill in hub/skills/, anything other than ALLOW fails it. The PR comment shows counts and rule ids only; the details stay in the repository’s private Security tab.
  4. A maintainer reviews it: what the instructions and any tools.py actually do, whether the permissions match, and whether the skill is useful and safe to ship under AMD’s signature.
By contributing you license the skill under the repo’s MIT license. Merging is not a tier promotion: the audit verdict and AMD’s signature decide the tier.

6. After it merges

The next final GAIA release runs release_skills.yml, which publishes every skill whose version is not on the hub yet, signed with AMD’s key. GAIA v0.25.4 and later trust that key out of the box. Release candidates do not publish. Once it is live, users find it with gaia skill search, by asking the agent, or at amd-gaia.ai/hub, then gaia skill install <name>. See Starter Skills. Publishing makes it installable; it is not built into the gaia agent unless AMD adds it to the agent’s bundle.

7. Updating a published skill

Hub versions are immutable. Change anything in a published skill, including a typo in tools.py, and bump version: in SKILL.md in the same PR. If you don’t, the release fails for that skill (“already published with different contents”) and the change never reaches users. The audit re-runs on every PR, so a new version earns its verdict again.

Starter Skills

Install skills from the hub, and read the AMD examples

Agent Skills spec

Format, permissions, tiers, and signing