{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://docs.nylorun.com/schemas/agent-folder/v1/agent-md.4.json",
  "title": "Nylorun agent folder: AGENT.md frontmatter",
  "description": "The frontmatter of an agent folder's AGENT.md; the body below it is the instructions",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$",
      "description": "The agent manifest's name, the folder's when it is saved under one"
    },
    "description": {
      "type": "string",
      "minLength": 1,
      "description": "What the agent does, in a sentence"
    },
    "format": {
      "enum": [
        1,
        2,
        3,
        "agent-folder/1",
        "agent-folder/2",
        "agent-folder/3"
      ],
      "description": "The folder's format: agent-folder/1 (or 1, the default), which gets every engine feature by default; agent-folder/2 (or 2), which declares each in engine; or agent-folder/3 (or 3), which declares the Runtime's features as plugins"
    },
    "harness": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]{1,62}$",
      "description": "The harness that runs the loop: nylorun (ours, the default) or a custom harness's id"
    },
    "inputSchema": {
      "$ref": "#/$defs/JsonSchemaOrPath",
      "description": "A flow's input (a folder with flow.json); an agent's input is the message"
    },
    "outputSchema": {
      "$ref": "#/$defs/JsonSchemaOrPath",
      "description": "The JSON Schema of the agent's final answer"
    },
    "mcpServers": {
      "type": "object",
      "propertyNames": {
        "pattern": "^[A-Za-z0-9_-]{1,64}$"
      },
      "additionalProperties": {
        "$ref": "#/$defs/McpServerSettings"
      },
      "description": "How this agent uses each MCP server of mcp.json or a plugin, by its name"
    },
    "skills": {
      "type": "object",
      "additionalProperties": {
        "type": "object",
        "properties": {
          "secrets": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
            },
            "description": "The secret slots the skill's scripts read, as environment variables"
          }
        },
        "additionalProperties": false
      },
      "description": "This agent's settings for each skill of skills/ or a plugin, by its name"
    },
    "memory": {
      "type": "object",
      "properties": {
        "access": {
          "description": "`read_write` (the default) or `read_only`",
          "type": "string",
          "enum": [
            "read_write",
            "read_only"
          ]
        },
        "instructions": {
          "description": "What this agent should remember, after the engine's own memory rules",
          "type": "string",
          "maxLength": 4096
        },
        "index": {
          "description": "agent-folder/2: false pins no memory index in a session. Default true",
          "type": "boolean"
        }
      },
      "additionalProperties": false,
      "description": "The Agent's memory: Markdown files under /memories it keeps across sessions"
    },
    "loop": {
      "type": "object",
      "description": "The harness's own settings, passed to it each turn; the nylorun harness reads plan (true offers the agent update_plan) and connections (true offers it request_connection)"
    },
    "plugins": {
      "type": "array",
      "items": {
        "enum": [
          "nylorun-memory",
          "nylorun-triggers",
          "nylorun-plan",
          "nylorun-interactions",
          "nylorun-artifacts",
          "nylorun-sandbox"
        ]
      },
      "uniqueItems": true,
      "description": "agent-folder/3: the Runtime's plugins the agent uses, which share the server nylorun (mcpServers.nylorun.tools turns one of their tools off): nylorun-memory, nylorun-triggers, nylorun-plan, nylorun-interactions, nylorun-artifacts, nylorun-sandbox (needs a computer)"
    },
    "model": {
      "type": "string",
      "maxLength": 200,
      "pattern": "^[A-Za-z0-9._-]+\\/\\S+$",
      "description": "The model the agent runs on: <provider>/<model>, such as anthropic/claude-sonnet-4-5"
    },
    "engine": {
      "type": "object",
      "description": "agent-folder/2: the engine features the agent uses, and nothing else is added: sandbox (the sandbox tools), artifacts (read_artifact, save_artifact), outputs (the outputs folder), toolSearch (MCP tools deferred past the threshold), triggers (the triggers tool, the root agent's), instructions (a block's wording, from a file under engine/)",
      "properties": {
        "sandbox": {
          "type": "array",
          "items": {
            "enum": [
              "bash",
              "read",
              "write",
              "edit",
              "grep",
              "glob"
            ]
          },
          "uniqueItems": true,
          "description": "The sandbox tools offered: any of bash, read, write, edit, grep and glob; needs a computer in runtime.json"
        },
        "artifacts": {
          "type": "object",
          "properties": {
            "read": {
              "type": "boolean",
              "description": "read_artifact, and the text on results too large to show and files of earlier turns"
            },
            "save": {
              "type": "boolean",
              "description": "save_artifact and its text; needs a computer"
            }
          },
          "additionalProperties": false
        },
        "outputs": {
          "type": "boolean",
          "description": "Save /workspace/outputs as the session's outputs folder when a turn ends; needs a computer"
        },
        "toolSearch": {
          "type": "boolean",
          "description": "Defer the MCP tools behind tool_search when their schemas pass the threshold; a server's own deferred applies either way"
        },
        "triggers": {
          "type": "boolean",
          "description": "The triggers tool and its text: the agent sets up its own schedules and follow-ups, kept by the Agent; the root agent's only"
        },
        "instructions": {
          "type": "object",
          "propertyNames": {
            "enum": [
              "skills",
              "sandbox",
              "skill_folder",
              "artifacts_save",
              "outputs",
              "artifacts_read",
              "wake",
              "triggers",
              "memory",
              "plan",
              "connection",
              "tool_search"
            ]
          },
          "additionalProperties": {
            "type": "string",
            "pattern": "^(\\./)?engine/.+\\.md$"
          },
          "description": "A block's wording, replaced by a Markdown file under engine/, by block name; the memory rule that outside text is data stays"
        }
      },
      "additionalProperties": false
    },
    "metadata": {
      "type": "object",
      "description": "The manifest's metadata, as it is"
    }
  },
  "required": [
    "name",
    "description"
  ],
  "additionalProperties": false,
  "$defs": {
    "JsonSchemaOrPath": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "\\.json$",
          "description": "The path of a JSON Schema file in the folder (./output.schema.json; /schemas/x.json from the uploaded folder's root), named *.schema.json or kept under schemas/"
        },
        {
          "type": "object",
          "description": "A JSON Schema (2020-12), inline"
        }
      ]
    },
    "McpServerSettings": {
      "type": "object",
      "properties": {
        "deferred": {
          "type": "boolean",
          "description": "Offer the server's tools on demand, by search, instead of in every turn"
        },
        "tools": {
          "type": "object",
          "additionalProperties": {
            "type": "object",
            "properties": {
              "enabled": {
                "type": "boolean"
              },
              "deferred": {
                "type": "boolean"
              }
            },
            "additionalProperties": false
          },
          "description": "Settings for each of the server's tools by name, \"*\" for the rest; approval is the Tenant's tool policy, not set here"
        },
        "credential": {
          "type": "string",
          "pattern": "^[A-Za-z0-9._-]{1,64}$",
          "description": "The secret slot a plugin's server authenticates with, which the plugin cannot name; a server of mcp.json names it in a header"
        }
      },
      "additionalProperties": false
    }
  }
}
