v1.0.0

coding

amd@amd⭐ 1.6k stars· last commit 2d ago· 580 open issues

Work on a codebase — read, search, edit and verify source files. Use when the user asks to fix a bug, add a feature, refactor, explain code, make a test pass, or change anything in a repository. Covers finding the right file, editing safely, and proving the change works before reporting it.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

7.4/10
Verified
Oct 12, 2026

// RATINGS

⭐GitHub Stars
⭐⭐⭐⭐⭐ 1.6k on GitHubGitHub ↗

Very popular

🟢ProSkills ScoreAI Verified
7.4/10
📍

Not yet listed on ClawHub or SkillsMP

// README

GAIA: Local AI Agents for AMD Ryzen AI

GAIA CLI Tests Latest Release PyPI GitHub downloads OS - Windows OS - Linux Python 3.10+ License: MIT Discord

GAIA is AMD's open-source agent factory. It uses coding-agent skills, evals and an auto-fix loop to improve and build agent harnesses that run locally by default on AMD Ryzen AI hardware. Local inference keeps your data private, avoids cloud usage fees, and supports air-gapped deployment with hardware-accelerated performance.

Anyone can build an agent harness with GAIA. The GAIA agent is the one we built to show what it can do: conversation, documents, data, web, memory and skills in one agent.

I want to...Start here
Use GAIA: run the flagship agent in the desktop app or terminalInstall GAIA, then the GAIA agent guide
Build with GAIA: make an agent harness with skills, evals and the SDKComposing skills, Agent evals, SDK reference

The terminal UI also supports optional Fireworks AI and AMD LLM Gateway chat through Lemonade. Use /provider to connect and choose a model; cloud chat sends conversation history to the selected provider. See AI provider setup. To make GAIA refuse every cloud AI model, run gaia config set network_policy local_ai_only.


Download

Download for Windows Download for macOS Download for Linux

One download for users: on Windows, one installer offers the desktop app, the terminal, or both. See Install GAIA for every platform, and its For developers section for script, pip/uv and source installs.

Note (Email agent): the Email agent installs with gaia hub install email, which fetches a binary sidecar into your GAIA agents directory — no PyPI wheel and no Node.js toolchain required. An npm client is also published for embedding the agent in a JS/TS app.


Why GAIA?

FeatureDescription
Local InferenceRun models on your machine for sensitive workloads and air-gapped deployments
No Cloud Inference FeesLocal models require no API subscription; optional cloud providers have their own pricing
Privacy-FirstHIPAA-compliant, GDPR-friendly—ideal for healthcare, finance, and enterprise
Ryzen AI OptimizedHardware-accelerated inference using NPU + iGPU on AMD Ryzen AI processors

Build with GAIA

The SDK is the base layer under the GAIA agent. A minimal harness is a class with a prompt and tools:

from gaia.agents.base.agent import Agent
from gaia.agents.base.tools import tool

class MyAgent(Agent):
    """A simple agent with custom tools."""

    def _get_system_prompt(self) -> str:
        return "You are a helpful assistant."

    def _register_tools(self):
        @tool
        def get_weather(city: str) -> dict:
            """Get weather for a city."""
            return {"city": city, "temperature": 72, "conditions": "Sunny"}

agent = MyAgent()
result = agent.process_query("What's the weather in Austin?")
print(result)

See the full quickstart guide →


Key Capabilities

  • Agent Factory — Skills, an eval benchmark, and gaia eval agent --fix, which patches failing scenarios and re-runs them (guide)
  • Agent SDK — Base class with tool orchestration, state management, and error recovery
  • Agent UI — Privacy-first desktop app with chat, file browser, document indexing, and tool execution
  • RAG System — Document indexing and semantic search for Q&A over 50+ file formats
  • Voice Integration — Whisper ASR + Kokoro TTS for speech interaction (P0 enabling technology)
  • Vision Models — Extract text from images with Qwen3-VL-4B
  • MCP Integration — Connect to any MCP server for external tool access
  • Skills — Extend the GAIA agent with a SKILL.md, no code required (guide)

C++ Framework

A C++17 port of the GAIA base agent framework is available under cpp/. It implements the same agent loop, tool registry, and MCP client interface without any Python dependency — suitable for embedding in native applications or resource-constrained environments.

#include <gaia/agent.h>

class MyAgent : public gaia::Agent {
protected:
    std::string getSystemPrompt() const override {
        return "You are a helpful assistant.";
    }
};

C++ build and usage instructions →


Quick Install

pip install amd-gaia

For complete setup instructions including Lemonade Server, see the Quickstart Guide.


System Requirements

RequirementMinimumRecommended
ProcessorAMD Ryzen AI 300-seriesAMD Ryzen AI Max+ 395
OSWindows 11, Linux-
RAM16GB64GB

Documentation

  • Quickstart — Install GAIA and build a first harness in 10 minutes
  • SDK Reference — Complete API documentation
  • Guides — Chat, Voice, RAG, and more
  • FAQ — Frequently asked questions

