{
  "markdown": "# plsfix\n\nTurn vague instructions into clear ones. An agent skill that diagnoses and rewrites spec documents, prompts, requirements docs, briefs, and any written instructions meant to drive action from humans or AI.\n\nGive it a document. It identifies what's unclear and why, rewrites it, and hands back both the improved version and a change report mapping every edit to the principle it implements.\n\nWorks as a skill in [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/skills), [OpenAI Codex](https://developers.openai.com/codex/plugins/build), [Google Antigravity](https://antigravity.google/docs/skills), and [Gemini CLI](https://github.com/google-gemini/gemini-cli/blob/main/docs/extension.md) — all four use the same `SKILL.md` format. Can also be used as raw principles for direct prompting with any LLM.\n\n> **NOTE:** Don't run plsfix on a document and accept its output without reading both the change report and the rewrite. The `[CONFIRM]` tags exist because the skill sometimes has to guess at your intent — and it will occasionally guess wrong.\n\n## Table of Contents\n\n- [Highlights](#highlights)\n- [Installation](#installation)\n- [Usage](#usage)\n- [What to Use It On](#what-to-use-it-on)\n- [Using the Principles Without the Skill](#using-the-principles-without-the-skill)\n- [When to Expect the Best Results](#when-to-expect-the-best-results)\n- [When NOT to Use plsfix](#when-not-to-use-plsfix)\n- [Scope: What plsfix Is (and Isn't)](#scope-what-plsfix-is-and-isnt)\n- [The 12 Principles](#the-12-principles)\n- [Compatibility](#compatibility)\n- [Contributing](#contributing)\n- [References](#references)\n- [License](#license)\n\n## Highlights\n\n- **12 research-backed principles** — synthesized from official prompt engineering guidance by Anthropic, Google, OpenAI, and Microsoft, plus 18 academic papers\n- **Three-phase workflow** — Structure first, then Content, then Delivery. Fixes the skeleton before polishing sentences.\n- **Change report with every rewrite** — every edit cites the principle it implements and why, so the author learns while reviewing\n- **Voice preservation** — rewrites sharpen clarity without stripping the author's tone or inventing new requirements\n- **Safe assumptions** — anything the skill infers is marked `[CONFIRM]` so the author can verify or override\n- **Cross-platform** — same `SKILL.md` file works in Claude Code, OpenAI Codex, Google Antigravity, and Gemini CLI\n\n## Installation\n\n### From the mackayi marketplace (recommended)\n\n```\n/plugin marketplace add keithmackay/mackayi\n/plugin install plsfix@mackayi\n```\n\n### Claude Code\n\n```bash\ncp -r /path/to/plsfix/ ~/.claude/skills/plsfix/\n```\n\nOr symlink:\n```bash\nln -s /path/to/plsfix/ ~/.claude/skills/plsfix\n```\n\nThen invoke with: `/plsfix`. See [Claude Code skills docs](https://code.claude.com/docs/en/skills) for details.\n\n### Codex\n\nPlace the plugin directory where Codex can find it, then add an entry to your marketplace:\n\n**`~/.agents/plugins/marketplace.json`** (create if absent):\n```json\n{\n  \"name\": \"personal\",\n  \"interface\": { \"displayName\": \"Personal Plugins\" },\n  \"plugins\": [\n    {\n      \"name\": \"plsfix\",\n      \"source\": { \"source\": \"local\", \"path\": \"/path/to/plsfix/\" },\n      \"policy\": { \"installation\": \"AVAILABLE\", \"authentication\": \"ON_INSTALL\" },\n      \"category\": \"Productivity\"\n    }\n  ]\n}\n```\n\nSee [Codex plugins docs](https://developers.openai.com/codex/plugins/build) for details.\n\n### Antigravity\n\n**Global install** (all workspaces):\n```bash\ncp -r /path/to/plsfix/ ~/.gemini/antigravity/skills/plsfix/\n```\n\n**Workspace install** (current project only):\n```bash\ncp -r /path/to/plsfix/ .agents/skills/plsfix/\n```\n\nThe root `SKILL.md` is Antigravity-compatible as-is (no platform-specific metadata to strip). Skills are auto-discovered via semantic triggering on the `description` field, or invoke explicitly by name. See [Antigravity skills docs](https://antigravity.google/docs/skills) for details.\n\n### Gemini CLI\n\nGemini CLI installs extensions directly from GitHub:\n\n```bash\ngemini extensions install https://github.com/keithmackay/plsfix\n```\n\nTo update:\n```bash\ngemini extensions update plsfix\n```\n\nThe skill is auto-discovered from `GEMINI.md` after installation. See [Gemini CLI extension docs](https://github.com/google-gemini/gemini-cli/blob/main/docs/extension.md) for details.\n\n### Any other LLM or agent\n\nIf your tool doesn't support the `SKILL.md` format natively, paste the contents of `SKILL.md` into your system prompt or prepend it to your message. The principles and workflow are plain markdown — any LLM can follow them.\n\n## Usage\n\nInvoke the skill, then paste or point it at the document you want improved.\n\n### Before\n\n```text\nBuild a dashboard. Don't use too many colors. Make sure it's good for executives.\nAvoid technical jargon. The data should be recent.\n```\n\n### After\n\n```text\nBuild a Grafana dashboard for the payments service showing three metrics:\np95 latency, error rate, and throughput over the trailing 30 days.\n\nAudience: VP-level executives who review operational health weekly.\nUse plain language a non-technical stakeholder would understand.\n\nFormat: single-page view, dark theme, with one chart per metric arranged\nin a 3-column grid.\n```\n\n### Change Report (excerpt)\n\n| # | Principle | Before | After | Rationale |\n|---|-----------|--------|-------|-----------|\n| 1 | P5: Be specific | \"Build a dashboard\" | \"Build a Grafana dashboard for the payments service showing p95 latency, error rate, and throughput\" | Original lacked tool, service, and metrics |\n| 2 | P6: Name your audience | \"good for executives\" | \"VP-level executives who review operational health weekly\" | Specifying the audience calibrates vocabulary and depth |\n| 3 | P9: Say what to do | \"Don't use too many colors\" / \"Avoid technical jargon\" | \"dark theme\" / \"Use plain language a non-technical stakeholder would understand\" | Negative instructions replaced with positive directives |\n| 4 | P7: Define output contract | (missing) | \"single-page view, one chart per metric, 3-column grid\" | No format specification existed; output shape was undefined |\n\n## What to Use It On\n\nplsfix works on any written instructions meant to drive action. The sweet spot is documents where vague or disorganized writing leads to misinterpretation — by humans or by AI.\n\n### System instruction files\n\nThese are the highest-leverage targets. A poorly written system instruction file silently degrades every interaction the agent has. plsfix is particularly effective on:\n\n- **CLAUDE.md / AGENTS.md** — Project-level instructions that shape how coding agents behave across your entire repo. Research shows that as instruction count increases, instruction-following quality decreases uniformly [[ref]](https://www.humanlayer.dev/blog/writing-a-good-claude-md). Every instruction that's vague, contradictory, or buried in the middle costs you compliance on the instructions around it.\n- **SKILL.md files** — Other skills you've written. Skills are ephemeral instructions loaded on-demand; they need to be especially clear because the agent has no prior context when it loads them.\n- **Custom agents and commands** — Agent definition files, slash command definitions, and any markdown that gets injected into an agent's context window.\n- **MEMORY.md and knowledge base files** — Persistent context that agents reference across sessions. Vague memories produce vague behavior.\n\n### Spec and requirements documents\n\n- Product requirements docs (PRDs)\n- Technical specs and architecture decision records\n- User stories and acceptance criteria\n- API contracts and interface definitions\n- Test plans\n\n### Prompts used directly with LLMs\n\n- System prompts for chatbots, assistants, and agent loops\n- Reusable prompt templates\n- Few-shot example sets (plsfix can evaluate whether examples are clear, diverse, and well-structured)\n\n### Operational documents\n\n- Runbooks and playbooks\n- Onboarding guides\n- Process documentation\n- Internal briefs and SOPs\n\n## Using the Principles Without the Skill\n\nYou don't need the skill infrastructure to benefit from the 12 principles. They work as a mental checklist or as raw instructions pasted into any LLM conversation.\n\n### As a one-shot prompt\n\nPaste the principles table from `SKILL.md` into a conversation along with the document you want improved:\n\n```text\nHere are 12 principles for effective instructions. Review the document\nbelow against each principle. For every violation, rewrite the relevant\nsection and explain which principle it fixes and why.\n\n[paste principles table]\n\n---\n\n[paste your document]\n```\n\n### As a mental checklist\n\nBefore sending any important prompt or spec document, scan it against the quick reference:\n\n1. Did I put context before the ask?\n2. Does each section have one goal?\n3. Are compound instructions broken into steps?\n4. Are different content types (instructions, context, examples) visually separated?\n5. Did I replace vague nouns with concrete details?\n6. Did I say who the audience is?\n7. Did I define what \"done\" looks like?\n8. Did I include an example?\n9. Did I frame instructions positively (what to do, not what to avoid)?\n10. Did I explain why this matters?\n11. Did I say what to do when uncertain?\n12. Do any of my instructions contradict each other?\n\n### In a custom GPT, assistant, or agent\n\nAdd the principles to your system prompt as standing instructions. The agent will apply them when asked to review or improve documents, or you can reference them when writing prompts yourself.\n\n## When to Expect the Best Results\n\nplsfix produces the most dramatic improvements when:\n\n- **The document is medium-length (200-2000 words).** Short enough for the agent to hold the full document in context, long enough to have structural problems worth fixing.\n- **The document has clear intent but poor execution.** The author knows what they want but hasn't articulated it well. plsfix clarifies; it doesn't invent.\n- **The document will be consumed by an LLM.** System prompts, skills, agent instructions, and prompt templates benefit the most because LLMs are more sensitive to the exact issues the 12 principles address (buried asks, contradictions, missing output contracts) than human readers are.\n- **The document is being used repeatedly.** A prompt template used 100 times gets 100x the value from a clarity improvement. A one-off message gets 1x.\n- **Multiple people are interpreting the same document.** Ambiguity costs compound with each additional reader. plsfix reduces the surface area for misinterpretation.\n\nResults are solid but less dramatic when the document is already well-written and mostly needs minor tightening — plsfix will correctly report that few principles were triggered.\n\n## When NOT to Use plsfix\n\nplsfix is designed for instruction documents — text that tells someone (or something) what to do. It is the wrong tool for:\n\n- **Creative writing.** Fiction, poetry, essays, marketing copy. These have different goals (voice, persuasion, narrative arc) that the 12 principles don't address and may actively harm. A novel shouldn't have an \"output contract.\"\n- **Conversational messages.** Slack messages, emails, chat replies. These are too short and too context-dependent. The overhead of a change report isn't worth it for a three-sentence message.\n- **Code.** plsfix works on natural language instructions, not source code. Use a linter.\n- **Documents where ambiguity is intentional.** Some strategic documents are deliberately vague to allow flexibility in interpretation. If the author left something open-ended on purpose, plsfix will flag it as a problem. That's a false positive.\n- **Documents you haven't read.** Don't run plsfix on a document and accept its output without reading both the change report and the rewrite. The `[CONFIRM]` tags exist because the skill sometimes has to guess at your intent — and it will occasionally guess wrong.\n- **Very long documents (5000+ words).** The skill works best when the full document fits comfortably in context. For very long documents, consider breaking them into sections and running plsfix on each section separately.\n\n## Scope: What plsfix Is (and Isn't)\n\nplsfix is a **general-purpose clarity tool**. It applies universal communication principles to any instruction document, regardless of the target platform or file format. It doesn't know or care about the specific conventions of any particular file type — it just makes the writing clearer.\n\nThat generality is by design, but it means plsfix doesn't replace specialized tools that understand the *content-level* requirements of specific file formats. There are excellent projects that tune what goes *into* these files:\n\n- **CLAUDE.md** — Tools like [claude-md-builder](https://github.com/anthropics/skills) and guides like [Writing a Good CLAUDE.md](https://www.humanlayer.dev/blog/writing-a-good-claude-md) help you decide *what instructions to include* (test commands, coding conventions, repo structure). plsfix then makes those instructions *clearer*.\n- **AGENTS.md** — Codex-specific generators help you structure agent instructions for OpenAI's conventions. plsfix helps ensure each instruction is unambiguous once written.\n- **SOUL.md** — [OpenClaw's SOUL.md system](https://github.com/aaronjmars/soul.md) defines agent persona, values, and communication style with its own structural conventions (Identity, Boundaries, Example Responses). plsfix can sharpen the *writing* within those sections, but it doesn't generate persona content.\n- **README.md** — Tools like [readme-ai](https://github.com/eli64s/readme-ai) generate entire READMEs from your codebase. plsfix is not a README generator — but if your README contains instructional sections (Contributing, Getting Started), plsfix can clarify those.\n\n**The relationship is complementary:** use the specialized tool to decide *what* to say, then use plsfix to say it *clearly*. Or use plsfix standalone when no specialized tool exists for your document type.\n\n## The 12 Principles\n\nOrdered by application phase: structure the document first, then sharpen content, then refine delivery. Each principle is grounded in at least two independent sources from the official prompt engineering guidelines of Anthropic, Google, OpenAI, and Microsoft, and backed by academic research.\n\n### Phase 1: Structure\n\nGet the bones right before worrying about individual sentences.\n\n**P1: Context first, ask last.** Lead with background and constraints, close with the actual request. Never bury the ask in the middle. LLMs process tokens left to right — an ask that appears before the context was processed without visibility into it. Research confirms models perform measurably better when context precedes the question [[26]](https://arxiv.org/abs/2511.09700), and that information buried in the middle of long prompts suffers significant degradation [[24]](https://arxiv.org/abs/2307.03172). All four providers recommend this structure: Anthropic says \"put longform data at the top, above your query\" [[1]](https://platform.claude.com/docs/en/docs/build-with-claude/prompt-engineering/claude-4-best-practices); Google says \"place specific questions at the end, after your data context\" [[3]](https://ai.google.dev/gemini-api/docs/prompting-strategies); Microsoft recommends starting with instructions, then content [[8]](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/concepts/prompt-engineering); OpenAI notes \"recency bias\" means information at the end has more influence [[8]](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/concepts/prompt-engineering).\n\n*Symptom it fixes:* Key requirements get missed; output addresses secondary concerns instead of the main ask.\n\n**P2: One ask per section.** Split multi-goal paragraphs so each section has exactly one objective. The copywriter's \"Rule of One\" (one idea, one audience, one call to action) has a direct analog in LLM research: multi-task prompts degrade performance compared to single-task prompts, particularly in smaller models [[23]](https://www.mdpi.com/2079-9292/14/21/4349). Ask for three things at once and the model weights them unevenly, just like a reader who skims a multi-CTA email and does none of them.\n\n*Symptom it fixes:* Output oscillates between competing goals or silently drops some.\n\n**P3: Break it into steps.** Decompose compound instructions into sequential, numbered steps. Copywriters call it the \"slippery slope\" — each sentence leads to the next, keeping cognitive load manageable. Researchers call it chain-of-thought prompting. Adding \"let's think step by step\" to math problems improved accuracy from 18% to 79% [[20]](https://arxiv.org/abs/2205.11916). Google recommends \"prompt decomposition\" — breaking complex tasks into simpler single-instruction prompts [[3]](https://ai.google.dev/gemini-api/docs/prompting-strategies). Microsoft calls it \"break the task down\" [[8]](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/concepts/prompt-engineering). OpenAI's GPT-5 guide recommends decomposing user queries into sub-requests [[7]](https://developers.openai.com/cookbook/examples/gpt-5/gpt-5_prompting_guide).\n\n*Symptom it fixes:* Output jumbles or skips parts of the task.\n\n**P4: Use structural markup.** Separate instructions, context, examples, and inputs with consistent delimiters — XML tags, markdown headers, or `---` separators. All four providers recommend this explicitly. Anthropic says \"XML tags help Claude parse complex prompts unambiguously\" [[1]](https://platform.claude.com/docs/en/docs/build-with-claude/prompt-engineering/claude-4-best-practices). Google says \"use consistent XML or Markdown delimiters throughout\" [[3]](https://ai.google.dev/gemini-api/docs/prompting-strategies). Microsoft recommends \"clear syntax\" with separators and uppercase section headings [[8]](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/concepts/prompt-engineering). OpenAI says \"if you're not sure what syntax to use, consider using Markdown or XML\" [[5]](https://platform.openai.com/docs/guides/prompt-engineering).\n\n*Symptom it fixes:* Reader/AI confuses instructions with examples, or context with the ask.\n\n### Phase 2: Content\n\nSharpen what you're saying.\n\n**P5: Be specific, not abstract.** Replace vague nouns with concrete details: audience, format, scope, quantities. \"Save $47 on your first order\" beats \"save money\" in copywriting. The same holds for LLMs: a study testing 26 prompting principles found an average 57.7% quality improvement on GPT-4 when applying specificity and other principles [[18]](https://arxiv.org/abs/2312.16171). Anthropic's golden rule: \"Show your prompt to a colleague with minimal context on the task and ask them to follow it. If they'd be confused, Claude will be too\" [[1]](https://platform.claude.com/docs/en/docs/build-with-claude/prompt-engineering/claude-4-best-practices). Microsoft says \"be specific — leave as little to interpretation as possible\" [[8]](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/concepts/prompt-engineering). OpenAI warns \"models can guess what you mean, but guesses aren't reliable, especially in production\" [[5]](https://platform.openai.com/docs/guides/prompt-engineering).\n\n*Symptom it fixes:* Output is generic or surface-level.\n\n**P6: Name your audience.** State who will read or act on the output and what they already know. \"Written for CFOs at Series B startups\" produces entirely different output than \"written for general audiences.\" The model shifts toward token distributions that co-occurred with that audience type in training data — different mechanism than human audience adaptation, same result. Google's prompt structure explicitly includes a \"Role\" component [[3]](https://ai.google.dev/gemini-api/docs/prompting-strategies). Anthropic recommends \"give Claude a role\" to focus behavior and tone [[1]](https://platform.claude.com/docs/en/docs/build-with-claude/prompt-engineering/claude-4-best-practices).\n\n*Symptom it fixes:* Tone, depth, or vocabulary is wrong for the reader.\n\n**P7: Define the output contract.** Specify what \"done\" looks like: format, length, structure, required fields. Microsoft identifies this as the #1 prompt failure: \"most failures stem from undefined 'done'\" [[9]](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/advanced-prompt-engineering). Their system message design checklist starts with \"specify the output format.\" OpenAI recommends specifying output structure because \"it can have a significant effect on the nature and quality of the results\" [[8]](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/concepts/prompt-engineering). Google says \"define response format expectations (tables, lists, JSON, etc.)\" [[3]](https://ai.google.dev/gemini-api/docs/prompting-strategies). Anthropic recommends telling Claude the desired output format and constraints explicitly [[1]](https://platform.claude.com/docs/en/docs/build-with-claude/prompt-engineering/claude-4-best-practices).\n\n*Symptom it fixes:* Output is correct in substance but wrong in shape, length, or structure.\n\n**P8: Show, don't tell.** Add 1-3 examples of desired output. Copywriters use case studies because concrete examples beat abstract claims. Few-shot prompting is the single most studied technique in all of prompt engineering, dating to GPT-3's foundational paper [[19]](https://arxiv.org/abs/2005.14165). Quality of examples matters more than quantity — one well-chosen example beats ten mediocre ones. Anthropic recommends 3-5 examples wrapped in `<example>` tags [[1]](https://platform.claude.com/docs/en/docs/build-with-claude/prompt-engineering/claude-4-best-practices). Google's whitepaper says \"prompts without few-shot examples are likely to be less effective\" and explicitly discourages zero-shot [[3]](https://ai.google.dev/gemini-api/docs/prompting-strategies). Microsoft and OpenAI both recommend few-shot learning with input/output pairs [[5]](https://platform.openai.com/docs/guides/prompt-engineering) [[8]](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/concepts/prompt-engineering).\n\n*Symptom it fixes:* Reader/AI guesses wrong about what \"good\" looks like.\n\n### Phase 3: Delivery\n\nRefine how you're saying it.\n\n**P9: Say what to do, not what to avoid.** Rewrite \"don't\" and \"avoid\" instructions as positive directives. Copywriters learned long ago that \"don't think about a pink elephant\" makes you think about a pink elephant. LLMs have the same problem: negative instructions activate the very concept you're trying to suppress. Anthropic has formalized this into their official documentation, recommending \"tell Claude what to do instead of what not to do\" [[1]](https://platform.claude.com/docs/en/docs/build-with-claude/prompt-engineering/claude-4-best-practices). Instead of \"do not use markdown,\" try \"your response should be composed of smoothly flowing prose paragraphs.\"\n\n*Symptom it fixes:* Forbidden behavior still appears; instructions feel restrictive rather than enabling.\n\n**P10: Make the stakes real.** State why this matters: who benefits, what breaks if done wrong, what success enables. Every copywriter knows emotion drives action more than logic. A Microsoft and Chinese Academy of Sciences team tested this directly on LLMs: positive emotional framing (\"this is very important to my career\") improved performance by up to 115% on BIG-Bench reasoning benchmarks [[21]](https://arxiv.org/abs/2307.11760). Negative emotional framing (\"this seems beyond your skill level\") boosted performance by 46% [[22]](https://arxiv.org/abs/2405.02814). The models don't feel urgency, but emotionally-framed requests in their training data were paired with higher-effort human responses. Anthropic recommends \"providing context or motivation behind your instructions\" because \"Claude is smart enough to generalize from the explanation\" [[1]](https://platform.claude.com/docs/en/docs/build-with-claude/prompt-engineering/claude-4-best-practices).\n\n*Symptom it fixes:* Instructions followed mechanically without judgment or care.\n\n**P11: Give an out for uncertainty.** Explicitly state what to do when information is missing, the request is ambiguous, or the task is out of scope. Without this, models fabricate answers or fail silently. Anthropic recommends giving \"explicit permission to express uncertainty rather than guessing\" to reduce hallucinations [[2]](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview). Microsoft's system message design checklist includes \"add a 'when unsure' policy\" — define behavior when the request is ambiguous, out of scope, or the model lacks information [[9]](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/advanced-prompt-engineering). Microsoft also recommends giving the model an \"out\" (e.g., \"respond with 'not found' if the answer isn't present\") [[8]](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/concepts/prompt-engineering).\n\n*Symptom it fixes:* Fabricated answers, confident guesses, or silent failures when the task can't be completed as written.\n\n**P12: Resolve contradictions.** Ensure no two instructions conflict; when tensions exist, state which takes priority. OpenAI's GPT-5 guide warns that \"GPT-5 expends reasoning tokens resolving contradictions rather than ignoring them\" and recommends reviewing prompts for conflicting directives before deployment [[7]](https://developers.openai.com/cookbook/examples/gpt-5/gpt-5_prompting_guide). Microsoft lists \"conflicting instructions\" as a top pitfall (e.g., \"be brief\" and \"be comprehensive\" without prioritization) and warns that \"a system message influences the model, but it doesn't guarantee compliance\" — contradictions make non-compliance more likely [[9]](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/advanced-prompt-engineering).\n\n*Symptom it fixes:* Reader/AI wastes effort resolving ambiguity, or silently picks the wrong side of a conflict.\n\n---\n\nSee [SKILL.md](SKILL.md) for the full workflow, rewriting rules, diagnosis patterns, and change report format.\n\n## Compatibility\n\n| Feature | Claude Code | Codex | Antigravity | Gemini CLI |\n|---------|:-----------:|:-----:|:-----------:|:----------:|\n| Core skill | ✅ | ✅ | ✅ | ✅ |\n| Sub-documents (`operations/`) | ✅ | ✅ | ✅ | ✅ |\n\nLegend: ✅ Supported · ❌ Not supported\n\n## Contributing\n\nContributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide, including how to report bugs, propose new principles, and set up local development.\n\nThe short version: proposed principle changes must be backed by at least two independent sources (two different LLM provider docs, or one provider doc + one peer-reviewed paper). Fork the repo, make your changes, and open a pull request with a description of what changed and why.\n\n---\n\n## References\n\n### Platform Documentation\n\n- **Claude Code Skills:** https://code.claude.com/docs/en/skills\n- **Codex Plugins:** https://developers.openai.com/codex/plugins/build\n- **Antigravity Skills:** https://antigravity.google/docs/skills\n- **Gemini CLI Extensions:** https://github.com/google-gemini/gemini-cli/blob/main/docs/extension.md\n- **Agent Skills open standard:** https://agentskills.io/home\n\n### Industry Prompt Engineering Guidelines\n\nThe 12 principles are synthesized from official prompt engineering documentation published by the four major LLM providers:\n\n1. [Anthropic: Prompting Best Practices (Claude 4.x)](https://platform.claude.com/docs/en/docs/build-with-claude/prompt-engineering/claude-4-best-practices)\n2. [Anthropic: Prompt Engineering Overview](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview)\n3. [Google: Prompt Design Strategies (Gemini API)](https://ai.google.dev/gemini-api/docs/prompting-strategies)\n4. [Google Cloud: What is Prompt Engineering](https://cloud.google.com/discover/what-is-prompt-engineering)\n5. [OpenAI: Prompt Engineering Guide](https://platform.openai.com/docs/guides/prompt-engineering)\n6. [OpenAI: Best Practices for Prompt Engineering](https://help.openai.com/en/articles/6654000-best-practices-for-prompt-engineering-with-the-openai-api)\n7. [OpenAI: GPT-5 Prompting Guide](https://developers.openai.com/cookbook/examples/gpt-5/gpt-5_prompting_guide)\n8. [Microsoft: Prompt Engineering Techniques (Azure OpenAI)](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/concepts/prompt-engineering)\n9. [Microsoft: System Message Design for Azure OpenAI](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/advanced-prompt-engineering)\n\n### Research Papers\n\nThese papers provide the empirical evidence that the same communication principles effective with humans are also effective with LLMs:\n\n10. [Grammarly and Harris Poll: The State of Business Communication (2022)](https://www.businesswire.com/news/home/20220125005525/en/Grammarly-and-Harris-Poll-Research-Estimates-U.S.-Businesses-Lose-%241.2-Trillion-Annually-to-Poor-Communication) — Poor communication costs US businesses $1.2 trillion per year.\n11. [NACE Job Outlook Surveys: Employer-Desired Competencies](https://www.naceweb.org/talent-acquisition/candidate-selection/employers-rate-career-competencies-new-hires-proficiency/) — 73-82% of employers rank written communication as a must-have competency.\n12. [Grammarly: Good Grammar, Good Career (LinkedIn Profile Analysis)](https://www.grammarly.com/blog/writing-tips/good-grammar-good-career/) — Professionals with fewer language errors tend to reach higher positions.\n13. [Do LLMs Write Like Humans? Variation in Grammatical and Rhetorical Styles, PNAS (2025)](https://www.pnas.org/doi/10.1073/pnas.2422455122) — Instruction-tuned models default to noun-heavy, informationally dense style and struggle to deviate.\n14. [MIT Sloan: Generative AI Results Depend on User Prompts as Much as Models](https://mitsloan.mit.edu/ideas-made-to-matter/study-generative-ai-results-depend-user-prompts-much-models) — Half the performance gains from a better model came from how users adapted their prompts, not the model itself.\n15. [Grammarly 2025: The Critical Role of AI Literacy Across the Enterprise](https://www.grammarly.com/business/learn/role-of-generative-ai-literacy/) — AI-literate workers save 8.9 hours/week vs 6.3 hours for merely familiar workers (41% gap).\n16. [Using Prompt Engineering to Better Communicate with People, Harvard Business Review](https://hbr.org/2024/01/using-prompt-engineering-to-better-communicate-with-people) — Skills flow both directions: better AI communication improves human communication and vice versa.\n17. [Nielsen Norman Group: Good from Afar, But Far from Good: AI Prototyping in Real Design Contexts](https://www.nngroup.com/articles/ai-prototyping/) — Vague prompts produce generic, randomly assembled designs; detailed prompts produce professional, usable work.\n18. [Principled Instructions Are All You Need for Questioning LLaMA-1/2, GPT-3.5/4](https://arxiv.org/abs/2312.16171) — 26 prompting principles tested, yielding 57.7% average quality improvement on GPT-4.\n19. [Language Models are Few-Shot Learners (GPT-3, Brown et al., 2020)](https://arxiv.org/abs/2005.14165) — The foundational paper establishing that providing examples in-context dramatically improves LLM output.\n20. [Large Language Models are Zero-Shot Reasoners (Kojima et al., 2022)](https://arxiv.org/abs/2205.11916) — Adding \"let's think step by step\" improved math accuracy from 18% to 79%.\n21. [Large Language Models Understand and Can be Enhanced by Emotional Stimuli (EmotionPrompt)](https://arxiv.org/abs/2307.11760) — Positive emotional framing improved performance by up to 115% on BIG-Bench reasoning benchmarks.\n22. [NegativePrompt: Leveraging Psychology for LLM Enhancement via Negative Emotional Stimuli](https://arxiv.org/abs/2405.02814) — Negative emotional framing boosted BIG-Bench performance by 46% and outperformed positive framing on instruction-following tasks.\n23. [Degradation of Multi-Task Prompting Across Six NLP Tasks and LLM Families](https://www.mdpi.com/2079-9292/14/21/4349) — Multi-task prompts degrade LLM performance compared to single-task prompts, particularly in smaller models.\n24. [Lost in the Middle: How Language Models Use Long Contexts (Liu et al., 2023)](https://arxiv.org/abs/2307.03172) — Models perform best when key information appears at beginning or end, with significant degradation for content buried in the middle.\n25. [Google Research: Repeat Prompting Improves Non-Reasoning LLMs (2025)](https://arxiv.org/abs/2412.15233) — Simply repeating a prompt twice improved accuracy by up to 76% on non-reasoning tasks.\n26. [Order Matters: Rethinking Prompt Construction in In-Context Learning](https://arxiv.org/abs/2511.09700) — Prompt component order matters enormously; context before question outperforms question before context.\n27. [World Economic Forum Future of Jobs Report 2025](https://www.weforum.org/publications/the-future-of-jobs-report-2025/) — Analytical thinking, creative thinking, and leadership are increasing in importance as meta-skills.\n\n### Related Reading\n\n- [The Most Important AI Skill Isn't Technical. It's the One You Learned in English Class.](https://tlcmentor.substack.com/p/communication-skills-are-ai-skills) — The article that motivated this skill, exploring why clear writing is the highest-leverage AI skill.\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for release history.\n\n## License\n\n[MIT](LICENSE) © 2025 Keith MacKay\n",
  "bytes": 33440,
  "sha": "6bc5fbe066b1b03f3ee3566dbaef52d121c3364c7a6a31d1e73289ebcb238b7e",
  "repo_slug": "keithmackay/plsfix",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_keithmackay_plsfix_55f47912/readme"
}