Build an Agent with a Skill

A Skill is a directory containing a SKILL.md instruction file and optional resources or scripts. It tells an Agent when and how to use a capability.

Before you start

Create and activate a virtual environment, then install Akasha:

uv venv --python 3.11

# macOS / Linux
source .venv/bin/activate

# Windows PowerShell
# .venv\Scripts\Activate.ps1

uv pip install "akasha-terminal[light]"

This example uses Gemini. Set the key in the same terminal that will run Python:

$env:GEMINI_API_KEY = "your_key"

1. Create the Skill directory

Create this structure next to your Python program:

hello-skill/
├─ SKILL.md
└─ scripts/
   └─ greet.py

Create hello-skill/SKILL.md:

---
name: hello-skill
description: Generate a deterministic greeting with a bundled script.
---

# Hello Skill

Use this skill when the user asks you to greet someone.

1. Execute the bundled Python script at `scripts/greet.py`.
2. Pass exactly one name as its argument.
3. Return the script stdout as the final answer.
4. If it fails, report the exit code and stderr.

Create hello-skill/scripts/greet.py:

import sys


def main() -> None:
    name = sys.argv[1] if len(sys.argv) > 1 else "friend"
    print(f"Hello, {name}! This greeting was generated by the Skill script.")


if __name__ == "__main__":
    main()

2. Load the Skill into an Agent

Create skill_agent.py in the folder containing hello-skill:

from pathlib import Path

import akasha


skill_path = Path("hello-skill").resolve()

agent = akasha.agents(
    model="gemini:gemini-2.5-flash",
    skills=[str(skill_path)],
    stream=False,
)

answer = agent(
    "Use the hello-skill to greet Alice. Follow the Skill instructions "
    "and return the script output."
)
print(answer)

Run it:

python skill_agent.py

The Agent reads the Skill instructions, locates the bundled script, and follows the declared workflow. A Skill is not a replacement for a Tool: a Skill provides instructions and resources, while a Tool exposes a callable operation.

Troubleshooting

• GEMINI_API_KEY missing: set the environment variable in the same terminal that runs Python.
• Skill not found: check that hello-skill/SKILL.md exists and use an absolute path.
• Script fails: run python hello-skill/scripts/greet.py Alice directly and inspect the error.
• Skill is ignored: make the Skill description specific and state the required workflow in SKILL.md.

For a Tool that directly calls a typed Python function, see Build an agent and use tools. For MCP-based tools, see MCP.