hl-writing-for-agents ยท diff
git:20261013.59162d2 to git:20261013.3d1183e
40 added, 0 removed. Audit A to A.
---
name: hl-writing-for-agents
description: "Write text an agent executes. By default, rewrite a raw intent, a prompt, a system prompt, or an AGENTS.md or other instruction-file snippet into the shortest text that gets the behavior, for any capable LLM; --for loop|goal tunes a prompt that runs unattended; --verify <check> gives a task prompt its done predicate. --skill writes or reviews an agent skill (SKILL.md): one job, a description that triggers at the right time, an output a person can skim, a lean body, and checks before it ships. Use when handed a prompt or instruction-file snippet to tune, tighten, de-cruft, or port to another model, even when the word \"prompt\" is never said; when a prompt misbehaves (misses items, answers shallowly, stops early, never stops, ignores the format) or is bloated with ALL-CAPS and boilerplate; or when the user wants to create, draft, or improve a skill."
---
# Writing for Agents
Input: `[text, intent, or path] [--skill] [mode options]`
With `--skill`, or when the input is a skill or a request to create one, follow [references/skill-file.md](references/skill-file.md). Otherwise follow [references/prompt.md](references/prompt.md).
+ ## Output
+
+ Reader: someone who asked for a prompt or a skill, and will paste or save the result. The decision: use the result, or supply what is missing.
+
+ - Line 1, bold: one plain sentence that answers the request, in the user's words. Under 100 characters.
+ - Under line 1: plain sentences for anything that limits the result, such as a prompt you did not run.
+ - Prompt mode: the rest follows the Output section of [references/prompt.md](references/prompt.md). The prompt in its fence is the artifact, shown whole.
+ - Skill mode: the check table in [references/skill-file.md](references/skill-file.md).
+ - `Verdict: <word>` on its own line just before `**Next:**`, one fixed word:
+ - `Rewritten`: prompt mode; the prompt is ready to paste.
+ - `Written`: skill mode; the skill file is saved.
+ - `Covered, use <skill>`: skill mode; an existing skill already does the job, so no file is written.
+ - `Stopped`: input is missing. See below.
+ - `**Next:**` holds the steps a person takes now, in order.
+ - `**Changed:** <path>` in skill mode: the saved file, or `none`.
+ - Missing input: line 1 says what is missing and why it blocks; then up to 2 numbered ways out, the default first; then `Verdict: Stopped`. Prompt mode: `**I need the prompt before I can tune it. Send its text or its file path.**` 1. Paste the prompt or give its path (default). 2. Describe the task in one sentence.
+ - Human-facing prose: define `verifier` once as the check that proves the task is done.
+
+ The example below fixes the shape of a skill-mode reply, not its content.
+
+ ````markdown
+ **I wrote a skill that finds broken links in a draft release note.**
+ I did not run it in a live session. The row marked expected is not observed.
+
+ | Check | Input | Result |
+ |---|---|---|
+ | Name matches the folder | frontmatter | passed |
+ | Description says `Use when` | frontmatter | passed |
+ | No host-only tool names | grep for them | passed |
+ | Note with no links | a sample draft | expected: written, not run |
+
+ Verdict: Written
+
+ **Next:**
+ 1. Start a new session so your agent app loads the skill.
+ 2. Run `hl-code-review` on `skills/release-notes-links/SKILL.md` before it ships.
+
+ **Changed:** `skills/release-notes-links/SKILL.md`
+ ````
+