Structure Over Length
The most common mistake in system prompt writing is trying to cover every possible scenario in a wall of text. Models respond better to structured prompts that clearly separate different types of instructions: role definition, process steps, output format, constraints, and examples.
A structured prompt might have a role section ("You're a code reviewer specializing in Python"), a process section ("For each file, check for: unused imports, missing type hints, security issues, and performance concerns"), an output section ("Present findings as a numbered list with severity ratings"), and a constraints section ("Don't suggest stylistic changes unless they affect readability").
This structure helps the model understand what's important and what to focus on at each stage of its processing. It also makes the prompt easier for humans to review, modify, and maintain.
Be Specific About What You Want
Vague instructions produce vague results. "Analyze the code" can mean anything. "Check each function for missing error handling, identify any database queries that don't use parameterized inputs, and flag any hardcoded credentials" tells the model exactly what to look for.
When writing AI skills, specificity is your primary tool for quality control. Every ambiguity in your prompt is a place where the model will make a judgment call, and those judgment calls may not match your expectations. The more specific you are, the less the model needs to guess.
Include Examples
Examples are the most effective way to communicate what you want. Instead of describing your desired output format abstractly, show the model what a good output looks like. Instead of explaining edge cases in text, provide examples of how they should be handled.
Two or three well-chosen examples can replace paragraphs of instructions. The model learns from patterns more effectively than from rules. An example that shows the correct response to a tricky input teaches the model to handle similar inputs without explicit rules for every case.
Define Boundaries
Tell the model what it shouldn't do. Without boundaries, the model will try to be helpful in ways you might not want. A code review skill might start suggesting refactoring ideas when you only wanted bug identification. A data analysis skill might make recommendations when you only wanted descriptive statistics.
"Don't" instructions are surprisingly effective at constraining behavior. "Don't suggest changes to the code architecture," "Don't include information that isn't directly supported by the data," and "Don't apologize or use filler phrases" all tighten the output to match your needs.
Test and Iterate
No system prompt works perfectly on the first try. Testing your skill with diverse inputs reveals where the prompt falls short. Maybe the model handles simple cases well but struggles with edge cases. Maybe the output format is correct for short inputs but breaks for long ones.
Each test failure is information about where the prompt needs improvement. Add handling for the edge case, tighten the output format specification, or provide an additional example that covers the failure mode. After several rounds of testing and refinement, the prompt converges on reliable behavior.
Keeping a version history of your prompts lets you track which changes improved results and which didn't. This prevents the common pitfall of iterating in circles, where changes that fix one issue reintroduce another.