Skills and rules

Purpose

Skills let you declare a named, reusable capability on an agent and give the model guidance on when to reach for it. Where tools are concrete integrations the agent can call and knowledge bases are content it can search, a skill is a lightweight, named unit you attach to the agent's configuration alongside a skill hint that teaches the model how to apply it.

Rules are the behavioral boundaries an agent must respect: the constraints, tone, and output shape you want enforced no matter what the user asks. On MagOneAI these are expressed through the agent's persona instructions and its guardrails rather than a separate configuration block, so this page covers both: how to declare skills, and how to hold an agent to its rules.

How it works

Skills live inside an agent's config_json, so they are scoped to the agent and, through it, to the project the agent belongs to. At prompt-assembly time the platform folds the skill hint into the system prompt in a fixed order, after the persona, the tool and file-tool sections, and the knowledge-base hint. When agentic retrieval is enabled an agentic knowledge-base section can follow it, so the skill hint is the last of the hint sections rather than always the final line of the prompt.

Configuration

Declaring skills

Skills are a list on the agent config. Provide a stable id and a descriptive name; leave config empty unless a skill defines its own settings.

{
  "skills": [
    {
      "id": "refund-calculation",
      "name": "Refund calculation",
      "config": {}
    }
  ]
}

Writing the skill hint

The skill hint is the prompt text that activates the declared skills. Keep it focused on when and how the model should apply them.

{
  "skill_hint": "You can perform refund calculations. Apply this skill only after you have confirmed the order total and the customer's eligibility window.",
  "skills": [
    { "id": "refund-calculation", "name": "Refund calculation", "config": {} }
  ]
}

The hint is limited to 2000 characters. It is only added to the prompt when the skills list is non-empty, so a hint on an agent with no skills is inert.

Rules and behavioral guardrails

MagOneAI does not have a standalone "rules" object. The behavioral rules an agent must follow are set in two places, both on the agent:

• Persona instructions carry the soft rules: tone, scope, what the agent should refuse, and the order it should work in. This is where most day-to-day rules live. See personas and prompts.
• The output schema guardrail carries the hard rules about shape. Set guardrails.output_schema to a JSON Schema and the agent's output is validated against it at runtime, so downstream nodes always receive the structure they expect.

{
  "persona": {
    "name": "Refund Assistant",
    "role": "Customer refund specialist",
    "instructions": "Never approve a refund above 500 without a human approval. Always cite the order id you acted on."
  },
  "guardrails": {
    "output_schema": {
      "type": "object",
      "properties": {
        "order_id": { "type": "string" },
        "refund_amount": { "type": "number" }
      },
      "required": ["order_id", "refund_amount"]
    }
  }
}

Use cases

Name a recurring capability

Scenario: Several agents in a project perform the same specialized step, such as calculating a pro-rated refund. Declaring it as a named skill with a shared hint makes the capability explicit in each agent's configuration and keeps the guidance consistent.

{
  "skills": [
    { "id": "prorate-refund", "name": "Prorate refund", "config": {} }
  ],
  "skill_hint": "Prorate refunds by unused days remaining in the billing period."
}

Enforce an output contract

Scenario: A workflow expects every agent to return a decision and a reason. Encode that as a rule with the output schema guardrail so the contract is validated, not just requested.

Workflow:
  1. Analyze request (Agent, output_schema = { decision, reason })
  2. Condition: decision == "approve"
     ├─ True: Continue processing
     └─ False: Human Task: "Review rejected request"

Keep an agent inside its lane

Scenario: A support agent must never discuss pricing changes. Put the rule in the persona instructions and add a validation step for the cases that matter most.

Workflow:
  1. Draft reply (Agent, instructions include the "no pricing" rule)
  2. Condition: reply mentions restricted topics
     ├─ True: Human Task: "Review before sending"
     └─ False: Send reply (Tool)

Best practices

Next steps