---
source_keys:
  - agentskills-spec
  - agentskills-using-scripts
---

# Formatting and Scripts Reference

Upstream source: agentskills.io — specification (body content), using-scripts (designing scripts
for agentic use).

Read this when judging the **formatting** and **scripts** dimensions. Both are checklists of static
criteria that never vary by skill, which is exactly why they live here rather than in the body.

## Formatting

- Heading levels are consistent: H2 for main sections, H3 for subsections. A body that jumps from
  H2 to H4, or opens on H3, reads as a fragment of a larger document.
- Code blocks carry a language tag wherever one applies — `bash`, `markdown`, `python`, `yaml`,
  `text`. An untagged block loses syntax highlighting and, more importantly, loses the signal of
  what the agent is meant to do with it.
- Whitespace is consistent: a blank line between sections, one list-indentation style throughout.
- No broken relative paths in file references. Every `references/…`, `scripts/…` and `assets/…`
  path named in the body resolves against the skill directory.

## Scripts

A script in a skill is run by an agent with no terminal and no human to answer it. The criteria
follow from that:

- **No interactive TTY prompts** — no `read`, no `input()`, no `readline`. A script that blocks on
  a prompt hangs the run with no diagnostic. `validate.sh` detects the common forms and reports
  them under Structure; the judgment call is any prompt it cannot pattern-match. What counts is
  where stdin comes from, not the word `read`: a `read` fed by a here-string, a here-doc, a pipe,
  or a redirect from a file never touches a terminal and is not a finding. `validate.sh` excludes
  those forms, so do not rewrite a working `read -r A B <<< "$line"` into parameter expansion to
  satisfy this rule.
- **`--help` is exposed** and gives concise usage.
- **Data to stdout, diagnostics to stderr.** A caller piping the script has to be able to separate
  the result from the commentary.
- **Idempotent** — "create if not exists" rather than "create", so a re-run after a partial failure
  is safe.
- **Meaningful exit codes, documented in `--help`.** An agent branches on the exit code; an
  undocumented one is a coin flip.
- **`--dry-run` present for destructive operations.**

The FAIL and SUGGESTION criteria for this dimension live in `references/finding-criteria.md`,
which Step 3 loads on every run.