prompt-best-practices

Prompt Best Practices

An AI agent skill that transforms unstructured prompts into high-quality structured prompts through a short interactive dialogue. Works with any AI agent that supports the Agent Skills open standard.

First-class support for both Anthropic Claude and OpenAI Codex. The 7-component framework was built by studying the prompting guidelines published by the major LLM providers. The canonical reference is Anthropic's prompting best practices — the most comprehensive publicly available guide on the subject — with each component mapped to a specific section of that documentation. The framework then maps 1:1 onto the OpenAI Codex Starter Prompt sections, and dedicated tuning notes for each runtime live in skill/references/claude-considerations.md and skill/references/codex-considerations.md. The underlying principles — clear tasks, structured context, concrete examples, well-motivated constraints — are shared across providers and improve output quality on any LLM.

The Problem

Most prompts sent to AI agents lack the structure needed to produce reliable, high-quality output. Users provide a vague goal — "write me an email", "build this feature" — without defining success criteria, output format, constraints, or context. The model fills in the blanks with assumptions, and what follows is multiple rounds of corrections to converge on what the user actually wanted.

This skill reduces that cycle. It intercepts underspecified prompts and guides you through a short, tier-adaptive dialogue (up to 2 questions for quick tasks, up to 5 for complex ones) to surface the missing information. The result is a structured prompt sized to the task weight.

Non-goals

• Not a guarantee of better output. The framework encodes well-documented heuristics but makes no empirical claim without a benchmark run. See tests/benchmark-protocol.md for how to measure effect size on your workload.
• Not a generic writing coach. It skips questions, micro-tasks, and conversational exchanges. See tests/activation-fixtures.md for the exact contract.
• Not XML-only. Structure is format-agnostic (XML, Markdown, JSON all qualify). XML is the Claude default.
• Not a framework factory. The 7 components are the framework. PRs adding new components belong in a fork. See CONTRIBUTING.md > Scope and non-goals.

Demo

Installation

One command. No configuration, no dependencies, no setup files to edit.

Via skills.sh (any compatible agent)

npx skills add gquattromani/prompt-best-practices -g -y

Via Claude Code plugin

/plugin marketplace add gquattromani/prompt-best-practices
/plugin install prompt-best-practices@prompt-best-practices

This installs the skill globally. It is immediately available in every project, in every agent that supports the Agent Skills standard.

Usage

/prompt-best-practices

The skill activates automatically when you ask to write, draft, generate, implement, fix, refactor, or build any output that lacks clear structure. Invoke it explicitly via slash command to force activation on any prompt.

How It Works

The skill evaluates your prompt against 7 components, each grounded in a specific section of Anthropic's prompting guide: