Agent Foundry

Agent Foundry

Skill and agent runtime for AI coding assistants.

Plan → execute → verify. Skills, agents, a local daemon. MIT, local, no cloud. 41 original skills. Two optional skills carry their own Apache-2.0 license; see LICENSES.md.

Quick start · Catalog · Architecture · Commands · Web app

---

Why Agent Foundry

Models hallucinate. They over-comment. They reach for npm install when

you asked for a one-line fix. Agent Foundry steers the model back to the

actual work.

Three layers:

Each layer is portable. A skill body is a plain markdown file with a trigger phrase. An agent is a role definition. The orchestrator is a Python package you can pip install or run from source.

---

Quick start

1. Install

Two independent lanes. Install one or both.

Skills (Node 22.14+, no Python):

macOS / Linux / Git Bash:

curl -fsSL https://raw.githubusercontent.com/youcisla/Agent-Foundry/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/youcisla/Agent-Foundry/main/scripts/install.ps1 | iex

Or run the installer from npm without a global install (any OS). The explicit package plus bin form selects the Node installer even when the Python package is also installed:

npx --yes --package @youcisla/agent-foundry agent-foundry-install

npx --yes --package @youcisla/agent-foundry agent-foundry-install --list

A global install exposes the same bin:

npm install -g @youcisla/agent-foundry

agent-foundry-install --list

The same package is mirrored on GitHub Packages: https://github.com/youcisla/Agent-Foundry/pkgs/npm/agent-foundry.

Runtime (Python 3.10-3.14, no Node):

pip install agent-foundry-runtime

agent-foundry-runtime init agent-foundry-runtime doctor uvx agent-foundry-runtime mcp # MCP stdio server, no install needed

Registry name: io.github.youcisla/agent-foundry.

agent-foundry still works as a compatibility alias from either package, but two packages can install the same name. Scripts should use agent-foundry-install (Node) and agent-foundry-runtime (Python). The alias is kept until at least 2027-06-30.

Every harness gets each skill as a direct child of its real discovery root. See docs/harness-compatibility.md for the path matrix and the dos/don'ts.

Then set an API key:

export ANTHROPIC_API_KEY=sk-...   # or OPENAI_API_KEY

2. Use it

In Claude Code (or any harness that accepts slash commands):

/af "build a react component"      # plan + execute

/plan "audit this API" # see which skills match

Without a harness:

agent-foundry-runtime plan  "kill generic AI slop"

agent-foundry-runtime run "refactor the API design" agent-foundry-runtime doctor

3. Or browse first

→ [youcisla-agents.vercel.app](https://youcisla-agents.vercel.app) has the full catalog, an interactive knowledge graph, and one-click install.

4. Or connect over MCP

agent-foundry-runtime mcp   # stdio MCP server: plan, execute, list_skills, search_skills, get_skill, verify_skills, check_action, runtime_status, execution_history, list_models

Or run the published package directly:

uvx agent-foundry-runtime mcp

Registered name: io.github.youcisla/agent-foundry.

5. Measure a skill instead of trusting it

agent-foundry-runtime eval --tasks tasks.json

Each task runs twice, with and without the skill, and reports the pass-rate lift. Task format: {"id", "prompt", "skill", "verify"} where verify is a shell command that receives the output on stdin. The layout matches SkillsBench v1.1 (benchflow/skillsbench), so published benchmarks can be reused.

---

Architecture

Your prompt  (/af build a react component)

└─▶ Agent Foundry daemon └─▶ planner · rank_skills └─▶ executor · LiteLLM ⇄ LLM provider (Claude, OpenAI, …) └─▶ SQLite · executions.db └─▶ Response to user

Published through three channels: npm (@youcisla/agent-foundry), PyPI (agent-foundry-runtime), and the official MCP registry (io.github.youcisla/agent-foundry).

Interactive versions of every diagram live on the site:

[/architecture](https://youcisla-agents.vercel.app/architecture),

[/graph](https://youcisla-agents.vercel.app/graph) (knowledge graph +

orchestration), and [/audit](https://youcisla-agents.vercel.app/audit).

What's in the box

skills/         41 disciplines (31 core + 10 optional)    ─┐ feed

agents/ af-planner · af-critic · af-orchestrator │ the ▼ indexer agent_foundry/ config.py ─▶ daemon.py (FastAPI) ─▶ mcp_server.py (stdio MCP) indexer.py ─▶ planner.py ─▶ loop.py ⇄ executor.py loop.py ─▶ judge.py (af-critic) ─▶ logging_db/ scripts/ install.js ─▶ 14 harness skill roots + CLI index

The daemon is lazy-started by the CLI, so there is no systemd/launchd requirement. Everything runs locally. Your data stays in ~/.config/agent-foundry/executions.db.

The loop, end to end

 1.  user      → run_loop   : /af "kill generic AI slop"

1. run_loop → planner : rank_skills(prompt, index)
2. planner → run_loop : top match (e.g. anti-slop, 0.24)
3. run_loop → run_loop : budget guard
4. run_loop → executor : build_messages(prompt, body)
5. executor → LiteLLM : POST /v1/messages
6. LiteLLM → executor : response text
7. executor → run_loop : response + cost
8. (judge=true) run_loop → af-critic : score → {corr, slop, scope, verdict}
9. run_loop → SQLite : log_execution(...)
10. run_loop → user : LoopResponse {output, plan, judge_score?}

---

Catalog

41 skills, 3 agents. Original work; MIT except two optional skills (chrome-devtools-mcp-bridge, persistent-memory) licensed Apache-2.0 in their own frontmatter. Each skill:

• 📏 ≤150 lines / ≤8 KB (Codex cap, no exceptions)
• 🎯 Exactly one trigger phrase (Use when... so the model knows when to fire)
• 🚫 Anti-patterns + Verification checklist (teach what *not* to do, then confirm it was done)
• ⚡ Action verbs, not tool names (examine not Read, create not Write)

Core skills (31)

Optional skills (10)

| [funnel-pr-guard](skills