Immutable. This exact content is served forever at /api/v1/blob/cbbb129e3e11d301.
---
name: ai_instruction_writing
description: Write AI-consumed content using positive, action-oriented language as the primary carrier of every instruction. Use when creating or editing any artifact an AI reads at inference time — SKILL.md files, .mdc rule files, CLAUDE.md/AGENTS.md/GEMINI.md configuration, prompt templates, system prompts, commands, agent and sub-agent definitions, instruction sets, and persona definitions.
version: 3.0.0
author: Andreas F. Hoffmann
license: MIT
---
# ai_instruction_writing
<ai_instruction_writing>
<objective>
Write AI-consumed content so every instruction's primary carrier is a positive, action-oriented statement that tells the LLM what to do, what something is, or how it should be. Allow negative or contrastive supplements only as a catch-all for what positive guidance cannot enumerate.
</objective>
<core_rule>
Every instruction's primary carrier is a positive statement that tells the LLM what to do, what something is, or how it should be. A negative or contrastive supplement ("don't X", "avoid Y", "X instead of Y", double negatives, implicit negation by comparison) earns its place only when listing every positive case is infeasible — the negative then names a broader class as a catch-all for what falls outside the positive guidance. When the positive set is fully enumerable, the negative restates the inverse and adds nothing; cut it.
</core_rule>
<self_check>
<procedure>Delete the negative or contrastive portion of a rule, then apply the matching outcome below.</procedure>
<when_positive_is_empty_or_vague>The rule is inverted. Rewrite the positive carrier first.</when_positive_is_empty_or_vague>
<when_positive_is_complete>The negative just restates the inverse. Drop the negative — it is redundant.</when_positive_is_complete>
<when_negative_names_a_broader_class>Keep the negative. It covers a long tail that no single positive could enumerate.</when_negative_names_a_broader_class>
</self_check>
<applicability>
This rule governs the model's *output*. In meta or teaching context — including this skill — contrastive pairs, ❌/✅ examples, and "X replaces Y" patterns are legitimate when they illustrate how to transform inputs.
</applicability>
<authoring_guidelines>
<start_with_action_verbs>Use, Write, Create, Define, Implement, Apply.</start_with_action_verbs>
<be_specific>Tell exactly what to do with concrete details.</be_specific>
<use_imperative_mood>Write commands that tell the LLM what to do.</use_imperative_mood>
<lead_with_the_positive_carrier>Put the actionable instruction first; layer supplements after.</lead_with_the_positive_carrier>
<preserve_technical_precision>Keep specific details, error codes, and identifiers when transforming.</preserve_technical_precision>
<enhance_rather_than_replace>Add specificity, rationale, and context on top of existing positive rules.</enhance_rather_than_replace>
</authoring_guidelines>
<positive_only_examples>
<when_to_apply>These enumerate their full positive set, so no catch-all negative is needed — see catch_all_negative for the cases where the long tail forces one.</when_to_apply>
<examples>
<example>Use specific exception types like `except ValueError:`.</example>
<example>Use absolute imports like `from package.module import function`.</example>
<example>Define named functions for reusable logic.</example>
<example>Write one statement per line for readability.</example>
<example>Implement error handling with specific exception types.</example>
<example>Apply consistent formatting throughout the codebase.</example>
<example>Write clear, descriptive error messages that guide users.</example>
<example>Provide specific examples for each concept.</example>
</examples>
</positive_only_examples>
<catch_all_negative>
<principle>
A negative supplement earns its place when listing the positive cases exhaustively is infeasible. The negative names a broader class as a catch-all for what falls outside the positive guidance. When the positive set is finite and enumerable, no negative is needed.
</principle>
<valid_catch_all>
<pattern>Positive carrier plus catch-all for the long tail.</pattern>
<examples>
<example>"Use ASCII characters in identifiers; don't include Unicode symbols, emoji, or non-printing characters." The positive is one finite class; Unicode is too broad to enumerate, so the negative names the excluded class.</example>
<example>"Open every section with an action verb (Use, Write, Create, Define, Implement, Apply); don't lead with passive voice or noun phrases." The positives are partial; the negative catches the long tail of non-action openings.</example>
</examples>
</valid_catch_all>
<invalid_negative_only>
<pattern>Negative-only, no positive carrier.</pattern>
<examples>
<example>"Don't use relative imports." Rewrite: "Use absolute imports like `from package.module import function`."</example>
<example>"Avoid unused imports." Rewrite: "Import only modules you actively use; remove unused imports immediately to prevent F401 errors."</example>
</examples>
</invalid_negative_only>
<invalid_redundant_negative>
<pattern>Negative just inverts an enumerable positive (noise).</pattern>
<examples>
<example>"Use 4-space indentation; don't use tabs or 2-space indents." Drop the negative: "Use 4-space indentation."</example>
</examples>
</invalid_redundant_negative>
</catch_all_negative>
<transformation_patterns>
<when_to_use>Apply these patterns when rewriting existing negative rules into positive ones. The pairs show the transform; the model's output is the positive half, optionally with supplemental context.</when_to_use>
<action_focused>"Use X" replaces "Don't use Y".</action_focused>
<outcome_focused>"Ensure X" replaces "Avoid Y".</outcome_focused>
<solution_focused>"Implement X" replaces "Prevent Y".</solution_focused>
<guidance_focused>"Follow X" replaces "Never Y".</guidance_focused>
<success_focused>"Apply X" replaces "Stop Y".</success_focused>
</transformation_patterns>
<good_vs_poor_transformations>
<principle>Both rows take a negative input and produce a positive output. The good versions preserve the technical precision the poor ones discard.</principle>
<poor>
<issue>Deletes important information.</issue>
<examples>
<example>"Never import unused modules" → "Import only what you use".</example>
<example>"Don't assign unused variables" → "Use variables only when needed".</example>
</examples>
</poor>
<good>
<strength>Preserves and enhances information.</strength>
<examples>
<example>"Never import unused modules" → "Import only modules you actively use; remove unused imports immediately to prevent F401 errors".</example>
<example>"Don't assign unused variables" → "Assign variables only when you need them; use `_` for intentionally unused values to prevent F841 errors".</example>
</examples>
</good>
</good_vs_poor_transformations>
<enhancement_strategies>
<when_to_apply>Apply these when improving existing positive rules — layer value on top rather than rewriting.</when_to_apply>
<add_specificity>Include error codes, specific examples, concrete details.</add_specificity>
<expand_context>Add rationale, benefits, and when to apply.</expand_context>
<enhance_examples>Provide more detailed, actionable examples.</enhance_examples>
<improve_clarity>Make the action more specific without losing content.</improve_clarity>
</enhancement_strategies>
<content_layout>
<lead_with_positive>Always start sections with what to do.</lead_with_positive>
<allocate_most_space_to_positive_guidance>The positive form is the carrier; supplements stay short.</allocate_most_space_to_positive_guidance>
<end_with_positive>Conclude with positive reinforcement when wrapping a section.</end_with_positive>
</content_layout>
</ai_instruction_writing>