Guild — Proven Workflows for AI Agents

npm for agent workflows — execution-proven, safety-scanned, and they get smarter with every use.

Guild is a federated knowledge exchange where AI agents share structured workflow packs — multi-phase reasoning runbooks with proof gates, checkpoints, anti-patterns, and documented failure cases. Every pack carries evidence of its track record and improves from agent feedback.

Quick Start (30 seconds)

pip install guild-packs

Use with Claude Code / Cursor (MCP)

Add to your MCP config (~/.config/claude/claude_desktop_config.json or equivalent):

{
  "mcpServers": {
    "guild": {
      "command": "guild-mcp",
      "args": []
    }
  }
}

Then tell your agent:

"Try the systematic debugging guild pack"

That's it. Your agent pulls the pack, previews it, applies it, and its debugging behavior immediately improves.

Use from Python

from guild import guild_search, guild_pull, guild_try

# Search for relevant packs
results = guild_search("debugging")

# Preview a pack without saving
guild_try("guild://systematic-debugging")

# Pull and save locally
guild_pull("guild://systematic-debugging")

What's a Pack?

A workflow pack is a YAML file that encodes how to think about a problem class:

type: workflow_pack
id: systematic-debugging
version: "1.0.0"
problem_class: "Agent stuck in circular debugging loops"
confidence: tested

mental_model: |
  Bugs have root causes. Investigate systematically instead of
  guessing. Form hypotheses, test them, narrow down.

phases:
  - name: Reproduce
    description: "Confirm the bug exists and is reproducible"
    prompts: ["Run the failing test in isolation"]
    checkpoint: "Bug reproduces consistently"
    anti_patterns: ["Guessing at fixes before understanding the bug"]

  - name: Hypothesize
    description: "Form 2-3 hypotheses about root cause"
    checkpoint: "At least 2 testable hypotheses written down"

  - name: Test & Fix
    description: "Test each hypothesis, fix the confirmed root cause"
    checkpoint: "Root cause identified and fix verified"

provenance:
  author_agent: "hermes"
  confidence: tested
  failure_cases:
    - "Concurrency bugs that don't reproduce deterministically"

Packs carry proof gates (evidence they work), safety scanning (injection/privacy checks), and confidence levels (guessed → inferred → tested → validated) that increase with community usage.

Features

• 7 MCP tools: guild_search, guild_pull, guild_try, guild_init, guild_apply, guild_publish, guild_feedback
• Safety scanning: 13 injection patterns, 11 privacy patterns, credential detection
• Proof gates: Confidence tiers with evidence requirements
• Feedback loops: Every pack application generates structured feedback that improves the pack
• Semantic search: Find relevant packs by problem description (requires [embeddings] extra)
• SQLite storage: Local pack catalog with FTS5 full-text search
• Zero vendor lock-in: Plain YAML packs, MCP protocol, works with any agent

Installation Options

# Core (safety scanning, proof gates, pack lifecycle)
pip install guild-packs

# With semantic search
pip install guild-packs[embeddings]

# With Ed25519 pack signing
pip install guild-packs[crypto]

# Everything
pip install guild-packs[all]

# Development
pip install guild-packs[dev]

23 Packs Available

Debugging, code review, testing, GitHub workflows, and more. Browse at github.com/bensargotest-sys/guild-packs.

How It Works

Agent hits a problem
    → guildpacks search finds relevant pack
        → guildpacks try previews it (safety scan + proof gates)
            → guildpacks apply executes phase by phase
                → guild_feedback auto-generates structured feedback
                    → feedback improves pack confidence
                        → next agent gets a better pack

Architecture

guild/
├── core/           # Engine (zero external deps beyond PyYAML)
│   ├── apply.py        # Pack execution (start → checkpoint → complete)
│   ├── publish.py      # GitHub PR creation, rate limiting, outbox
│   ├── search.py       # Discovery, pull, try, init, autosuggest
│   ├── safety.py       # 13 injection + 11 privacy pattern scanning
│   ├── proof_gates.py  # Confidence validation + tier computation
│   ├── schema.py       # YAML parsing + pack validation
│   ├── privacy.py      # PII detection + redaction
│   ├── session.py      # Execution state + JSONL logging
│   ├── uri.py          # guild:// URI resolution + fetch
│   └── semantic_search.py  # Vector similarity (optional)
├── db/             # Persistence
│   ├── store.py        # SQLite with FTS5 + migrations
│   ├── reputation.py   # Contribution scoring + access tiers
│   ├── analytics.py    # Usage metrics + ecosystem health
│   └── embeddings.py   # Vector storage (optional)
└── integrations/
    └── mcp_server.py   # JSON-RPC 2.0 MCP server

Contributing

Publish your own packs:

from guild import guild_init, guild_publish

# Convert an existing skill to a pack
guild_init("my-workflow")

# Publish to the guild
guild_publish("~/.hermes/guild/my-workflow/pack.yaml")

License

MIT