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
Models hallucinate. They over-comment. They reach for
npm installwhen you asked for a one-line fix. Agent Foundry steers the model back to the actual work.
Three layers:
| Layer | What | Lives in |
|---|---|---|
| 🧠 Skills | Disciplines the model applies (how to think, not what to know) | skills/core/<name>/SKILL.md |
| 🤖 Agents | Roles the orchestrator can dispatch (critic, planner, orchestrator) | agents/af-*/AGENT.md |
| ⚙️ Orchestrator | Local daemon that ranks, dispatches, executes, logs, judges | agent_foundry/ (Python) |
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.
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 | bashWindows (PowerShell):
irm https://raw.githubusercontent.com/youcisla/Agent-Foundry/main/scripts/install.ps1 | iexOr 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 --listA global install exposes the same bin:
npm install -g @youcisla/agent-foundry
agent-foundry-install --listThe 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 neededRegistry 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_KEYIn Claude Code (or any harness that accepts slash commands):
/af "build a react component" # plan + execute
/plan "audit this API" # see which skills matchWithout a harness:
agent-foundry-runtime plan "kill generic AI slop"
agent-foundry-runtime run "refactor the API design"
agent-foundry-runtime doctor→ youcisla-agents.vercel.app has the full catalog, an interactive knowledge graph, and one-click install.
agent-foundry-runtime mcp # stdio MCP server: plan, execute, list_skills, search_skills, get_skill, verify_skills, check_action, runtime_status, execution_history, list_modelsOr run the published package directly:
uvx agent-foundry-runtime mcpRegistered name: io.github.youcisla/agent-foundry.
agent-foundry-runtime eval --tasks tasks.jsonEach 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.
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, /graph (knowledge graph + orchestration), and /audit.
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.
1. user → run_loop : /af "kill generic AI slop"
2. run_loop → planner : rank_skills(prompt, index)
3. planner → run_loop : top match (e.g. anti-slop, 0.24)
4. run_loop → run_loop : budget guard
5. run_loop → executor : build_messages(prompt, body)
6. executor → LiteLLM : POST /v1/messages
7. LiteLLM → executor : response text
8. executor → run_loop : response + cost
9. (judge=true) run_loop → af-critic : score → {corr, slop, scope, verdict}
10. run_loop → SQLite : log_execution(...)
11. run_loop → user : LoopResponse {output, plan, judge_score?}
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 (
examinenotRead,createnotWrite)
| Skill | Trigger |
|---|---|
anti-slop |
Kill generic AI patterns before they ship |
api-design |
Use when creating a new API endpoint or reviewing API consistency |
automation-pick |
Decide whether to automate a task before automating |
bottleneck-gating |
Phase a project by measured bottleneck, not intuition |
budget-guard |
Set and enforce a hard spend ceiling for paid loops |
constraint-then-solve |
Restate the problem, catalog constraints, then solve |
context-optimization |
Use on any task with >2K-token outputs, big files, or repeated reads |
cron-troubleshoot |
Debug a missing or wrong cron job |
e2e-test-strategy |
Use when designing test coverage for a web app or API |
engram-routing |
Route prompts via O(1) N-gram lookup when trigger patterns should match fast |
execution-observability |
Log model, cost, latency, and outcome for every run |
fallback-model-routing |
Route around provider failures and report which model answered |
feedback-loop |
After shipping, instrument → measure → iterate |
knowledge-extract |
Turn a session into a skill draft |
landscape-first |
Research the space before building |
measure-first |
Use when about to optimize, refactor, or claim a system is slow |
plan-before-code |
Use before writing any non-trivial code change |
plan-then-act |
Use when a task has multiple steps and the order matters |
prompt-discipline |
Use on every non-trivial task: think, simplify, edit surgical, stay goal-driven |
pushback-when-wrong |
Use when reviewing an assertion that smells off |
quality-protocol |
Use before declaring a task complete |
re-verify-findings |
Use after any prior verification claimed a finding |
read-before-build |
Read source files before writing code |
session-closeout |
Apply at the end of any multi-step project |
session-distill |
Extract patterns from every session |
show-your-work |
Output a thinking trace after complex tasks |
structured-output-contract |
Enforce a JSON Schema for machine-read output |
verify-first |
Apply before committing to any claim |
workflow-decompose |
Use when designing or debugging an automation |
cache-identity |
Version and bound caches; publish atomically |
judge-integrity |
Separate judge failure from a low score |
| Skill | Trigger |
|---|---|
persistent-memory |
Use when persisting context across sessions or threading memory across agents |
token-compression |
Compress tool outputs before they consume context |
chrome-devtools-mcp-bridge |
Drive Chrome DevTools from an agent |
design-language |
Apply Apple-grade UI polish |
funnel-pr-guard |
Guard conversion-critical paths from breaking |
sql-migration-trio |
Three-file migration pattern (up/down/schema) |
agent-memory-vault |
Shared structured memory that survives agent sessions |
agent-team-standards |
Per-project locked agent skill set with version pins |
autonomous-briefing |
Run a fully autonomous morning briefing |
book-to-skill |
Convert book chapters or long articles into a runnable skill |
| Agent | Model | Job |
|---|---|---|
af-critic |
opus |
Score output on correctness, slop, scope. Returns JSON. |
af-planner |
opus |
Decompose a request into a skill/agent plan. Returns JSON. |
af-orchestrator |
opus |
Dispatch subtasks to specialized agents and skills, then merge results. |
| Command | What it does |
|---|---|
agent-foundry-runtime init [--force] |
Write config and the first skill index |
agent-foundry-runtime index |
Rebuild the skill index from disk |
agent-foundry-runtime plan "<prompt>" |
Rank skills for a prompt |
agent-foundry-runtime run "<prompt>" |
Plan + execute the top-ranked skill |
agent-foundry-runtime resume <session_id> "<prompt>" |
Continue a loop session with a follow-up |
agent-foundry-runtime session <session_id> |
Inspect a stored loop session |
agent-foundry-runtime execute <skill_id> "<prompt>" |
Run a specific skill |
agent-foundry-runtime doctor |
Health-check: config, index, daemon, API key |
agent-foundry-runtime status |
Routing accuracy, fallback rate, average cost |
agent-foundry-runtime consult "<need>" |
Recommend skills for a need |
agent-foundry-runtime cost-report |
Token and time estimates per skill |
agent-foundry-runtime feedback <id> <score> |
Attach a human score to an execution |
agent-foundry-runtime rejudge <id> [--model] |
Re-score stored output without re-running the completion |
agent-foundry-runtime calibrate [--bins N] |
Compare judge scores with human feedback |
agent-foundry-runtime prune --older-than-days N [--dry-run] |
Delete old executions, observations, policy decisions, and perf stats |
agent-foundry-runtime learn [--scope project|global] |
Learn trigger weights from judged executions |
agent-foundry-runtime instincts [--explain <id>] [--proposals] |
List instincts, explain evidence, or write review-only proposals |
agent-foundry-runtime instinct-approve <id> |
Approve an instinct and persist it |
agent-foundry-runtime attest |
Sign a manifest of skill file hashes and frontmatter digests |
agent-foundry-runtime verify [--strict] |
Verify the installed manifest and signature |
agent-foundry-runtime gate --kind <kind> --value <value> |
Classify an action as allow, confirm, or deny |
agent-foundry-runtime browse |
Browse/search the catalog, or --read <id> |
agent-foundry-runtime mcp |
Start the MCP stdio server (plan/execute/list_skills/search_skills/get_skill/verify_skills/check_action/runtime_status/execution_history/list_models) |
agent-foundry-runtime eval --tasks <file> |
Paired skill eval: with vs without, reports lift |
agent-foundry-runtime serve |
Start the daemon (lazy-started on first command) |
Every command also has an HTTP endpoint on the daemon for programmatic use:
/health, /site-data, /events, /index, /plan, /engram, /execute,
/loop, /loop/resume, /loop/{id}, /stats, /feedback, /learn,
/instincts, and /instincts/{id}/approve.
What the runtime does not provide, stated so you do not discover it in production:
- No hosted execution sandbox. Skills run as prompts; tool execution belongs to the host harness.
- No multi-tenant auth or per-user quota enforcement. The daemon binds localhost and trusts the local user.
- No durable queue across daemon restarts. In-flight requests are lost if the process dies.
- No cross-provider load balancing. Routing is per-call chain order with optional historical attempt allocation.
- No semantic determinism guarantee from providers. The determinism contract covers the trace digest, not model sampling.
Skills and runtime are separate, explicit steps:
# Skills only: Node 22.14+, no Python
npx --yes --package @youcisla/agent-foundry agent-foundry-install --harness=codex
# Runtime only: Python 3.10-3.14, no Node
pip install agent-foundry-runtime && agent-foundry-runtime init
# init warns until content is installed with agent-foundry-installRun the runtime from source (any OS):
git clone https://github.com/youcisla/Agent-Foundry.git ~/.agent-foundry
cd ~/.agent-foundry && pip install -e .See INSTALL.md for the full matrix of harnesses, install lanes, and platforms.
- Node 22.14+ for the skill installer (skills-only installs need no Python)
- Python 3.10-3.14 for the CLI, daemon, and MCP runtime (no Node required)
- macOS, Linux, or Windows
- A supported harness: Claude Code, Codex, Cursor, Gemini/Antigravity, OpenCode, Hermes, Zed, or any of the 14 adapters
- An API key (Anthropic, OpenAI, or any provider LiteLLM supports)
One entry point, explicit named gates, no bash required for the default scopes:
python scripts/check.py --fast # inner loop
python scripts/check.py --all # pre-merge and CI
python scripts/check.py --release # built artifacts and SBOMscripts/check.py runs each gate with a timeout, prints a machine-readable
summary with --json, and never counts a skipped gate as a pass for release.
See docs/testing.md for the gate scopes and the offline
routing evaluation.
Counts and measured values below are generated from live sources; do not edit them by hand.
| Metric | Value | Source |
|---|---|---|
| Version | 0.6.0 | package.json |
| Skills | 41 (31 core + 10 optional) | skills/ (filesystem) |
| Agents | 3 | agents/ (filesystem) |
| Adapters | 14 | scripts/install.js |
| Commands | 25 | agent_foundry/cli.py (Click tree) |
| Http Endpoints | 15 | agent_foundry/daemon.py (routes) |
| Routing Top1 | 85.8% | evals/routing/baseline.json |
| Routing Top3 | 99.1% | evals/routing/baseline.json |
| Gates | 20 named gates | scripts/check.py |
31 core + 10 optional = 41 skills
Provenance (generated_at, revision) lives in web/metrics.js.
Each skill has a generated sidecar record in data/skills/<id>.json. A tier is
published evidence, never an assertion:
| Tier | Name | Requirement |
|---|---|---|
| L0 | Metadata | valid frontmatter |
| L1 | Static contract | the content lint passes |
| L2 | Routing evidence | at least two labelled routing cases with a top-1 hit and documented neighbors |
| L3 | Behavioural evidence | paired offline eval with at least three deterministic-verifier tasks and a stored artifact |
| L4 | Field evidence | opt-in human feedback with a reviewer sign-off |
python scripts/gen-skill-evidence.py regenerates every record from the live
corpus and lint. --check fails when a body edit makes a record stale (the body
hash changes, so the tier must be re-reviewed before it can be claimed again).
Routing evidence is selection evidence only; records never present it as task
efficacy, and L3 records appear only when paired-eval artifacts exist under
data/evals/.
Maintainers publish through .github/workflows/release.yml. See
docs/releasing.md for the dry run, trusted-publisher
prerequisites, tag rules, and recovery steps. The local scripts/publish.sh
is an emergency fallback only.
Browse the catalog, the knowledge graph, and the audit at youcisla-agents.vercel.app:
| Page | What |
|---|---|
| Catalog | All 41 skills + 3 agents with live search |
| Graph | Interactive knowledge graph canvas; no fixed counts are claimed here |
| Audit | God nodes, surprising connections, interactive React Flow diagrams |
The site regenerates from live repo state on every commit via
scripts/gen-site-data.py → Vercel build → deploy.
| Status | Item |
|---|---|
| ✅ v0.1 | Python package + FastAPI daemon + Claude Code plugin |
| ✅ v0.2 | Foundational audit, frozen Config, multi-page web app, knowledge graph, interactive React Flow diagrams |
| ✅ v0.3 | npm package, Engram O(1) routing, af-orchestrator agent, harness adapters |
| ✅ v0.4 | PyPI + MCP registry, loop sessions, deterministic site data, per-skill adapter installs |
| 📋 next | af verify signed-manifest integrity |
See docs/launch-plan.md for the full design spec.
MIT, except the two optional skills that declare Apache-2.0 in their own frontmatter. All skills, agents, and authored artifacts are original work by the Agent Foundry Contributors. See AUTHORSHIP.md for the attribution policy, LICENSES.md for the per-artifact license ledger, and SECURITY.md for the private vulnerability reporting and supply-chain policy.
Built by Youcisla · Contribute · Report an issue