kayforkind/skill-slice/agent-prompt-engineering

Claude Code and agent skill by kayforkind/skill-slice

Trust tier 3
  • community
Source check pending

Checking that the SKILL.md file is still in the repository.

Load when writing prompts for sub-agents, generation CLIs (jules, agy, claude-code, opencode, codex), or any model emitting structured artifacts (SVG, JSON specs/ops, code files). Turns vague instructions into machine-checkable contracts with mandatory verification gates. Not for casual chat with no artifact deliverable, and not for authoring a new skill file (create-skill).

Install

npx vskill@latest install kayforkind/skill-slice/agent-prompt-engineering

SKILL.md

The same SKILL.md was published earlier as kayforkind/skill-slice/agent-prompt-engineering.

Overview

This skill generalizes the fix proven in the svg-vault audit: agent-generated output rots when prompts express quality as adjectives and command no verification. The audit found, in one corpus:

DefectCountRoot cause in the prompt
Literal \n / \t / \" escapes in file bodies747 files"Write the SVG file" — no serialization contract, model pasted a JSON-escaped string as bytes
LLM commentary leaked after </svg>94 filesNo "output ends at </svg>, nothing after" rule and no gate to catch it
Duplicate attributes23 filesNo attribute rules, no validator commanded
Mismatched tags12 filesModel hand-wrote XML text; no parse check required

Every defect traces to the same prompt shape: artifact written as free text, quality expressed as adjectives ("clean", "premium", "consistent"), zero verification commanded. The fix that worked: models emit JSON specs/ops validated by ajv, ONE canonical serializer writes bytes, Gate0+Gate2 run on every write. This skill codifies that fix into a repeatable prompt-writing method.

Core principle:

Describe OUTPUT CONSTRAINTS + VERIFICATION, not ADJECTIVES.

An agent cannot act on taste words. "Premium", "clean", "high quality", "consistent", "polished" compile to nothing — the model nods and does whatever it was going to do anyway. A constraint it can check itself against compiles to behavior.

Test every sentence of your prompt with: "Could a validator script enforce this?" If no, either rewrite it until yes, or delete it. A prompt where every requirement is machine-checkable is a prompt whose output is machine-checked.

Corollary: the prompt is a contract, not a mood board. Contracts have (a) an exact deliverable spec, (b) an acceptance test, (c) defined behavior on failure. Your prompt needs all three.

Operational note for this repo: agy (Gemini) is the default heavy-lift CLI, with claude-code, opencode, codex as alternates. jules and agy need heavy hand-holding — assume the agent will do the laziest thing your prompt technically permits.

When to Use

Load this skill when:

  • Writing prompts for sub-agents spawned via delegate_task or similar delegation mechanisms.
  • Writing prompts for generation CLIs: agy, jules, claude-code, opencode, codex.
  • Commissioning any model to emit structured artifacts (SVG, JSON specs/ops, YAML frontmatter, code files, batch icon sets).
  • Reviewing or debugging a delegated prompt that produced defective output (escaped characters, commentary leaks, duplicates, missing files).
  • Designing a verification gate or serializer for a new artifact type.

Do NOT load this skill for casual conversational prompts with no artifact deliverable.

Prerequisites

  • Windows host (primary): PowerShell is the default shell. Use Get-Content / Read for spot-reading artifacts. Path separators in commands should use forward slashes for Node.js scripts (node gate.mjs) but Windows backslash paths (~) for filesystem references.
  • Node.js: Required for gate scripts, serializers, and ajv validation. Ensure node is on PATH.
  • ajv: Install if validating JSON schemas: npm install -g ajv or use a local node_modules copy.
  • Gate scripts: If a gate does not yet exist for the artifact type you are commissioning, write the gate before writing the prompt. A 20-line parser/linter script is cheaper than one triage pass over 747 broken files.
  • Project gates: Inspect gate/serializer files in the target project when you need the svg-vault case study, ajv pipeline, or serializer architecture. This folder does not ship those helpers — write them in the project before the prompt.

