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

# Standards-Native Agents and Evals

> Define managed agent behavior with AGENTS.md, Markdown skills, eval rubrics, production traces, and explicit improvement objectives.

Sikaru accepts behavior sources your team can review in a product repo: instructions, skills, and eval rubrics written as Markdown. These standards files give managed agents durable intent, while Experience trajectories and OpenInference-compatible traces show what happened in production.

This is how Sikaru connects the evals domain to continual learning: eval rubrics define what good means, production traces reveal where behavior falls short, and reviewed improvements update the managed agent without handing Sikaru your credentials or customer-facing application surface.

## File convention

A minimal agent artifact looks like this:

```text theme={null}
support-agent/
  AGENTS.md
  agent.py
  skills/
    refunds.md
    crm.md
  evals/
    refund-quality.md
```

| Source        | Meaning                                               |
| ------------- | ----------------------------------------------------- |
| `AGENTS.md`   | Operating instructions for the agent.                 |
| `skills/*.md` | Playbooks, tool notes, or task-specific behavior.     |
| `evals/*.md`  | Rubrics that define what good behavior means.         |
| `SKILL.md`    | Agent Skills-style skill files for existing projects. |

## Load standards in Python

Python can pass Markdown paths directly from an agent artifact.

```python theme={null}
from sikaru_sdk import Sikaru, tool

sikaru = Sikaru(project="proj_123")

@tool("crm.search")
def search_crm(account_id: str):
    return {"account_id": account_id}

support = (
    sikaru.agent(
        "support",
        instructions="AGENTS.md",
        skills=["skills/refunds.md"],
        evals=["evals/refund-quality.md"],
        tools=[search_crm],
    )
    .define(outcomes=["task_success", "refund_accuracy"])
)
```

`from_standards(".")` reads `AGENTS.md`, Markdown files under `skills/`, and Markdown files under `evals/`.

```python theme={null}
support = sikaru.agent("support", tools=[search_crm]).from_standards(".")
```

Older `agent.md`, `skills.md`, and Agent Skills `SKILL.md` files remain supported for existing projects.

## Load standards in TypeScript

TypeScript usually passes file contents from the product server or build step.

```ts theme={null}
const support = sikaru
  .agent("support", {
    instructions: { path: "AGENTS.md", content: agentsMd },
    skills: [{ path: "skills/refunds.md", content: refundSkill }],
    evals: [{ path: "evals/refund-quality.md", content: refundQualityEval }],
  })
  .tools({ searchCrm })
  .define({
    instructions: "Resolve billing issues and ask for approval before large refunds.",
    outcomes: ["task_success", "refund_accuracy"],
  });
```

## Keep traces separate from behavior

Behavior files describe how the agent should behave. Traces show what actually happened.

```python theme={null}
sikaru.traces.upload_file("./support-openinference.jsonl", dataset="prod")
```

This separation lets Sikaru compare intent, production evidence, and eval results without asking you to upload a runnable production harness.

## Attach eval objectives

Use `capture` when you have static eval references and an improvement objective.

```python theme={null}
(
    sikaru.capture("support")
    .evals(
        uri="r2://acme-support/evals/support-quality.yaml",
        primary_metric="task_success",
    )
    .improve("increase task_success without increasing escalation mistakes")
    .submit()
)
```

## What Sikaru does with standards

Sikaru reads these files as customer-authored intent, runs them through a Sikaru-managed harness, and compares future proposals against private evals and production evidence. Proposed improvements are reviewable before promotion.

<Note>
  Sikaru does not ask for production credentials inside Markdown files. Keep credentials in your product services and expose only tool capabilities through the SDK.
</Note>