| name | prompt-engineering |
| description | Write and review LLM prompts and coding-agent instruction files: tighten routing in name/description, behavior defaults, output format constraints, tool-use phrasing, and verification. Triggers: editing system or developer prompts, agent rules, persona files, or files like `SKILL.md`, `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.instructions.md`, `.agent.md`, `.prompt.md`, `.mdc`. |
| license | AGPL-3.0-only |
| metadata | {"author":"marcodsl","tags":"prompts, agents, instructions","version":4} |
Prompt Engineering
Use this skill to write or review prompts, instruction files, and skill bundles so the model gets clear routing, actionable behavior, and portable defaults.
Turn vague prompt ideas into explicit instructions that control output, tool use, reasoning, and instruction layering.
- Writing or editing system prompts, developer prompts, or reusable prompt templates.
- Reviewing coding-agent customization files such as `SKILL.md`, `.instructions.md`, `.agent.md`, `.prompt.md`, and `.mdc`.
- Fixing weak routing, over-aggressive tool rules, vague constraints, or portability problems across agent apps.
<governing_rule>
Say exactly what you want, in the layer that controls that behavior, and write the instruction so the model can follow it without guessing.
</governing_rule>
<working_method>
- Identify the artifact type and control layer before editing anything.
- Rewrite the highest-leverage instructions first: routing, behavior defaults, format constraints, tool use, and verification.
- Keep loaded instructions short; move long examples and reference material into bundled resources.
- Test the rewritten guidance against the real task it is supposed to steer.
</working_method>
- Use model-level prompts to improve reasoning quality, output format, grounding, and consistency.
- Use agent-level instructions to control tool use, safety boundaries, autonomy, context recovery, and multi-step workflows.
- For skills, explain the three-layer loading model explicitly when it matters:
1. `metadata` in frontmatter is the discovery surface. `name` and `description` decide whether the skill can be found.
2. The `SKILL.md` body is the loaded workflow surface. Keep it focused on what to do once the skill loads.
3. Bundled resources are on-demand detail. Move long examples, tables, schemas, and helper material into `references/`, `scripts/`, or `assets/`.
- State the desired output shape and constraints before generation starts.
- Tell the model what to do, not only what to avoid.
- Give motivation for non-obvious rules so the model can generalize them.
- Use few-shot or multishot examples when they materially reduce ambiguity. Keep them relevant and diverse. 3 to 5 well-chosen examples is a good starting point; see `references/prompt-patterns.md` for the full pattern.
- Pick one structure style per file or prompt and stay consistent. For non-trivial prompts and skill files, prefer XML tags for top-level structure; reserve plain markdown for short prompts where tag overhead is not justified.
- Make actions vs suggestions explicit. If you want execution, say to implement or change something instead of merely suggesting improvements.
- Use conditional tool guidance, not blanket defaults. Prefer `Use tool X when...` over `ALWAYS use tool X`.
- Tell the model to parallelize independent tool calls, but only when parameters are already known.
- Prefer provider-native reasoning controls when available. Otherwise ask for focused reasoning plus a concrete verification step.
- Avoid aggressive emphasis (`CRITICAL`, ALL-CAPS, repeated MUSTs) unless you have evidence a target model underfollows normal instructions.
- Start with a portable baseline that works across agents.
- Prefer XML structural tags over vendor-specific syntax when shaping multi-section files. Most agent apps (Claude, Codex, Copilot, OpenCode) parse the body as text and ignore unknown tags, so the same file travels without rewrites.
- Add vendor-specific syntax only when it unlocks a capability the portable version cannot express clearly.
- Keep precedence explicit when repo defaults, scoped instructions, skills, and persona files can stack.
- When multiple layers can apply, state which layer wins and avoid duplicating the same rule across those layers.
- Keep routing text tight. `Use this skill when` and `Do not use this skill when` are routing controls, not filler sections.
- Avoid Markdown tables unless two-dimensional structure is essential and cannot be expressed as bullets. Tables consume significantly more tokens than equivalent bullet lists due to border syntax and padding; prefer `- key: value` or `- trigger → action` formats.
- Name tool availability, confirmation boundaries, and context assumptions explicitly instead of assuming every agent behaves like your primary one.
<review_checklist>
- The discovery surface matches likely user requests.
- Every rule is actionable and tied to a real behavior.
- The prompt names the required output format, grounding expectations, and verification criteria.
- Tool-use guidance is conditional, not over-broad.
- Long examples live in bundled resources instead of bloating the loaded file.
- Tables are only used when two-dimensional structure is essential; bullet lists replace them everywhere else.
- Stacked instruction layers do not repeat the same rule without a clear reason.
- Cross-agent files stay portable, and vendor-only syntax is isolated.
</review_checklist>
<bundled_resources>
references/prompt-patterns.md for prompt structure, long-context patterns, tool-use phrasing, reasoning controls, and the generalizable agentic patterns (grounding, autonomy and safety, state tracking).references/customization-files.md for skill layout, instruction-layer precedence, portability rules, and file-type-specific guidance.references/claude-specific.md for Claude-only patterns (Opus 4.8 lead): effort and adaptive thinking, response verbosity, tool-use triggering, literal instruction following, tone, prefill migration, frontend aesthetics, code-review harness tuning, interactive coding, and other Claude-latest-model specifics.
</bundled_resources>