Procedure

Step 1 — Replace every adjective with a machine-checkable constraint

Go through your draft prompt. For each quality word ("clean", "premium", "consistent", "robust", "polished"), replace it with one of:

  • A limit: "Max 2 stop-colors per gradient."
  • An allowlist: "Allowed elements: svg, g, path, circle, rect, line, polyline, polygon, defs, linearGradient, stop, title."
  • A forbidden pattern: "No <filter>, no <foreignObject>, no <script>. Contains NO literal two-character sequences \n, \t, or \"."
  • A gate command: "After writing, run node validate.mjs <file>; if it exits non-zero, fix and re-run until it passes."

If a sentence cannot be converted to any of these, delete it. It is padding that the agent will ignore.

Before (produced the 747-file disaster):

Generate 20 SVG icons for the mythology theme. Make them clean, consistent, and premium quality. Save them in assets/mythology/.

Nothing here is checkable. No viewBox rule, no encoding rule, no filename rule, no gate.

After (bulletproof):

Generate 20 SVG icons for the mythology theme into assets/mythology/.
Output contract — every file MUST satisfy all of these (a validator will check):
- File starts with exactly <svg and ends with exactly </svg> followed by a single trailing newline. Zero bytes of prose, markdown, or code fences before or after.
- Contains NO literal two-character sequences \n, \t, or \" — real newlines and real quotes only. If your output pipeline JSON-encodes strings, you are doing it wrong; use the write path below.
- Root: viewBox="0 0 24 24", xmlns="http://www.w3.org/2000/svg". No width/height attributes.
- No element may repeat an attribute name. Allowed elements: svg, g, path, circle, rect, line, polyline, polygon, defs, linearGradient, stop, title. Everything else (including filter, image, script, style, foreignObject) is forbidden.
- Gradients: max 2 <stop> elements. Colors from this palette only: #1A1B2E #4F5D95 #C9A227 #F4F1E8.
- Filenames: myth-{subject}.svg, lowercase kebab-case, ASCII.
Write path: do NOT write SVG text directly. Emit a JSON spec per icon and run node serialize.mjs spec.json — the serializer owns the bytes.
Gate (mandatory): after each write, run node gate.mjs assets/mythology/. Exit code non-zero = you are not done. Read the errors, fix, re-run. Do not report completion until the gate passes on all 20 files.
Step 2 — Embed labeled GOOD/BAD examples for every critical rule

Agents pattern-match examples far more reliably than they interpret adjectives. For every critical rule, embed one GOOD and one BAD sample — the bad one drawn from a real failure.

GOOD (real newlines, single attributes, ends at </svg>):
<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
<path d="M12 2L2 22h20z" fill="#4F5D95"/>
</svg>
BAD — REJECT if your output looks like either of these:
1) Escaped whitespace leaked into the file (this is a JSON string pasted as bytes):
<svg viewBox=\"0 0 24 24\">\n <path d=\"M12 2L2 22h20z\"/>\n</svg>
2) Duplicate attribute + commentary after the close tag:
<svg viewBox="0 0 24 24" viewBox="0 0 24 24">...</svg>
Here is your icon! Let me know if you'd like any changes.

Rules for the examples themselves:

  • Label them GOOD: / BAD — REJECT: explicitly. Unlabeled examples get imitated indiscriminately, including the bad ones.
  • Keep the bad example realistic — copy an actual defective file from a past run, not a strawman. The model needs to recognize its own failure mode.
  • One pair per critical rule. Ten pairs for one rule is padding; zero pairs for a rule the agent keeps breaking is negligence.
Step 3 — Command a verification gate with a bounded loop

"Check your work" and "double-check the output" are adjectives in disguise — the agent will "check" by rereading its own text and approving it. The prompt must command an executable gate with a loop:

