# Orcha Builder

> Documentation for creating and modifying ORCHA resources (agents, workflows, skills, functions, knowledge stores)

- Skill: `ddalcu/orcha-builder` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ddalcu/orcha-builder`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ddalcu/orcha-builder/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: ddalcu (https://skillmd.com/u/ddalcu)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ddalcu/orcha-builder

---


# ORCHA Resource Schemas

## Agents (`agents/<name>.agent.yaml`)

```yaml
name: my-agent
description: What the agent does
model:
  llm: default
  temperature: 0.7
prompt:
  system: |
    Your system prompt here.
  inputVariables:
    - query
tools:                                # mcp:<server> | knowledge:<store> | function:<name>
  - mcp:server-name                   # builtin:<name> | sandbox:<tool> | workspace:<tool>
  - knowledge:store-name              # workspace: read, write, delete, list, list_resources, diagnostics
  - sandbox:browser_navigate          # sandbox: exec, shell, web_fetch, web_search
                                      # sandbox: browser_navigate, browser_observe, browser_screenshot,
                                      #   browser_content, browser_click, browser_type, browser_evaluate
                                      # sandbox: vision_screenshot, vision_navigate, vision_click,
                                      #   vision_type, vision_scroll, vision_key, vision_drag
                                      #   (requires EXPERIMENTAL_VISION=true)
                                      # sandbox: file_read, file_write, file_edit, file_insert, file_replace_lines
                                      # builtin: ask_user, save_memory, canvas_write, canvas_append, generate_image, generate_tts, generate_video
                                      #   generate_video: distributed video generation via P2P (requires P2P enabled)
                                      #   (conditional: integration_post, integration_context, email_send)
skills:
  - skill-name                        # or use mode: all to attach all skills
output:
  format: text                        # text | structured
memory:
  enabled: true
  maxLines: 100
integrations:
  - type: collabnook
    url: "wss://collabnook.com/ws"          # optional — defaults to wss://collabnook.com/ws
    channel: general
    botName: Bot
  - type: email
    imap:
      host: imap.gmail.com
      port: 993
    smtp:
      host: smtp.gmail.com
      port: 587
    auth:
      user: agent@example.com
      pass: pw
    pollInterval: 60
    folder: INBOX
triggers:
  - type: cron
    schedule: "*/5 * * * *"
    input:
      query: "Task"
publish: true                         # or { enabled: true, password: "secret" }
p2p:                                  # P2P network config
  share: true                         # share this agent on the P2P network
  leverage: false                     # P2P model fallback — if a model (LLM, image, TTS) isn't available locally, search peers by name
sampleQuestions:                       # optional — clickable chips shown in chat UI on initial load
  - "What can you help me with?"
  - "Summarize the latest report"
```

Published agents are accessible at `/chat/<agent-name>` with optional per-agent password.
Agents with `p2p.share: true` are shared on the P2P network (enabled by default). Agents with `p2p.leverage: true` get P2P model fallback — if a model (LLM, image, or TTS) isn't available locally, the agent searches P2P peers by model name. This is different from `model: p2p` which explicitly routes LLM calls to a remote peer. P2P settings (peer name, network key, rate limit) are configurable in the P2P tab UI or via environment variables.

## Step-Based Workflows (`workflows/<name>.workflow.yaml`)

```yaml
name: my-workflow
description: What the workflow does
type: steps
input:
  schema:
    query:
      type: string
      required: true
steps:
  - id: step-one
    agent: agent-name
    input:
      query: "{{query}}"
    output:
      key: step_one_result
      extract: output
  - id: step-two
    agent: another-agent
    input:
      query: "{{step_one_result}}"
    output:
      key: step_two_result
    condition: "{{step_one_result}}"
  - parallel:
      - id: branch-a
        agent: agent-a
        input:
          query: "{{query}}"
        output:
          key: result_a
      - id: branch-b
        agent: agent-b
        input:
          query: "{{query}}"
        output:
          key: result_b
config:
  timeout: 300000
  onError: stop                       # stop | continue | retry
output:
  result: "{{step_two_result}}"
chatOutputFormat: text                  # text | json
sampleQuestions:
  - "Run the pipeline"
```

## ReAct Workflows (`workflows/<name>.workflow.yaml`)

```yaml
name: my-react-workflow
description: Autonomous workflow with tool and agent discovery
type: react
input:
  schema:
    query:
      type: string
      required: true
prompt:
  system: |
    You are a helpful assistant.
  goal: "Answer the user's query"
graph:
  model: default
  tools:
    sources:
      - mcp
      - knowledge
      - function
      - builtin
    mode: all                         # all | none | include | exclude
    exclude:
      - dangerous_tool
  agents:
    mode: all
    exclude:
      - architect
  executionMode: react                # react | single-turn
  maxIterations: 10
  timeout: 300000
