Agent skill

Agentex

by kid-sid in kid-sid/claude-spellbook

A skill your agent uses when building, wiring, or debugging an Agentex agent — choosing agent type, configuring acp.py and manifest.yaml, using adk.messages or adk.state, or resolving…

MITAuto-check: notesDevelopment

Install Agentex

skills CLI
$ npx skills add kid-sid/claude-spellbook --skill agentex -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install kid-sid/claude-spellbook agentex --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/kid-sid/claude-spellbook.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/agentex .claude/skills/agentex && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
agentex
GitHub stars
189
Token cost
~2.2k tokens
SKILL.md length
718 words
Files
1
Skills in repo
54
Repo updated
First seen
Licence
MIT

At a glance

A skill your agent uses when building, wiring, or debugging an Agentex agent — choosing agent type, configuring acp.py and manifest.yaml, using adk.messages or adk.state, or resolving…

  • Debugging an Agentex agent — choosing agent type
  • SKILL.md covers When to Activate, Agent Types, ACP State Pattern (Async) and Sending Messages (Async), plus 8 more sections
  • Calls uv
  • Configuring acp.py and manifest.yaml

What it does

Agentex is an agent skill from kid-sid/claude-spellbook. Use when building, wiring, or debugging an Agentex agent — choosing agent type, configuring acp.py and manifest.yaml, using adk.messages or adk.state, or resolving Windows-specific setup issues.

Its SKILL.md is about 2.2k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Development. The repository describes itself as: A curated collection of skills, prompts, and workflows that extend Claude's capabilities — your personal grimoire for AI-powered development. The licence is MIT.

When your agent uses it

  • Debugging an Agentex agent — choosing agent type
  • Configuring acp.py and manifest.yaml
  • Using adk.messages
  • Resolving Windows-specific setup issues

Example prompts

  • “/agentex”

Requirements

  • Python 3
  • Docker

What it can do on your machine

Read from SKILL.md and the folder at commit a7c2ac9. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • uv

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use uv, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Agentex loads about 2.2k tokens when it runs. Until then it costs about 51 tokens; SKILL.md has 718 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~51
When it runs · the whole SKILL.md, loaded when a task matches
~2.2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check: notes

