Source Code:
hub/skills/ ·
src/gaia/skills/cli.py ·
.github/workflows/skill_audit.ymlhub/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
SKILL.md:
namemust equal the folder name (lowercase, hyphens). The hub publishes undername, andgaia skill importinstalls under it even if the folder differs.descriptionis how the agent decides to use the skill. Say what it does and when.versionis required to publish, asMAJOR.MINOR.PATCH;0.0.0is refused.license: useMIT, like every skill in the repo.tools_requirednames tools the agent already has.toolsdeclares Python tools your owntools.pyprovides; each needs an entry that matches its signature, or the skill will not load.rss-digestis the worked example with atools.py.
Or write it by hand
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 undermetadata.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:readandscratch:write),community(addsnetwork:write,mcp:connect,shell:execute:<binary>, andprogram:run; dangerous grants prompt the user),verified(everything, AMD-audited). Claimcommunity, as every skill inhub/skills/does. filesystem,database,desktop, andenvpermissions 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.
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
- Add only
hub/skills/<name>/on a branch of your fork and open a PR intomain. - Fill in the PR template; see CONTRIBUTING.
- The Skill Audit (deterministic gate) check runs on every PR that touches a
skill. For a skill in
hub/skills/, anything other thanALLOWfails it. The PR comment shows counts and rule ids only; the details stay in the repository’s private Security tab. - A maintainer reviews it: what the instructions and any
tools.pyactually do, whether the permissions match, and whether the skill is useful and safe to ship under AMD’s signature.
6. After it merges
The next final GAIA release runsrelease_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 intools.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