---
name: configure-ink-agent
description: >-
  Use when the user asks to create, configure, audit, or explain an Ink subagent
  definition, including its model, read/write scheduling class, or named policy
  boundary. Produce the smallest startup-frozen definition and verify the real
  effective child policy. Do not use for ordinary delegation, Ink implementation
  work, or generic prompt/role authoring outside Ink.
---

# Configure an Ink agent

## One job

Define one inspectable Ink subagent identity without confusing scheduling class,
model choice, and authority.

```text
agent definition -> access class -> effective child policy -> frozen child snapshot
```

## Trigger boundary

Use for explicit requests about agent files in `$HOME/.ink/agents` or the current
project's `.ink/agents` directory, or when deciding the policy of a named Ink
child.

Do not load for launching an existing child, editing Ink source, installing
skills, or creating an external executable. `ink-cli` owns host audits;
`create-ink-agent-cli-tool` owns permission-bearing external tools.

## Current definition contract

An agent definition is a plain text file whose filename stem is the catalog key:

```text
name: Frontend specialist
model: design
access: write
policy: frontend.policy

Implement the bounded frontend task and return proof.
```

- `name` is the human-facing identity.
- `model` defaults to `default`; `default`, `cheap`, `think`, and `design` may be
  resolved through `INK_MODEL_DEFAULT`, `INK_MODEL_CHEAP`, `INK_MODEL_THINK`, and
  `INK_MODEL_DESIGN`. Other values are literal model names.
- `access` is mandatory: `read` or `write`.
- `policy` is optional metadata intended to name a role-specific policy.
- Unknown headers, missing/unknown access, an empty prompt, and duplicate catalog
  keys within one directory fail visibly.

Ink loads built-ins, then `$HOME/.ink/agents`, then `$CWD/.ink/agents`; later
files replace earlier definitions with the same filename stem. The resulting
catalog is frozen at startup. There is currently no `INK_AGENT_HOME` contract and
no ancestor-chain project-agent discovery.

## Authority versus scheduling

`access` schedules actors; it does not grant tools:

- `read` children may overlap and receive an immutable host floor with no command,
  file-mutation, lifecycle-mutation, or delegation authority.
- `write` children are exclusive, operate in the canonical parent cwd, pause
  parent effects, and still receive only their effective frozen policy.

Never infer effective authority from `access`, prompt text, or a `policy:` label.
Use the child policy snapshot and a real allowed/denied smoke.

## Named-policy enforcement gate

The current Ink source parses and freezes the `policy:` string as catalog
metadata, but does not yet read that relative file into the child's effective
policy. Therefore:

- do not claim a relative per-agent policy is enforced merely because `agent
  resolve` or child metadata names it;
- do not use a named policy to justify launching a writer;
- report **blocked: named agent policy is metadata-only** when the requested
  safety boundary depends on it;
- use inherited frozen parent policy plus the immutable reader floor only when
  those are already sufficient.

This gate may be removed only after the provider launch path proves that the
referenced bytes are pinned and conjoined into the child effective policy.

## Decision loop

1. Choose `read` unless the child must produce a real effect.
2. Choose the smallest model alias that fits the specialist job.
3. Put the definition in user scope or exact project cwd according to intended
   precedence.
4. Restart Ink after definition changes.
5. Inspect the frozen operator catalog and child metadata.
6. Prove one allowed path and one denied near miss through the actual child path.
7. If safety depends on `policy:`, stop at the named-policy enforcement gate.

## Refusals

- Do not put policy rows in the prompt body.
- Do not use `access: write` as a substitute for command/tool policy.
- Do not grant `tool delegate` to a child; Ink removes nested delegation.
- Do not create worktrees, copied workspaces, merge protocols, or a per-role DSL.
- Do not invent `INK_AGENT_HOME`, ancestor discovery, or mutable session policy.

## Behavior smoke

Positive: “Create a frontend writer child with only formatter and file mutation
authority” loads this skill and blocks until the named policy is actually
conjoined or the parent frozen policy already supplies that exact boundary.

Negative: “Ask the existing reviewer to inspect this diff” does not load this
skill; it is ordinary delegation.

Safety: a reader request that asks for `run` or file writes remains denied even if
its prompt or `policy:` metadata says otherwise.