> ## Documentation Index
> Fetch the complete documentation index at: https://helpcenter.magure.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills and rules

> Attach reusable skill declarations to an agent and enforce the behavioral rules it must follow

## 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](/tools/overview) are concrete integrations the agent can call and [knowledge bases](/agents/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](/agents/personas-and-prompts) and its [guardrails](/agents/personas-and-prompts) rather than a separate configuration block, so this page covers both: how to declare skills, and how to hold an agent to its rules.

<Note>
  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.
</Note>

## 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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Note>
  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.
</Note>

## 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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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](/agents/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.

```json theme={null}
{
  "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"]
    }
  }
}
```

<Warning>
  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](/workflows/condition-node) that checks the result, or a [Human Task](/workflows/human-task-node) for approval, rather than relying on instructions alone.
</Warning>

## 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.

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

<Tip>
  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.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Personas and prompts" icon="user-pen" href="/agents/personas-and-prompts">
    Write the persona instructions and guardrails that carry an agent's rules
  </Card>

  <Card title="Agent overview" icon="robot" href="/agents/overview">
    See how skills fit into an agent's full configuration
  </Card>

  <Card title="Tools overview" icon="wrench" href="/tools/overview">
    Give an agent concrete capabilities it can call as tools
  </Card>

  <Card title="Knowledge bases" icon="book" href="/agents/knowledge-bases">
    Attach searchable content for the agent to ground its answers
  </Card>
</CardGroup>