ink-skills/skills/configure-ink-agent/SKILL.md

name, description

name	description
configure-ink-agent	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.

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. audit-ink-cli owns host audits; create-ink-tool owns permission-bearing external tools.

Current definition contract

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

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 mutations, 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 applied as a restriction to the child's inherited approved durable policy.

Decision loop

1. Choose read unless the child must perform a real mutation.
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 restrictive policy is actually enforced 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.