A research-backed toolkit covering the Description competency of the AI Fluency 4D Framework — with calibrated evaluation tools, real-world examples, and production-ready prompt templates.
This toolkit is a practitioner's implementation built on top of the AI Fluency Framework by Rick Dakan, Joseph Feller, and Anthropic (2025), released under CC BY-NC-SA 4.0. The framework defines four competencies for effective, efficient, ethical, and safe collaboration with AI systems — the 4Ds:
- Delegation — deciding when and how to involve AI
- Description — communicating your intent to AI effectively
- Discernment — evaluating AI outputs with critical judgment
- Diligence — taking responsibility for AI-assisted work
This toolkit covers Description in depth — the competency concerned with writing prompts that produce the results you need. The PPEP framework, prompt evaluator, and calibration sets all operate within this competency. The issue evaluator is a Discernment tool — it supports human judgment over AI-destined documents before execution begins.
The three remaining competencies (Delegation, full Discernment coverage, and Diligence) are not covered by this toolkit. The full AI Fluency course is available through Anthropic and covers all four competencies with structured exercises and project-based learning.
Dakan, R., Feller, J., & Anthropic. (2025). AI Fluency: Framework and Foundations. Released under CC BY-NC-SA 4.0. Supported in part by the Higher Education Authority, Ireland, through the National Forum for the Enhancement of Teaching and Learning.
Most prompt engineering guides are opinion-based. They tell you what to do without explaining why, without evidence, and without a way to measure whether your prompts are actually improving.
This toolkit was built differently.
Every decision in this framework was:
- Grounded in established research — Nielsen's 10 Usability Heuristics, WCAG 2.2 AA, NN/G studies, peer-reviewed usability literature
- Validated through iteration — prompts were evaluated, scored, revised, and rescored against a consistent rubric until the framework stabilized
- Calibrated against real examples — a set of nine anchor prompts spanning the full quality range (1/10 to 10/10) was developed to reduce scoring subjectivity
- Honest about limitations — confidence intervals, epistemic uncertainty, and the 7% irreducible subjectivity inherent in single-evaluator heuristic assessment are documented throughout
The result is a framework you can trust, teach, and build on.
See the toolkit in action at https://prompt-engineering-toolkit-companio.vercel.app. The companion app ships three of the evaluators as a hosted web app, powered by Claude. No API key required.
Source: Doberjohn/prompt-engineering-toolkit-companion.
A four-dimension model for evaluating and writing AI prompts, extended with seven evidence-based prompting techniques and mapped to established research.
Scope note: The PPEP framework covers the Description competency of the AI Fluency 4D Framework (Dakan, Feller, and Anthropic, 2025). The three peer competencies — Delegation, Discernment, and Diligence — are not covered by this toolkit. Description is the competency concerned with communicating effectively with AI systems. The other three competencies address deciding when to involve AI (Delegation), evaluating AI outputs (Discernment), and responsible use (Diligence).
Core dimensions:
- Product — what you want: output, format, audience, scope, constraints
- Process — how the AI should approach the task: steps, order, methodology
- Performance — how the AI should behave: tone, role, collaboration style, depth
- Epistemics — how the AI should know things: inventory before judging, proof for negative claims, reasoning before concluding
The Epistemics dimension is the most advanced and the most impactful. It was independently surfaced during iterative development and is not found in most prompting guides. It is the single biggest differentiator between a 7/10 and a 10/10 prompt.
A session intro prompt for activating strict, calibrated prompt evaluation. Scores prompts across the four PPEP dimensions using nine scored reference anchors. Works best with Claude, compatible with any instruction-following AI model.
Three production-ready evaluation prompts for auditing user interfaces — one for each evaluation source: URL, Screenshot, and Codebase. Built on Nielsen's heuristics, WCAG 2.2 AA, and a 20-dimension scoring system covering both UI (objective) and UX (heuristic inference).
A Discernment tool — a session intro prompt for exercising human judgment over GitHub implementation plan issues before delegating execution to AI. Evaluates whether an issue is safe to hand to an AI coding agent by scoring it across eight sections using a weighted formula derived from Nielsen's severity scale. Produces severity findings and generates targeted improvement suggestions (score >= 7.0), a full revised issue (2.0 <= score < 7.0), or a structured template (score < 2.0) when context is insufficient for a meaningful rewrite. Built on research from GitHub official documentation, Agile acceptance criteria standards, and SRE runbook quality frameworks.
Nine real prompts evaluated and scored during framework development, spanning scores from 1/10 to 10/10 with two distinct 10/10 anchors (technical agentic and non-technical collaborative). Included as a learning resource.
Ten controlled degradations of a real implementation plan issue (GitHub issue #278, formula score 9.44/10), each with a traceable degradation rationale and formula-verified score. Built using the same controlled degradation methodology recommended by NLP evaluation research to avoid central tendency bias. Includes a full methodology section with 25+ citations across GitHub issue quality research, Agile documentation standards, SRE runbook frameworks, and LLM evaluation methods.
Two project-agnostic Claude Code skills that close the write → evaluate → implement loop end to end. Both skills are Claude Code only and cannot run in chat interfaces.
draft-issue (skills/draft-issue/SKILL.md) — invoke at the end of any Claude Code session where scope has been agreed. Reads context from the conversation, asks up to three clarifying questions when needed, drafts a full eight-section issue, scores it against the weighted rubric, iterates until approved, then publishes via gh issue create.
implement-issue (skills/implement-issue/SKILL.md) — invoke when starting work on an issue. Runs session hygiene, fetches the issue, evaluates it against the eight-section rubric with a 7.0 quality gate, rewrites and updates the GitHub issue if it scores below the threshold, reads CLAUDE.md for project conventions, creates the branch, and presents a full implementation brief.
This toolkit was built with explicit confidence tracking. Current confidence level in the framework: 93%.
The remaining 7% is the irreducible subjectivity inherent in single-evaluator heuristic assessment, documented in peer-reviewed literature (Nielsen 1993, Hertzum 2006). This is not a failure of the framework — it is an honest acknowledgment of the limits of any expert-led evaluation method without multi-evaluator aggregation.
All research sources are cited inline in the relevant documents.
| Component | Claude | ChatGPT | Gemini | Claude Code |
|---|---|---|---|---|
| Framework (PPEP) | Full | Full | Full | Full |
| Prompt Evaluator | Full | Partial* | Partial* | Full |
| Issue Evaluator | Full | Partial* | Partial* | Full |
| UI/UX URL Mode | Full | Full | Full | Full |
| UI/UX Screenshot Mode | Full | Full | Full | Full |
| UI/UX Codebase Mode | Full | Partial** | Partial** | Full |
draft-issue skill |
N/A | N/A | N/A | Full*** |
implement-issue skill |
N/A | N/A | N/A | Full*** |
*The calibration anchors were developed and validated using Claude. Scoring consistency may vary on other models.
**Codebase mode uses grep commands and file:line references that require an agentic coding environment (Claude Code, Cursor, GitHub Copilot Workspace). Standard chat interfaces cannot execute these commands.
***Skills are Claude Code only. They cannot run in any chat interface because they depend on local tool access (git, gh, file system) and conversation context.
To evaluate a GitHub implementation plan issue:
- Open
prompts/issue-evaluator.md - Copy the full contents
- Paste into a new AI session
- The AI will confirm it understands the framework, then you paste your issue content
To understand how the scoring is anchored, read examples/issue-calibration-set.md — it contains the ten reference issues used to calibrate the evaluator.
To evaluate a prompt you have written:
- Open
prompts/prompt-evaluator.md - Copy the full contents
- Paste into a new AI session
- The AI will confirm it understands the framework, then you paste your prompt
To evaluate a UI/UX interface:
- Open
prompts/uiux-evaluation-prompts.md - Choose the mode that matches your available input (URL, Screenshot, or Codebase)
- Copy that mode's prompt
- Paste into a new AI session alongside your URL, screenshots, or codebase access
To draft an implementation plan issue from a Claude Code conversation:
- In your Claude Code terminal, agree on the scope of the upcoming work
- Invoke
/draft-issue(optionally with a brief title hint) - The skill reads the conversation, asks clarifying questions if needed, and produces a scored draft
- Review, request changes, approve
- The skill publishes the issue via
gh issue create
Install: copy skills/draft-issue/SKILL.md to .claude/commands/draft-issue/SKILL.md in your repo, or to ~/.claude/commands/draft-issue/SKILL.md for global access.
To start implementing an issue with the quality gate:
- In your Claude Code terminal, invoke
/implement-issue <number> - The skill evaluates the issue against the eight-section rubric
- If the score is >= 7.0 it proceeds to branch setup with an implementation brief
- If the score is < 7.0 it produces a rewrite, asks for approval, updates the GitHub issue, then branches
Install: copy skills/implement-issue/SKILL.md to .claude/commands/implement-issue/SKILL.md in your repo, or to ~/.claude/commands/implement-issue/SKILL.md for global access.
To learn the framework before using the tools:
- Start with
framework/ppep-framework.md - Read through the seven integrated techniques
- Study
examples/prompt-calibration-set.mdto calibrate your intuition
This toolkit draws on the following established research and standards:
- Nielsen, J. (1994). 10 Usability Heuristics for User Interface Design. Nielsen Norman Group.
- Nielsen, J. (1994). Severity Ratings for Usability Problems. Nielsen Norman Group.
- W3C. (2023). Web Content Accessibility Guidelines (WCAG) 2.2.
- Hertzum, M. (2006). Problem prioritization in usability evaluation: From severity assessments toward impact on design. International Journal of Human-Computer Interaction, 21(2), 125–146.
- MeasuringU. (2013). Rating the Severity of Usability Problems.
- CorsoUX. (2026). UX Audit Checklist: 50 Points.
- Dakan, R., Feller, J., & Anthropic. (2025). AI Fluency: Framework and Foundations. CC BY-NC-SA 4.0.
- Li, X., et al. (2024). An Empirical Analysis of Issue Templates Usage in Large-Scale Projects on GitHub. ACM Transactions on Software Engineering and Methodology.
- Sayagh, M., et al. (2025). What Makes a GitHub Issue Ready for Copilot? arXiv preprint.
- GitHub. (2025). Best Practices for Using GitHub Copilot to Work on Tasks. GitHub Docs.
- Eisenstein, J., et al. (2024). LLM-Rubric: A Multidimensional, Calibrated Approach to Automated Evaluation of Natural Language Texts. Proceedings of ACL 2024.
- ReliablePenguin. (2025). What Is a Runbook? History, Template, and Best Practices.
- Atlassian. (2025). What is Acceptance Criteria?
See CONTRIBUTING.md for guidelines. Contributions that include evidence, citations, or calibrated examples are strongly preferred over opinion-based additions.
MIT. See LICENSE.