The automated check noted patterns worth knowing about, such as sudo or a known installer.

  • NoteMentions a .env fileSKILL.md:21
    etup issues (`uv sync`, port conflicts, `.env` loading)
  • NoteMentions a .env fileSKILL.md:166
    o `localhost` inside Docker | Caused by `.env` overriding Docker network hostnames — needs `override=False` |
  • NoteMentions a .env fileSKILL.md:187
    ## Key Environment Variables (agentex/.env)
  • NoteMentions a .env fileSKILL.md:227
    de Docker** — overriding with the local `.env` file replaces Docker-injected environment variables such as `DATABASE_URL

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from kid-sid/claude-spellbook at commit a7c2ac9, republished under its MIT licence (© kid-sid). 718 words, ~2,235 tokens.

Download SKILL.mdSave it as .claude/skills/agentex/SKILL.md (or your agent's skills folder).
name
agentex
description
Use when building, wiring, or debugging an Agentex agent — choosing agent type, configuring acp.py and manifest.yaml, using adk.messages or adk.state, or resolving Windows-specific setup issues.

Agentex Platform

Agentex is a platform for building and deploying intelligent agents. The repo has two main parts:

  • agentex/ — FastAPI backend + Temporal workflows (runs in Docker)
  • agentex-ui/ — Next.js frontend (runs locally)

Agents are built with the agentex-sdk CLI and run as separate processes that register with the backend.

When to Activate

  • Choosing between sync, async, or Temporal agent type for a new agent
  • Wiring acp.py, manifest.yaml, or run_worker.py for a new agent
  • Using adk.messages, adk.state, or adk.providers in an activity or workflow
  • Debugging ACP protocol issues or agent registration failures
  • Understanding the backend DDD layer boundaries or exception mapping
  • Windows-specific setup issues (uv sync, port conflicts, .env loading)

Agent Types

Sync ACP

One message in, one response out. Stateless.

python
acp = FastACP.create(acp_type="sync")

@acp.on_message_send
async def handle(params: SendMessageParams) -> TaskMessageContent:
    return TextContent(author="agent", content="reply")

Use when: FAQ bots, translation, data lookups, single-turn interactions.

Async ACP (base)

Task lifecycle with persistent state across multiple turns.

python
acp = FastACP.create(acp_type="async", config=AsyncACPConfig(type="base"))

@acp.on_task_create   # called once — initialize state
@acp.on_task_event_send  # called per message — respond via adk.messages.create
@acp.on_task_cancel   # called on cancel — cleanup

Key difference from sync: responses are pushed via adk.messages.create, not returned. State is persisted via adk.state.create / get_by_task_and_agent / update.

Use when: multi-turn conversations, stateful workflows, streaming LLM responses. Warning: race conditions if parallel events arrive — use Temporal for production.

Async ACP + Temporal

Same as Async but every step is a durable Temporal workflow. Survives crashes and restarts.

yaml
# manifest.yaml
agent:
  acp_type: async
  temporal:
    enabled: true

Use when: production agents, long-running tasks, human-in-the-loop, complex multi-step tool chains.


ACP State Pattern (Async)

python
class MyState(BaseModel):
    turn: int
    messages: List[Message]

# Create on task init
await adk.state.create(task_id=..., agent_id=..., state=MyState(...))

# Read on each event
task_state = await adk.state.get_by_task_and_agent(task_id=..., agent_id=...)
state = MyState.model_validate(task_state.state)

# Write back after mutating
await adk.state.update(state_id=task_state.id, task_id=..., agent_id=..., state=state)

Sending Messages (Async)

python
# Echo user message back (so it shows in UI)
await adk.messages.create(task_id=params.task.id, content=params.event.content)

# Send agent reply
await adk.messages.create(
    task_id=params.task.id,
    content=TextContent(author="agent", content="response text"),
)

# Streaming LLM (auto-sends chunks to UI)
await adk.providers.litellm.chat_completion_stream_auto_send(
    task_id=params.task.id,
    llm_config=LLMConfig(model="gpt-4o-mini", messages=state.messages, stream=True),
)

manifest.yaml Structure

yaml
local_development:
  agent:
    port: 8000          # must be unique per agent (8000, 8001, 8002...)
    host_address: host.docker.internal
  paths:
    acp: project/acp.py

agent:
  name: my-agent        # unique name, shown in UI
  acp_type: sync        # or async
  temporal:
    enabled: false
  credentials: []
  env: {}

Backend Architecture

src/
├── api/routes/         # FastAPI endpoints
├── domain/entities/    # Pure Pydantic models
├── domain/use_cases/   # Business logic
├── adapters/crud_store/ # DB adapters (Postgres + MongoDB)
├── adapters/streams/   # Redis SSE streams
└── config/dependencies.py  # Singleton GlobalDependencies

Layer rules:

  • Domain layer has zero framework imports
  • API layer → use cases → domain ← adapters
  • ORM ↔ domain conversion via explicit converter functions — never skip layers

Exceptions:

  • ClientError → 400, ServiceError → 500, ItemDoesNotExist → 404

Windows-Specific Gotchas

ProblemFix
uv sync fails: platform not compatibleAdd "sys_platform == 'win32'" to environments in root pyproject.toml, then uv lock
load_dotenv(override=True) clobbers Docker env varsChange to override=False in environment_variables.py
Local PostgreSQL on port 5432 blocks DockerChange Docker postgres port to 5434:5432 in docker-compose.yml
agentex init Unicode errorSet $env:PYTHONUTF8 = "1" before running
agentex init path has \n in itType short relative name (my-agent), not a full path
source .venv/bin/activate failsUse .venv\Scripts\Activate.ps1 on Windows
Temporal worker connects to localhost inside DockerCaused by .env overriding Docker network hostnames — needs override=False

Ports

PortService
3000Frontend UI
5003FastAPI backend (Swagger at /swagger)
5432Local PostgreSQL (if installed)
5434Docker agentex-postgres (remapped to avoid conflict)
5433Docker Temporal PostgreSQL
6379Redis
7233Temporal server
8080Temporal UI
8000+Agent ACP servers (one port per agent)
27017MongoDB

Key Environment Variables (agentex/.env)

env
ENVIRONMENT=development
DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:5434/agentex
TEMPORAL_ADDRESS=localhost:7233
REDIS_URL=redis://localhost:6379
MONGODB_URI=mongodb://localhost:27017
MONGODB_DATABASE_NAME=agentex
AGENTEX_SERVER_TASK_QUEUE=agentex-server
ALLOWED_ORIGINS=http://localhost:3000
ENABLE_HEALTH_CHECK_WORKFLOW=true

Running Tests

powershell
cd agentex
# Unit tests (no Docker needed)
.\build.ps1 test-unit

# Integration tests (needs Docker infra running)
.\build.ps1 test-integration

# Specific file
.\build.ps1 test -File tests/unit/test_foo.py

Show full SKILL.md (324 more words)Show less

Red Flags

  • Sync ACP for multi-turn conversations — sync agents receive one message and return one reply; they have no state, no turn history, and no mechanism to stream responses; use async ACP (or async + Temporal) for any stateful interaction
  • Handler decorators in acp.py for a Temporal agent — Temporal agents route all ACP events through the workflow engine; registering @acp.on_task_create decorators in acp.py bypasses Temporal and runs handlers outside the durable execution context
  • Returning a response from an async handler instead of using adk.messages.create — async agent handlers are not expected to return a value; the return value is silently discarded and the user sees no reply; push responses explicitly via adk.messages.create
  • Not following load → mutate → save with adk.state — reading state, mutating it in-memory, and then returning without saving means the next signal handler loads stale state; always call adk.state.update after every mutation before returning
  • Omitting get_all_activities() in run_worker.py — ADK built-in activities (messages, state persistence, tracing) are registered via get_all_activities(); omitting it means all adk.messages.create and adk.state.* calls fail at runtime with "activity not found"
  • Two agents sharing the same port in manifest.yaml — each ACP server process binds a port; running two agents with the same local_development.agent.port causes one to fail to start; increment the port for each agent (8000, 8001, 8002, …)
  • load_dotenv(override=True) when running inside Docker — overriding with the local .env file replaces Docker-injected environment variables such as DATABASE_URL and TEMPORAL_ADDRESS with localhost values, breaking service discovery inside the container network

Checklist

  • acp_type chosen correctly in manifest.yaml (sync / async / async + temporal)
  • Temporal agent acp.py has only FastACP.create(acp_type="async", config=TemporalACPConfig(...)) — no handler decorators
  • adk.messages.create used to send responses (not returned from handlers)
  • State follows load → mutate → save pattern via adk.state
  • on_task_create ends with await workflow.wait_condition(lambda: self._done) for Temporal agents
  • get_all_activities() included in worker alongside custom activities
  • Agent port in manifest.yaml is unique across all running agents (8000, 8001, …)
  • Windows: load_dotenv(override=False) to avoid clobbering Docker env vars
  • Domain exceptions (ClientError, ServiceError, ItemDoesNotExist) used — not HTTPException in use cases

© kid-sid, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/agentex of kid-sid/claude-spellbook.

Open the folder on GitHubat commit a7c2ac9

Compare with similar skills

Agentex next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Agentex compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Agentex this skillkid-sid/claude-spellbook189—~2.2kAutomated safety check: NotesMIT
Finishing a Development Branchobra/superpowers296k5 repos~1.9kAutomated safety check: PassMIT
Typescript Advanced Typesrolling-scopes/rsschool-app10k24 repos~4.2kAutomated safety check: PassMPL-2.0
PR Babysitteropeninterpreter/openinterpreter69k3 repos~4.2kAutomated safety check: PassApache-2.0
Code Review ChecklistshareAI-lab/learn-claude-code78k5 repos~1.1kAutomated safety check: PassMIT
Greplooponyx-dot-app/onyx32k4 repos~3.3kAutomated safety check: PassMIT

Similar skills

  • Walks the last step of a branch: confirm tests pass, detect the git environment, ask how to integrate, carry out your choice and clean up the worktree.

    296k GitHub starsUsed in 5 repos~1.9k tokens
    DevelopmentAuto-check passed
  • Typescript Advanced Types

    rolling-scopes/rsschool-app

    Master TypeScript's advanced type system including generics, conditional types, mapped types, template literals, and utility types for building type-safe applications.

    10k GitHub starsUsed in 24 repos~4.2k tokens
    DevelopmentAuto-check passed
  • PR Babysitter

    openinterpreter/openinterpreter

    Watches an open GitHub pull request until it merges, handling review comments, diagnosing CI failures and retrying flaky checks along the way.

    69k GitHub starsUsed in 3 repos~4.2k tokens
    DevelopmentAuto-check passed
  • Code Review Checklist

    shareAI-lab/learn-claude-code

    Reviews code against a five-part checklist covering security, correctness, performance, maintainability and testing, and reports findings in a fixed format.

    78k GitHub starsUsed in 5 repos~1.1k tokens
    DevelopmentAuto-check passed
  • Greploop

    onyx-dot-app/onyx

    Iteratively improves a PR (GitHub), MR (GitLab), or shelved changelist (Perforce) until Greptile gives it a 5/5 confidence score with zero unresolved comments.

    32k GitHub starsUsed in 4 repos~3.3k tokens
    DevelopmentAuto-check passed
  • Guidelines

    akash-network/node

    Behavioral guidelines to reduce common LLM coding mistakes. An agent skill from akash-network/node.

    1.1k GitHub starsUsed in 22 repos~577 tokens
    DevelopmentAuto-check passed

More from kid-sid/claude-spellbook

All 54 skills in this repo
  • Accessibility

    kid-sid/claude-spellbook

    A skill your agent uses when building or reviewing UI components for keyboard and screen reader compatibility, adding ARIA to custom widgets, auditing a page for WCAG AA conformance, or preparing…

    189 GitHub stars~3.2k tokensUpdated 2 mo ago
    Auto-check passed
  • AI Engineer

    kid-sid/claude-spellbook

    A skill your agent uses when building production LLM applications — designing RAG pipelines, choosing vector databases, implementing agent orchestration, optimizing cost, or adding AI safety…

    189 GitHub stars~3.7k tokensUpdated 2 mo ago
    Auto-check passed
  • Angular

    kid-sid/claude-spellbook

    A skill your agent uses when building or refactoring Angular applications — choosing between signals, RxJS, and NgRx for state, configuring routing with guards and lazy loading, optimizing change…

    189 GitHub stars~5k tokensUpdated 2 mo ago
    Auto-check passed
  • API Design

    kid-sid/claude-spellbook

    A skill your agent uses when designing new REST endpoints, reviewing an existing API contract, adding pagination or filtering, planning a versioning strategy, or building a public or partner-facing…

    189 GitHub stars~3.6k tokensUpdated 2 mo ago
    Auto-check passed
  • Auth

    kid-sid/claude-spellbook

    A skill your agent uses when implementing login flows, issuing or validating JWTs, setting up OAuth2/OIDC with a provider, designing role-based or attribute-based access control, securing API…

    189 GitHub stars~3.2k tokensUpdated 2 mo ago
    Auto-check passed
  • Azure

    kid-sid/claude-spellbook

    A skill your agent uses when writing Python code that integrates with Azure Blob Storage, AI Search, Document Intelligence, or Key Vault — or when configuring Managed Identity auth, designing a…

    189 GitHub stars~3.7k tokensUpdated 2 mo ago
    Auto-check: notes

Categories

Questions about Agentex

What does Agentex do?

A skill your agent uses when building, wiring, or debugging an Agentex agent — choosing agent type, configuring acp.py and manifest.yaml, using adk.messages or adk.state, or resolving…. Agentex is an agent skill from kid-sid/claude-spellbook.state, or resolving Windows-specific setup issues.

When should I use Agentex?

Agentex fits situations like: debugging an Agentex agent — choosing agent type; configuring acp.py and manifest.yaml; using adk.messages; resolving Windows-specific setup issues.

How do I install Agentex in Claude Code?

Run `npx skills add kid-sid/claude-spellbook --skill agentex -a claude-code`. Or copy the skill folder (skills/agentex in kid-sid/claude-spellbook) into .claude/skills/agentex in your project. Claude Code loads it when a task matches its description.

How do I install Agentex in Codex?

Run `npx skills add kid-sid/claude-spellbook --skill agentex -a codex`. Or copy the skill folder (skills/agentex in kid-sid/claude-spellbook) into .agents/skills/agentex in your project. Codex loads it when a task matches its description.

Can I use Agentex in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add kid-sid/claude-spellbook --skill agentex -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/agentex, .gemini/skills/agentex, .github/skills/agentex and .opencode/skills/agentex in your project.

What does Agentex need to run?

Going by SKILL.md and its folder, Agentex needs the command-line tools its instructions call (uv). Our summary lists: Python 3; Docker.

Does Agentex access the network?

SKILL.md contains no URLs. Its commands use uv, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Agentex safe to install?

Our automated static check of SKILL.md found notes only (mentions a .env file), nothing it rates as a warning. It is not a guarantee. Review the folder before installing.

What licence does Agentex use?

Agentex is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Agentex use?

About 2.2k tokens (SKILL.md is roughly 8.9k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Agentex?

Skills that share tags, products or a category with Agentex: Finishing a Development Branch (obra/superpowers, 296k stars), Typescript Advanced Types (rolling-scopes/rsschool-app, 10k stars), PR Babysitter (openinterpreter/openinterpreter, 69k stars) and Code Review Checklist (shareAI-lab/learn-claude-code, 78k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Agentex?

kid-sid (a GitHub user) maintains it in kid-sid/claude-spellbook, which has 189 GitHub stars. The repository holds 54 skills in this directory. The repository was last updated on August 5, 2026.

Source: kid-sid/claude-spellbook on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.