Releases

See the full Release Notes on the documentation site, or browse GitHub Releases.

Release Process

To publish a new release (e.g. v0.17.0), create a release PR that updates these 3 files:

#FileWhat to change
1src/gaia/version.pySet __version__ = "0.17.0"
2docs/releases/v0.17.0.mdxCreate release notes (see format guide)
3docs/docs.jsonAdd "releases/v0.17.0" to the Releases tab pages array

Then run `python util/release_versions.py

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • hub/skills/coding/SKILL.md9.6 KB4dd55771f73dupstream ↗
    ---
    name: coding
    description: Work on a codebase — read, search, edit and verify source files. Use when the user asks to fix a bug, add a feature, refactor, explain code, make a test pass, or change anything in a repository. Covers finding the right file, editing safely, and proving the change works before reporting it.
    license: MIT
    version: 0.2.2
    metadata:
      gaia:
        security_tier: community
        permissions:
          - shell:execute:pytest
          - shell:execute:python
          - shell:execute:python3
          - shell:execute:git
        tools_required:
          - read_file
          - edit_file
          - search_file_content
          - search_code_index
          - run_python
          - run_shell_command
        provenance:
          source: starter-pack
    ---
    
    # Coding
    
    Changing code is different from answering a question: you can be *confidently
    wrong for hours* because the answer looked plausible. Everything below exists to
    close that gap.
    
    ## Find the code before you change it
    
    You have two searches and they answer different questions:
    
    - **`search_file_content`** — grep. Use it when you know the string: a function
      name, an error message, a config key. Fastest way to find every call site.
    - **`search_code_index`** — semantic. Use it when you know the *behaviour* but
      not the name: "where do we decide which model to load". Run `index_codebase`
      once for the repo first; `get_index_status` says whether it is ready.
    
    Grep first when you have an exact token — it is instant and exhaustive. Reach
    for the semantic index when grep returns nothing useful because you are
    guessing at names.
    
    ## Read the file before you edit it
    
    Not the top of it — use `read_file` on the part you are changing, plus enough
    around it to see what else depends on it. An edit written from memory of a
    similar file is how you delete someone's special case.
    
    `edit_file` replaces an exact string. If it fails, the file is not what you
    thought: **re-read it**, do not retry with a guess. Never fall back to
    rewriting the whole file to get past a failed edit — that silently reverts
    anything else in it and rewrites every line's endings, turning a two-line change
    into a whole-file diff.
    
    ## Reproduce it first, then fix it
    
    Run the failing thing and read the actual output before changing anything. A bug
    you have not reproduced is a bug you are guessing at, and the fix for a guess
    usually lands somewhere real code was fine.
    
    This also gives you the *before* state. Without it you cannot tell whether you
    fixed the problem or merely changed the symptom.
    
    ## Prove it, then say it
    
    **A test you did not run is not a test that passed.** Tracing the logic in your
    head is not verification — it is the same reasoning that produced the bug.
    
    This skill grants `pytest` and `python` **when they are installed on PATH**, so
    run the suite directly with `run_shell_command`. Prefer the `python -m` spelling
    — it puts the project's own directory on `sys.path`, so it works on a checkout
    that was never installed, where bare `pytest` fails to import the project:
    
    ```
    python -m pytest -q tests/
    python -m pytest -x -k discount tests/test_cart.py
    pytest -q tests/                     # same grant, same rules; for an installed project
    python util/lint.py --all --fix      # or whatever the project's own runner is
    ```
    
    `python -m` adds the current directory to the import path, not `src/`. For a
    project whose package lives under `src/`, scope the path to that one command:
    
    ```
    PYTHONPATH=src python -m pytest -q tests/
    ```
    
    Where only `python3` exists, `python3 -m pytest` works the same way.
    
    pytest often lives only in the project's virtualenv, so it is not on PATH. The
    skill still loads, but without the `pytest` grant — and `python -m pytest` is
    judged as `pytest`, so that spelling is refused too. Run the suite with
    `execute_python_file` instead, which works wherever pytest is importable:
    
    ```python
    import sys, pytest
    sys.exit(pytest.main(["-q", "tests/"]))
    ```
    
    Loading this skill grants `pytest` and `python <script.py>` execution without
    another prompt. Tests and scripts are trusted project code: they can write
    files, access the network, and launch other programs, including commands the
    direct CLI policy refuses. These grants do not sandbox their effects. The
    separate `execute_python_file` tool still requires per-call approval.
    
    `python -c "..."` is outside the grant, which requires a reviewable file in the
    checkout — the user would have to approve that exact line once. Write new code to a file first so the diff shows it, and review what
    it does before executing it. For a one-off calculation that should not land in
    the repository at all, `run_python` takes the snippet through the tool path
    instead — it asks for approval on every call rather than riding this grant.
    
    The rest of the grant is narrow on purpose. `--pdb` would hang waiting for a
    debugger nobody can answer, `-p <plugin>` imports arbitrary code, `--junitxml`
    writes outside the run. `python -m pytest --pdb` is refused for exactly the same
    reason `pytest --pdb` is — `-m` is not a way around a rule.
    
    For a suite `pytest` cannot drive — npm, go, cargo, make — you have no grant by
    default. GAIA ships policies for `npm`, `go`, `uv`, `pip`, `black`, `isort` and
    `ruff`, so a project skill can declare the one it needs (`shell:execute:npm`)
    and get the same three-tier treatment. `make` has no policy and will not get
    one: its argument is a target in a file, so "run `make test`" means "run
    whatever the Makefile says", which no approval prompt can honestly describe.
    
    If you could not run something, say so plainly — *"I could not execute the
    suite, so this is unverified"* — rather than implying it passed.
    
    ## Do not break what was already working
    
    Run the WHOLE suite, not just the test you were asked about. A fix that repairs
    one test and breaks two is a worse state than you started in, and you will not
    notice if you only look at the one.
    
    If something else fails, that is now your problem, whether or not you caused it.
    Say which of the two it is.
    
    ## Committing: yours to propose, theirs to approve
    
    You have `git`. Reads — `status`, `diff`, `log`, `show`, `branch` — run straight
    through, and you should use them constantly: `git diff` before you report a
    change is the cheapest possible check that the diff is only what you meant.
    
    `add`, `commit`, `checkout`, `switch`, and `restore` require approval of the
    exact command before running. Write the commit message as if it is the only
    thing the reviewer reads, because for a squashed PR it is.
    
    `stash list` and `stash show` are reads. `stash push`, `stash save`, `stash
    apply`, and `stash pop` require approval; bare `stash`, `stash drop`, and
    `stash clear` are refused.
    
    The direct Git policy refuses these commands entirely: `push`, `fetch`, `pull`,
    `clone`, `merge`, `cherry-pick`, `revert`, `bisect`, `rebase`, `rm`, `mv`,
    `reset`, `clean`, `gc`, `tag`, `apply`, `format-patch`, and `config`. It also
    refuses `commit --amend` and `reset --hard`; these are not alternate spellings.
    For remote commands, tell the user the exact command. For history-changing
    commands, stop at the boundary and return the conflict state; the user may run
    `merge --continue`, `rebase --continue`, or the corresponding abort command.
    For `rm`, `mv`, `reset`, `clean`, `gc`, and `tag`, ask the user to perform the
    exact change—never substitute a shell command or another Git spelling. Every
    `tag` form, including listing tags, is refused.
    
    Publishing, history rewriting, and destroying uncommitted work are the user's
    to run. When a committed branch wants pushing, **say so and stop** —
    *"committed on `fix/discount`; run `git push -u origin fix/discount` and I will
    open the PR"* — rather than looking for a spelling that gets through.
    
    The supported Git surface is reads (`status`, `diff`, `log`, `show`, `branch`,
    `blame`, `describe`, `rev-parse`, `merge-base`, `ls-files`, `ls-tree`,
    `cat-file`, `grep`, `shortlog`, `help`), local staging and commits (`add`,
    `commit`), approval-gated branch/file operations (`checkout`, `switch`,
    `restore`, `stash`), and the read-only `remote` view. Anything else is refused.
    
    ## Keep the diff to the change
    
    - Fix the bug you were asked about. Do not reformat, rename, reorder imports, or
      "clean up while you're here" — every unrelated line is a line the reviewer has
      to check.
    - Match the file's existing style, even where you would write it differently.
    - Do not add comments narrating what the code does. A comment earns its place by
      explaining a *why* that is not obvious from the code.
    
    ## When you fix one instance, look for the others
    
    The same mistake is rarely alone. A bad `subprocess` call, a missing encoding, a
    wrong default — grep for the pattern once you understand it, and say what you
    found even if you only fixed one. "Fixed here; three more in X, Y, Z" is far
    more useful than a silent single fix.
    
    ## Scratch files are yours, not theirs
    
    Runner scripts and scratch output go in the system temp directory — write them
    there and run them with `execute_python_file`, which does not care where the
    file lives. `python` does: its grant stops at the checkout, so a scratch script
    outside it is `execute_python_file`'s job, not the shell's.
    
    Writing `create_doc.py` and `temp/` into the root of someone's repository leaves
    them in the next `git status`, and they did not ask for them.
    
    ## Reporting a code change
    
    Lead with whether it works, then what changed:
    
    > Both failing tests pass now, and the other six still do.
    >
    > - `apply_discount` was subtracting `amount * percent` instead of
    >   `amount * percent / 100`.
    > - `format_money` used `str(round(...))`, which drops the trailing zero in
    >   `$5.50`.
    
    Name the file and line only when the reader needs it to act. Never claim a test
    run you did not do.
    
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/amd-gaia-hub-skills-coding.md

// REPO STATS

1.6k stars
580 open issues
Last commit: 2d ago