After writing each file, RUN:
node gate.mjs <file>
- Exit 0: proceed to the next file.
- Exit non-zero: read stderr, fix THAT file, re-run the gate. Repeat until exit 0.
- If the same file fails the gate 3 times, STOP, do not write more files, and
report the file path + full gate stderr as your final output.
Never report success without pasting the final passing gate command + its output.

Key properties:

  1. A command, not an intention. Name the exact executable and arguments.
  2. A loop, not a glance. Fix → re-run → until pass, with a bounded retry (3) and a defined stop.
  3. Proof of execution. Requiring the agent to paste the gate's output in its report makes "I validated it" falsifiable.
  4. Generate via script, don't write text directly. For any structured format (SVG, JSON, YAML frontmatter), the strongest gate is architectural: the agent emits a spec, a canonical serializer emits bytes. The model never touches the byte stream, so escape/encoding/tag-balance bugs become impossible rather than merely detected. This is the svg-vault's ajv-spec + single-serializer + Gate0/Gate2 design — reuse the pattern anywhere.
Step 4 — Add a dedup / idempotency rule for batch prompts

Batch prompts without a dedup instruction produce duplicates — the agent doesn't know the corpus exists unless told to look. Every batch/generation prompt must state:

  1. The check: "Before creating each item, list existing outputs: ls assets/consolidated/ (or run node manifest.mjs list)."
  2. The dedup key: the exact identity function. E.g. "Two icons are duplicates if they share the same theme + subject slug, regardless of filename casing or visual differences. Key: ${theme}-${subject} lowercase."
  3. The action on hit: "If the key exists: SKIP (do not overwrite, do not create -2/-final/-new variants) and log SKIP <key> in your report."

Without a stated key, the agent invents one per run ("well, this griffin faces left...") and you get near-duplicates. Idempotency is the acceptance test: running the same prompt twice must change nothing on the second run. Say that sentence verbatim in batch prompts — it collapses a whole class of ambiguity.

Step 5 — Define failure behavior explicitly

Unspecified failure handling means the agent proceeds and improvises — it pads malformed input with invented data, skips broken steps silently, and reports success. Every prompt needs a failure clause:

FAILURE RULES:
- Malformed/missing input (spec doesn't parse, referenced file absent, schema
mismatch): do NOT guess or fabricate values. Skip that item, record it in a
`failures` list with the exact error, continue with the rest.
- A required command fails (serializer, gate, git): retry ONCE. Second failure:
STOP the whole run — do not attempt workarounds or alternative tools.
- Final report ALWAYS includes: items succeeded, items skipped (with reasons),
items failed (with errors). "Done" with zero counts is not a valid report.
- NEVER delete or overwrite files not listed in this prompt's scope.

Tune stop-vs-continue per task: a batch of 200 independent icons → skip-and-continue; a 4-step pipeline where step 2 feeds step 3 → stop. The point is that you chose, not the agent.

Step 6 — Make the prompt self-contained

Sub-agents spawned via delegate_task have no parent memory. CLI agents (agy, jules, codex, opencode) see only the prompt text and the filesystem — none of your conversation, none of your mental context, no "as discussed". Pronouns and references like "the usual format", "same as last time", "our palette" resolve to nothing.

Bundle all six blocks into every delegated prompt:

┌─ BULLETPROOF PROMPT TEMPLATE ────────────────────────────────────────────┐
## GOAL (1–3 sentences)
Generate <N> <artifact type> for <purpose> into <exact path>.
## INPUTS
- <path/to/input1> — <what it is, exact schema/format>
- (Paste small inputs inline; give absolute paths for large ones.)

This is the start of the file. Read the full SKILL.md on GitHub.

Security

  • Security scanPassed, 95 of 100Pattern checks on the skill's files.
  • Model reviewPassed

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

Source

Popularity

7-day trend score
5

Not refreshed yet.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/kayforkind/skill-slice/agent-prompt-engineering/badge)](https://verified-skill.com/skills/kayforkind/skill-slice/agent-prompt-engineering)

Something wrong with this skill or its page? Tell us.