Table of Contents

1. Overview
2. Architecture
3. Project Structure
4. Quick Start
5. Core Concepts
6. The Six-Layer Agent Pipeline
7. Agent Templates
8. Skill File System
9. Generated Output Files
10. Guardrails System
11. Evaluation Framework
12. Multi-Agent System
13. Audit Trail
14. Governance & Permissions
15. Deployment
16. Configuration Reference
17. Development
18. Security
19. Contributing
20. License

Overview

Ai-Agent Builder is a production-grade, "backend-less" single-file web application for authoring, configuring, and packaging AI agents. It runs entirely in the browser — no server, no API keys stored, no telemetry — making it invisible to trackers and safe for enterprise environments.

What It Does

Users enter an agent name, describe a use case (or select a template), upload reference .md/.txt/.docx files, configure model parameters and feature flags, then click Build Agent. The builder generates a complete, deployment-ready package of markdown configuration files following the agentskills.io open standard.

Key Features

Architecture

┌─────────────────────────────────────────────────────────┐
│                    BROWSER (No Server)                  │
│                                                         │
│  ┌──────────┐  ┌───────────────────┐  ┌─────────────┐   │
│  │ Sidebar  │  │   Canvas (Main)   │  │ Right Panel │   │
│  │          │  │                   │  │             │   │
│  │ Agent    │  │ • Identity        │  │ • SKILL.md  │   │
│  │ Nav      │  │ • Use Case        │  │ • AGENTS.md │   │
│  │          │  │ • Templates       │  │ • Eval      │   │
│  │ Workspace│  │ • File Drop Zone  │  │ • Audit Log │   │
│  │ Links    │  │ • Skills Registry │  │             │   │
│  │          │  │ • Pipeline View   │  │             │   │
│  │ Stats    │  │ • Model Config    │  │             │   │
│  │          │  │ • Feature Flags   │  │             │   │
│  └──────────┘  └───────────────────┘  └─────────────┘   │
│                                                         │
│  ┌─────────────────────────────────────────────────────┐│
│  │              Build Engine (JavaScript)              ││
│  │  validate() → build() → package() → download()      ││
│  └─────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────┘
                         │ downloads
                         ▼
┌─────────────────────────────────────────────────────────┐
│              Deployment Package (.md files)             │
│                                                         │
│  SKILL.md · AGENTS.md · MEMORIES.md · guardrails.md     │
│  llm-judge.md · audit-trails.md · governance.md         │
│  permissions.md · versioning.md · eval-golden-set.md    │
│  README.md · .agents/skills/SKILL.md                    │
└─────────────────────────────────────────────────────────┘

Design Principles

1. Backend-less by design — The entire application is a single HTML file. State lives in JavaScript. Files are generated client-side using the Blob API.
2. Privacy-first — Zero network requests after initial load. No CDN fonts, no analytics scripts, no telemetry.
3. agentskills.io standard — All output follows the open SKILL.md format, compatible across LLM platforms.
4. Progressive disclosure — Skill files use 3-level loading: discovery (frontmatter only) → execution (full file) → orchestration (linked references on-demand).
5. Enterprise-grade defaults — Guardrails, audit trails, sandbox config, HITL gates, and LLM-judge rubrics are generated automatically.

Project Structure

ai-agent-builder/
│
├── ai-agent-builder.html          # Main application — single deployable file
│
├── README.md                      # This file
│
├── .agents/
│   └── skills/
│       ├── SKILL.md               # Meta-skill: how to use skills
│       ├── code-review.md         # Code review skill
│       ├── security-audit.md      # Security audit skill
│       ├── sprint-planner.md      # Sprint planning skill
│       ├── data-validator.md      # Data pipeline validation skill
│       ├── rag-retrieval.md       # Agentic RAG skill
│       └── incident-response.md   # Incident triage skill
│
├── logic/                         # ← Logic Components (deterministic orchestration)
│   ├── ROUTER.md                  # Deterministic router — regex/JSON path routing
│   ├── SEQUENCE.md                # Iterator & batch controller — loop over items
│   ├── GATE.md                    # HITL checkpoint — durable wait for approval
│   ├── DATA_MAP.md                # Cross-skill data mapper — explicit field mapping
│   ├── ERROR_POLICY.md            # Recovery & retry — backoff, fallback, circuit breaker
│   └── routing-manifest.json      # Compiled rule index — read by runner at startup
│
├── references/
│   ├── guardrails.md              # Runtime safety configuration
│   ├── llm-judge.md               # LLM-as-Judge rubric
│   ├── audit-trails.md            # Audit event schema
│   ├── governance.md              # Governance policies
│   ├── permissions.md             # RBAC and permission scopes
│   └── versioning.md              # Versioning manifest
│
├── agents/
│   ├── architect/
│   │   └── INSTRUCTIONS.md        # Architect agent role config
│   ├── worker/
│   │   └── INSTRUCTIONS.md        # Worker agent role config
│   └── security/
│       └── INSTRUCTIONS.md        # Security Officer role config
│
├── evals/
│   ├── golden-set/
│   │   ├── README.md              # Golden set documentation
│   │   ├── code-review.json       # Code review eval scenarios
│   │   ├── security.json          # Security eval scenarios
│   │   └── general.json           # General capability evals
│   └── red-team/
│       ├── README.md              # Red team documentation
│       ├── prompt-injection.md    # Injection attack prompts
│       ├── credential-theft.md    # Credential exfiltration probes
│       └── permission-escalation.md
│
├── scripts/
│   ├── validate.sh                # Pre-build validation script
│   ├── package.sh                 # Package builder script
│   ├── eval-runner.sh             # Eval framework shell runner
│   └── eval-runner.py             # Eval framework Python runner
│
├── docs/
│   ├── ARCHITECTURE.md            # Deep-dive architecture docs
│   ├── SKILL_AUTHORING.md         # How to write SKILL.md files
│   ├── DEPLOYMENT.md              # Deployment guide
│   └── API_REFERENCE.md           # Configuration reference
│
├── tests/
│   ├── unit/
│   │   └── builder.test.js        # Unit tests for build engine
│   └── integration/
│       └── e2e.test.js            # End-to-end tests
│
├── SKILL.md                       # Root skill manifest (agentskills.io)
├── AGENTS.md                      # Root orchestration city map
├── MEMORIES.md                    # Session memory store
├── CHANGELOG.md                   # Version history
├── CONTRIBUTING.md                # Contribution guidelines
└── LICENSE                        # MIT License

Quick Start

Option 1 — Open the HTML file directly

# Clone or download the repo
git clone https://github.com/david-spies/ai-agent-builder.git
cd ai-agent-builder

# Open in browser (no server needed)
open ai-agent-builder.html          # macOS
xdg-open ai-agent-builder.html      # Linux
start ai-agent-builder.html         # Windows

Option 2 — Serve locally (recommended for development)

# Python (built-in)
python3 -m http.server 3000

# Node.js
npx serve .

# Then open http://localhost:3000/ai-agent-builder.html

Option 3 — Deploy to static host

# Netlify
netlify deploy --prod --dir .

# Vercel
vercel --prod

# GitHub Pages
# Push to gh-pages branch — single file deploys instantly

Building Your First Agent (5 minutes)

1. Name your agent — Type a descriptive name in the Identity field
2. Describe the use case — Or click a Quick Fill pill (e.g., "Code Review")
3. Select a template — Choose the architecture pattern (e.g., "ReAct Agent")
4. Drop reference files — Drag your .md or .docx skill files into the dropzone
5. *Review the pipeline