Examples

Examples

Patterns for defining Experts. Each example highlights a specific skill type or integration approach.

• GitHub Issue Bot
• Web Search
• Custom MCP Server
• Interactive Wizard
• Application Integration

GitHub Issue Bot

Pattern: Use requiredEnv to pass environment variables to tools like gh CLI.

[experts."@perstack/github-issue-bot"]
description = "Answers GitHub issues by reading codebase"
instruction = """
You are a GitHub issue support bot.
Use `gh` CLI to fetch issue content, explore the codebase, and generate answers.
"""

[experts."@perstack/github-issue-bot".skills."@perstack/base"]
type = "mcpStdioSkill"
command = "npx"
packageName = "@perstack/base"
requiredEnv = ["GH_TOKEN", "GITHUB_REPO", "ISSUE_NUMBER"]

This Expert is published to the registry. Run it with:

npx perstack run @perstack/github-issue-bot "Answer issue #123"

See examples/github-issue-bot for complete setup including GitHub Actions workflow and real-time activity logging.

Web Search

Pattern: Use mcpStdioSkill with an npm package. Auto-installed at runtime.

[experts."market-monitor"]
description = "Monitors stock market changes and analyzes trends"
instruction = """
You are a market monitoring assistant.
Search for latest market news, compare with previous reports, and highlight changes.
"""

[experts."market-monitor".skills."web-search"]
type = "mcpStdioSkill"
command = "npx"
packageName = "exa-mcp-server"
requiredEnv = ["EXA_API_KEY"]

Uses Exa MCP Server. Set EXA_API_KEY environment variable.

Custom MCP Server

Pattern: Use mcpStdioSkill with your own MCP server for internal systems.

[experts."support-assistant"]
description = "Provides customer support using internal knowledge base"
instruction = """
You are a customer support assistant.
Look up customer info, search the knowledge base, and provide solutions.
"""

[experts."support-assistant".skills."customer-db"]
type = "mcpStdioSkill"
command = "node"
args = ["./mcp-servers/customer-db.js"]
requiredEnv = ["DB_CONNECTION_STRING"]

[experts."support-assistant".skills."knowledge-base"]
type = "mcpStdioSkill"
command = "node"
args = ["./mcp-servers/knowledge-base.js"]

Implement MCP servers in Node.js, Python, or any language. Keep credentials in environment variables.

Interactive Wizard

Pattern: Use interactiveSkill to pause execution and wait for user input.

[experts."project-setup"]
description = "Guides users through project setup"
instruction = """
You are a setup wizard.
Use askChoice to ask about project type, framework, and tooling.
Generate config files based on selections.
"""

[experts."project-setup".skills."interaction"]
type = "interactiveSkill"

[experts."project-setup".skills."interaction".tools."askChoice"]
description = "Ask user to choose from options"
inputJsonSchema = """
{
  "type": "object",
  "properties": {
    "question": { "type": "string" },
    "options": { "type": "array", "items": { "type": "string" } }
  },
  "required": ["question", "options"]
}
"""

When askChoice is called, execution pauses until the user responds.

Application Integration

Pattern: Use interactiveSkill to let your application handle operations the Expert triggers.

[experts."shopping-concierge"]
description = "Helps find products and add to cart"
instruction = """
You are a shopping assistant.
Find matching products, then use addToCart to add them.
"""

[experts."shopping-concierge".skills."catalog"]
type = "mcpStdioSkill"
command = "node"
args = ["./mcp-servers/product-catalog.js"]

[experts."shopping-concierge".skills."app"]
type = "interactiveSkill"

[experts."shopping-concierge".skills."app".tools."addToCart"]
description = "Add product to cart"
inputJsonSchema = """
{
  "type": "object",
  "properties": {
    "productId": { "type": "string" },
    "quantity": { "type": "number" }
  },
  "required": ["productId", "quantity"]
}
"""

When addToCart is called, execution pauses and returns control to your application. Your app performs the cart operation, then resumes the Expert. This pattern separates AI reasoning from actual operations.