# Add reusable skills and instructions

Package instruction bundles once and attach their immutable versions to an agent profile.

A skill is an instruction bundle with a `SKILL.md` file and optional supporting assets. It shapes the agent's behavior. Business operations belong in explicitly authorized tools. Executable skill scripts are not enabled in this release.

Create a directory such as `skills/release-review` with this `SKILL.md`:

```markdown
# Release review

Review a proposed release in three steps:
1. Identify the user-visible change and its acceptance criteria.
2. List meaningful boundary and failure-path checks.
3. Report observed evidence separately from assumptions.

Use only attached, authorized tools. Ask for clarification when the target
environment or required permissions are missing.
```

Upload the bundle from your backend:

### Python

`upload_directory` packages the directory and its assets.

```python
skill = await agents.skills.upload_directory(
    "skills/release-review",
    name="Release review",
    description="A repeatable review checklist for application releases.",
)
profile = await agents.profiles.create(
    name="Release reviewer",
    instructions="Be concise and cite the observed evidence.",
    skill_ids=[skill.id],
    max_cost_microusd=300_000,
    timeout_seconds=120,
)
session = await agents.sessions.create(
    title="Review release candidate",
    profile_id=profile.id,
)
```

### TypeScript

This example reads only `SKILL.md`. Include every required asset in `files` with a safe relative path and base64-encoded content.

```typescript
import { readFile } from "node:fs/promises"

const content = await readFile("skills/release-review/SKILL.md")
const skill = await agents.skills.create({
  name: "Release review",
  description: "A repeatable review checklist for application releases.",
  files: [
    {
      path: "SKILL.md",
      content_base64: content.toString("base64"),
    },
  ],
})
const profile = await agents.profiles.create({
  name: "Release reviewer",
  instructions: "Be concise and cite the observed evidence.",
  skill_ids: [skill.id],
  max_cost_microusd: 300_000,
  timeout_seconds: 120,
})
const session = await agents.sessions.create({
  title: "Review release candidate",
  profile_id: profile.id,
})
```

Bundles require safe relative paths and a `SKILL.md`. The current limits are 64 files, 1 MiB per file, and 2 MiB total. Binary assets are preserved. Uploaded skill digests and the effective profile revision are retained for an admitted run, so later edits cannot silently change its behavior.

The operator controls available models. A profile may choose a permitted model by its advertised ID. It cannot bypass the account's provider assignment or spending limits. If routing changes, start a new session instead of trying to continue native history under a different provider configuration.
