Skill Architect and Runner

A two-agent architecture that enforces strict separation of concerns: a Skill Architect creates and maintains skills in a shared space, while a Task Runner can only read those skills and execute them in its own isolated workspace - making skills non-modifiable at runtime.

←Back to examplesCopy
dual-agent
skills
separation of concerns
1707

The Skill Architect and Runner blueprint demonstrates a critical production pattern: immutable skill governance through agent-level access control.

In the existing Skill Bot blueprint a single agent can create, read, and execute skills in the same space. That is powerful for prototyping but risky in production - the executing agent can modify its own skills mid-conversation, either by accident or through prompt injection. There is no enforcement boundary between "who writes the rules" and "who follows them."

This blueprint solves that by splitting responsibilities across two agents with asymmetric access to two separate spaces:

The Skill Architect

The Architect owns the Skill Library space. It has full create, list, and read access to skills in that space, plus shell execution and file read/write capabilities in the same space for testing skills before publishing them. Its job is to design, write, test, and maintain skills - each one a structured Markdown file with a name, description, and step-by-step instructions.

The Architect is the only agent that can modify the skill library. When a user asks for a new capability, the Architect creates a well-tested skill file. When a skill needs updating, the Architect rewrites it. Skills are versioned by convention (the Architect includes a version and last-updated date in each skill file).

The Task Runner

The Runner has read-only access to the Skill Library space - it can list and read skills but never create or modify them. For execution it has its own separate Runtime Workspace space with full shell execution and file read/write capabilities.

When a user asks the Runner to perform a task, it discovers available skills from the Skill Library, reads the relevant skill, and follows the instructions using its own runtime workspace. The Runner cannot alter the skill definitions it follows, even if instructed to do so.

Why This Matters

This asymmetric access pattern creates a clean governance boundary:

  • Tamper-proof skills - The Runner follows skills exactly as the Architect wrote them. No prompt injection or user instruction can cause the Runner to modify the skill definitions it operates from.

  • Auditable changes - All skill changes flow through the Architect. The Skill Library space becomes a version-controlled record of what the system can do and when each capability was added or changed.

  • Safe execution - The Runner's runtime workspace is isolated from the skill definitions. Script outputs, temporary files, and execution artifacts stay in the Runner's space and cannot pollute the skill library.

  • Independent scaling - The Architect can be a slower, more capable model focused on quality (it runs less frequently). The Runner can be a faster, cheaper model optimized for throughput (it handles every user request).

Comparison with Dual-Agent Programmable Workflows

The Dual-Agent Programmable Workflows blueprint uses a similar separation pattern but with a single playbook file. This blueprint upgrades that concept by using the platform's native skill system, which provides structured discovery (list/read), frontmatter metadata, and a standardized format. Skills are individually addressable, self- describing, and independently maintainable - advantages over a single monolithic playbook document.

Getting Started

  1. Open a conversation with the Skill Architect and ask it to create skills for your workflows (e.g. "Create a skill that fetches the latest HackerNews stories and summarizes them").
  2. The Architect writes, tests, and publishes the skill to the Skill Library space.
  3. Open a conversation with the Task Runner and ask it to perform the task. It discovers the skill, reads it, and executes it in its own workspace.
  4. Browse both spaces with the Space File Browsers to see the skill library and runtime artifacts independently.

This pattern is ideal for production environments where skill definitions must be controlled, auditable, and protected from runtime modification.

Backstory

Common information about the bot's experience, skills and personality. For more information, see the Backstory documentation.

You are the Skill Architect - responsible for designing, writing, testing, and maintaining skills in the Skill Library. You are the ONLY agent that can create or modify skills. The Task Runner agent reads your skills but cannot change them. ## YOUR RESPONSIBILITIES 1. SKILL DESIGN - Analyze user requirements and design clear, reusable skills - Each skill is a Markdown file stored in the `.skills` directory - Follow the standard skill format with frontmatter metadata 2. SKILL CREATION - Use the `create_space_skills` tool to write skills to the Skill Library - Every skill must include: - A clear name and description in the frontmatter - Step-by-step instructions the Task Runner can follow precisely - Any required shell commands, API calls, or data transformations - Expected inputs and outputs - Error handling guidance 3. SKILL TESTING - Before publishing, test your skills using the bash tool - Verify shell commands work correctly - Ensure instructions are unambiguous and complete 4. SKILL MAINTENANCE - List existing skills before creating new ones to avoid duplicates - Update skills when requirements change - Include a version number and last-updated date in each skill ## SKILL FORMAT When creating skills, use this structure: ```markdown --- name: Skill Name description: What this skill does version: 1.0 updated: YYYY-MM-DD --- # Skill Name ## Purpose [What this skill accomplishes] ## Instructions 1. [Step one with precise details] 2. [Step two] 3. [Step three] ## Required Environment [Any API keys, tools, or prerequisites] ## Error Handling [What to do if something goes wrong] ``` ## RULES - Always list existing skills before creating to avoid duplicates - Test every skill before publishing - Write instructions as if the reader has no prior context - Include error handling in every skill - The current date is ${EARTH_DATE}

Skillset

This example uses a dedicated Skillset. Skillsets are collections of abilities that can be used to create a bot with a specific set of functions and features it can perform.

  • 🇫🇷

    Create Skills

    Creates one or more skills in the Skill Library under the .skills directory. Each skill is stored as a SKILL.md file with frontmatter containing the name and description.
  • 🎿

    List Skills

    Lists all available skills in the Skill Library by scanning .skills, .github/skills, and .claude/skills directories. Returns the name, description, and path for each skill found.
  • 🎭

    Read Skills

    Reads the full content of one or more skill files from the Skill Library by their paths.
  • ✂️

    Bash

    Execute shell commands for testing skills in the Skill Library space
  • 🐀

    Read/Write Files

    Read or write files in the Skill Library space for testing and configuration
  • 🎓

    List Skills

    Lists all available skills in the Skill Library. Use this to discover what capabilities are available before attempting any task.
  • 🌓

    Read Skills

    Reads the full content of one or more skill files from the Skill Library by their paths. Use list first to discover available skill paths.
  • 🏢

    Bash

    Execute shell commands and scripts in the isolated Runtime Workspace
  • ✂️

    Read/Write Files

    Read or write files in the isolated Runtime Workspace for execution artifacts and outputs

Terraform Code

This blueprint can be deployed using Terraform, enabling infrastructure-as-code management of your ChatBotKit resources. Use the code below to recreate this example in your own environment.

View Terraform Code

Copy this Terraform configuration to deploy the blueprint resources:

Next steps:

  1. Save the code above to a file named main.tf
  2. Set your API key: export CHATBOTKIT_API_KEY=your-api-key
  3. Run terraform init to initialize
  4. Run terraform plan to preview changes
  5. Run terraform apply to deploy

Learn more about the Terraform provider

A dedicated team of experts is available to help you create your perfect chatbot. Reach out via or chat for more information.

More Awesome Examples