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.

Skills are an emerging capability. Today, declaring one or more skills on an agent (together with a skill hint) adds that hint to the agent’s system prompt. The declaration is stored on the agent so it travels with export, import, and versioning, ready for richer skill behavior as the platform grows.

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.

Declare a skill on the agent

Add an entry to the agent’s skills list. Each entry has an id, a human-readable name, and an optional config object for future skill-specific settings.

Write a skill hint

Set skill_hint on the agent. This is the instruction text that tells the model what the declared skills are for and when to apply them.

The agent runs

When execution reaches the agent, the system prompt is assembled from its parts: persona, then the tool hint, then the knowledge-base hint, then the skill hint.

The skill hint is applied

The skill hint is appended only when the agent has at least one skill declared and a skill hint is set. If either is missing, the section is skipped entirely.

The model follows the guidance

The model reads the combined prompt, including the skill hint, and applies it while it reasons, calls tools, and produces its output.

The skill hint is additive prompt context, not a hard gate. A declared skill with no hint has no effect on the prompt, and a hint with no declared skill is ignored. Both conditions must be met.

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": {}
    }
  ]
}

Field	Required	Description
`id`	Yes	Stable identifier for the skill within the agent.
`name`	Yes	Human-readable name, up to 255 characters.
`config`	No	Object for skill-specific settings. Defaults to empty.

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"]
    }
  }
}

Prompt-based rules guide the model but do not guarantee compliance. For a rule that must hold every time, back it with the output schema guardrail, a Condition node that checks the result, or a Human Task for approval, rather than relying on instructions alone.

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

Pair every skill with a hint

A declared skill only affects the agent when a skill hint is also set. If you add a skill, write the hint that tells the model when to use it, otherwise the declaration has no effect on the prompt.

Keep hints about when, not what

The skill hint works best as guidance on when to apply a capability and what to check first. Put the detailed procedure in the persona instructions, and use the hint to point the model at it at the right moment.

Use stable skill ids

Give each skill a stable, meaningful id. Because skills travel with the agent through export, import, and versioning, a stable id keeps configurations comparable across environments.

Enforce hard rules, don't just ask for them

Instructions guide the model but can be overridden by a persuasive prompt. For rules that must hold, add the output schema guardrail, a Condition node, or a Human Task so the boundary is enforced by the workflow, not the wording.

Write rules positively and specifically

“Always cite the order id you acted on” is easier for the model to honor than a vague “be accurate.” Specific, testable rules also make it obvious what a downstream validation step should check.

Think of skills and rules as two halves of the same job: skills tell the agent what it can do and when, and rules define what it must and must not do. Declare the capability as a skill, state the boundary as a rule in the persona, and enforce the boundaries that matter with a guardrail or a workflow check.

Next steps

Personas and prompts

Write the persona instructions and guardrails that carry an agent’s rules

Agent overview

See how skills fit into an agent’s full configuration

Tools overview

Give an agent concrete capabilities it can call as tools

Knowledge bases

Attach searchable content for the agent to ground its answers

Getting Started

Platform Guide

Agents

Workflow Builder

Tools & Integrations

Models & Providers

Cookbooks

Security & Administration

Purpose

How it works

Configuration

Declaring skills

Writing the skill hint

Rules and behavioral guardrails

Use cases

Name a recurring capability

Enforce an output contract

Keep an agent inside its lane

Best practices

Next steps

Personas and prompts

Agent overview

Tools overview

Knowledge bases

​Purpose

​How it works

​Configuration

​Declaring skills

​Writing the skill hint

​Rules and behavioral guardrails

​Use cases

​Name a recurring capability

​Enforce an output contract

​Keep an agent inside its lane

​Best practices

​Next steps

Personas and prompts

Agent overview

Tools overview

Knowledge bases

Purpose

How it works

Configuration

Declaring skills

Writing the skill hint

Rules and behavioral guardrails

Use cases

Name a recurring capability

Enforce an output contract

Keep an agent inside its lane

Best practices

Next steps