output:
  result: "{{result}}"
chatOutputFormat: text                  # text | json
sampleQuestions:
  - "What can you do?"
```

## Knowledge Stores (`knowledge/<name>.knowledge.yaml`)

```yaml
name: my-knowledge
description: What this store contains
source:
  type: directory                     # directory | file | database | web
  path: ./docs
  pattern: "**/*.md"
  # Web-specific: url, selector (html only), headers, jsonPath (dot-notation for nested arrays)
loader:                               # optional — defaults: html (web), text (file/directory)
  type: text                          # text | pdf | csv | json | markdown | html
splitter:
  type: recursive                     # character | recursive | token | markdown
  chunkSize: 1000
  chunkOverlap: 200
embedding: default                    # reference to models.yaml config
search:
  defaultK: 4
  scoreThreshold: 0.5
reindex:                              # optional — periodic refresh
  schedule: "0 * * * *"              # cron expression
graph:                                # optional — works with database, csv, json (array of objects)
  directMapping:
    entities:
      - type: Person
        idColumn: id
        nameColumn: name
        properties:
          - email
          - role: job_title
    relationships:
      - type: WORKS_FOR
        source: Person
        target: Organization
        sourceIdColumn: person_id
        targetIdColumn: org_id
```

Web sources support all loader types. Use `loader.type: json` for APIs, `text` for raw content, `html` (default) for web pages with optional `selector`. Add `headers` for authenticated endpoints. Use `jsonPath` (e.g., `items` or `data.results`) to extract a nested array from the JSON response before parsing.

## Custom Functions (`functions/<name>.function.mjs`)

```javascript
export const metadata = { name: "my-function", description: "What it does" };
export const parameters = {
  type: "object",
  properties: { input: { type: "string", description: "Input" } },
  required: ["input"]
};
export default async function({ input }) {
  return { result: `Processed: ${input}` };
}
```

Function parameters support automatic type coercion — if an LLM passes a number as a string, it is auto-coerced to the declared type.

## Skills (`skills/<name>/SKILL.md`)

Markdown files with YAML frontmatter (`name`, `description`). Content is injected into the agent's system prompt. Add `sandbox: true` if the skill requires sandbox tools.

## MCP Servers (`mcp.json`)

```json
{ "servers": { "name": { "url": "https://example.com/mcp", "enabled": true } } }
```

Remote: `url`. Local: `command` + `args`. Optional: `headers`, `env`, `timeout`, `transport`, `description`. Transport is auto-detected. To add a server: read `mcp.json`, add entry, write back, then reference as `mcp:<name>` in agent tools.

## Model Configuration (`models.yaml`)

```yaml
version: "1.0"

llm:
  default: omni
  omni:
    provider: omni
    model: gemma-4-E2B-it-IQ4_NL
    reasoningBudget: 0
    contextSize: 32768
    active: true
    share: true
  lmstudio:
    provider: local
    engine: lmstudio
    baseUrl: http://localhost:1234/v1
    model: qwen3.5-4b-mlx
    active: false
  openai:
    provider: openai
    apiKey: ${OPENAI_API_KEY}
    model: gpt-4.1
    active: false

embeddings:
  default: omni
  omni:
    provider: omni
    model: nomic-embed-text-v1.5.Q4_K_M

image:
  default: omni
  omni:
    modelPath: .models/flux2-klein/flux-2-klein-4b-Q4_K_M.gguf
    llm: .models/flux2-klein/Qwen3-4B-Q4_K_M.gguf
    vae: .models/flux2-klein/flux2-vae.safetensors
    steps: 20
    description: flux2-klein
    share: true

tts:
  default: omni
  omni:
    modelPath: .models/qwen3-tts
    description: Qwen3 TTS 0.6B
    share: true
```

The `default` key is a string pointer to another config name. Providers: `omni`, `local`, `openai`, `anthropic`, `gemini`. Use `reasoningBudget`/`thinkingBudget` for thinking models. Use `share: true` to share a model on the P2P network. Values support `${ENV_VAR}` substitution.

## Environment Variable Substitution

All YAML and JSON config files support `${ENV_VAR}` and `${ENV_VAR:-default}` syntax. Use this for secrets, URLs, and any values that differ between environments.

## Best Practices

- Use kebab-case for all resource names
- Temperature: 0.0-0.3 for structured tasks, 0.5-0.7 for creative
- Only include tools the agent actually needs
- Always read existing resources before modifying them
- Check `workspace_list_resources` before creating to avoid name collisions
- Use skills to share knowledge across agents without duplicating prompts