---
source_keys: []
---

# Scripts Reference

Conventions for `scripts/new-agent.sh` and any future scripts in this skill.

## Contract

All scripts in this skill must follow these rules:

- **No interactive prompts** — agents run non-interactive; blocking on TTY input hangs indefinitely. Accept all input via positional arguments, flags, or environment variables.
- **Structured output** — file paths and status messages to stderr; nothing to stdout unless a downstream tool needs to consume it.
- **Idempotent** — "create if not exists" per file. The scaffold script skips any file that already exists; agents may safely re-run it.
- **Meaningful exit codes** — `0` success, `1` invalid arguments or precondition failure. Document in `--help`.
- **Self-contained** — no external package installs at runtime. The script uses only bash builtins and POSIX tools (`sed`, `mkdir`, `cat`).
- **No restated field rosters** — no script output, in `--help` or in next-steps guidance, enumerates permitted, forbidden, or required frontmatter fields. Point at the `apm-agent-allowlist` section of `agent-audit`'s `references/field-inventory.md`, which `agent-audit`'s `validate.sh` reads from there as data. A roster copied into script output goes stale one step further out than the list itself: the next-steps hint `(name, description, model, body only)` kept printing after ADR-0016's 2026-08-14 amendment added `disallowedTools` to the permitted set. `tests/new-agent.bats` enforces this for the plugin/APM branch — naming some allowlisted fields but not all is a failure.

## Template variables

The scaffold script uses `sed "s/AGENT_NAME/$AGENT_NAME/g"` to substitute the agent name into templates. Template files must use `AGENT_NAME` (all caps, no delimiters) as the substitution token.

Do not add additional substitution tokens unless you update both the template files and the script in the same edit pass.

## File placement

The script creates files at paths determined by scope detection (plugin/APM / project / user). Scope is resolved by walking up from the root directory: a `type:`-bearing `apm.yml` at or above the root marks the package root (plugin/APM scope, single file); an `apm.yml` without a `type:` field is a marketplace-only manifest and is skipped, the walk continues upward. If no such `apm.yml` is found, the root resolving to exactly `$HOME` is user scope; anything else is project scope. If scope detection logic changes, update the `new-agent.sh` usage comment and `SKILL.md` Step 1 scope detection description in the same pass.

## Error messages

On failure, state: what went wrong, what was expected, what to try. Example:
```
Error: agent-name must use lowercase letters, numbers, and hyphens only.
       No leading, trailing, or consecutive hyphens.
       Received: 'My_Agent'
```

Vague errors leave agents unable to self-correct.

## --help output

Keep `--help` concise — it may enter the agent's context window. Include: usage line, argument descriptions with scope detection table, exit codes. Omit prose explanations.