On this page
There's something I've noticed after spending countless hours working with AI models and coding agents.
We expect increasingly sophisticated intelligence from AI, yet we often communicate with it using astonishingly unsophisticated instructions.
We write a sentence.
Press Enter.
Get something mediocre.
And immediately conclude that the model isn't good enough.
Then we rewrite the prompt.
Add a few instructions.
Tell it to "think harder."
Maybe throw in "act as an expert" for good measure.
And eventually, after multiple attempts, we get something reasonably close to what we wanted.
But here's the question that started bothering me:
Was the model actually failing, or did we never properly define what success looked like?
That question led me to build the ART Prompt Framework.
A simple, open-source framework and agent skill designed to turn vague requests into structured, context-rich, reusable AI prompts.
No magical phrases.
No unnecessarily complicated prompt-engineering rituals.
Just three components that force us to become more deliberate about what we're asking AI to do.
Act As. Request. Terms.
And there's a reason I chose to keep it that simple.
The Problem With Most Prompts Isn't the Model
Imagine asking an AI assistant:
Write a cold email to a SaaS founder.
The model generates something.
It sounds professional.
It mentions innovation, growth opportunities, and perhaps a "mutually beneficial collaboration."
You read it.
And you immediately know you would never send it.
Too generic.
Too long.
Too much corporate language.
Nothing that demonstrates actual understanding of the recipient.
So you tell the AI to make it shorter.
Then more personal.
Then less salesy.
Then more confident.
Then you ask it to remove the unnecessary introduction.
Five iterations later, you're still correcting things that could have been established before the first response.
Now consider what the original prompt actually communicated.
It never specified:
- What kind of SaaS founder we're targeting.
- What the email is supposed to accomplish.
- Which information is available about the company.
- How long the message should be.
- What tone should be used.
- Which claims must not be invented.
- What a successful final response should look like.
Yet we expected the AI to somehow infer all of that.
We gave it an incomplete specification and expected a production-quality deliverable.
As a software engineer, that contradiction is difficult to ignore.
We wouldn't hand a developer a one-line requirement for a critical feature and assume they could reconstruct every business rule, edge case, and acceptance criterion.
Why do we routinely expect AI systems to do exactly that?
Prompting Is an Interface Design Problem
I think we need to stop treating prompts as casual messages and start treating them as interfaces between human intent and machine execution.
An API request has a contract.
It defines what the caller provides, how the system should interpret it, and what kind of response is expected.
When that contract is ambiguous, unexpected behavior becomes more likely.
Prompting has a similar problem.
The model receives natural language instead of a strongly typed request.
That flexibility is powerful.
But it also creates enormous room for interpretation.
Consider these two instructions:
Instruction A:
Review this code and make it better.
Instruction B:
Review this Node.js authentication middleware for authorization bypasses, insecure session handling, and missing validation. Prioritize findings by severity, cite the relevant code, and avoid recommending unrelated architectural changes.
Both ask for a code review.
But they establish very different expectations.
The first leaves the agent to decide what "better" means.
The second identifies the domain, the objective, the review boundaries, and the expected evidence.
Neither guarantees that the model will discover every vulnerability.
But the second makes the intended work significantly less ambiguous.
That's the principle behind ART.
The goal isn't to control every word the model produces. It's to reduce unnecessary uncertainty about the work it needs to perform.
Introducing the ART Prompt Framework
ART is built around three components:
A — Act As
R — Request
T — Terms
Each component addresses a different source of ambiguity.
Together, they create a structured specification that can be reused across models, conversations, and workflows.
Let's break them down.
A — Act As: Establish the Right Expertise
Most people have written something like:
Act as an expert.
But an expert in what?
With which responsibilities?
Using what judgment?
A senior backend architect reviewing a distributed transaction should approach the problem differently from a technical writer documenting that transaction.
Both might be experts.
Their objectives, priorities, and decision-making standards are not the same.
ART encourages specificity.
Instead of:
Act as an experienced developer.
Try:
Act as a senior backend engineer specializing in Node.js, distributed systems, API reliability, and production debugging. Prioritize correctness, security, maintainability, and operational simplicity.
This establishes the perspective the model should adopt.
Importantly, assigning a role doesn't magically give a model expertise it doesn't possess.
It helps orient the response toward the relevant domain and the standards you want applied.
That's the real value.
A useful role isn't a decorative title. It's a way of communicating which kind of judgment the task requires.
R — Request: Define the Actual Mission
This is where the majority of vague prompts fall apart.
People describe the general topic instead of the required deliverable.
"Help me with marketing."
"Build an application."
"Analyze this business."
"Fix my code."
These are directions, not complete specifications.
The Request component forces us to establish the intended outcome.
What exactly needs to be produced?
Who is it for?
What information is available?
What is the purpose?
What should remain outside the scope?
For example:
Design a REST API for a multi-tenant SaaS application that allows organization administrators to invite, manage, and remove team members. Include endpoint definitions, authentication and authorization boundaries, request and response schemas, and relevant failure cases. Assume Node.js and PostgreSQL.
Now the agent knows what it's building and which assumptions matter.
It doesn't need to invent the entire project.
It has a defined mission.
And that makes its output easier to evaluate.
T — Terms: Define the Rules of Engagement
This is my favorite part of the framework.
Because even when you establish the right role and define a clear task, the model still needs boundaries.
Terms define those boundaries.
They can specify:
- Required output structure and formatting.
- Length, tone, and level of detail.
- Technical and business constraints.
- Sources the model may rely on.
- Information that must not be invented.
- Requirements that must remain unchanged.
- Behaviors and approaches to avoid.
The key is making those constraints testable.
"Be accurate" is a preference.
"Use only facts from the attached document, and explicitly identify anything unverifiable" is an actionable instruction.
"Write professionally" is subjective.
"Use concise, direct language; avoid exaggerated claims, generic praise, and buzzwords" is considerably more specific.
This is where ART becomes especially useful for real work.
Terms turn expectations into explicit boundaries before the model has an opportunity to make the wrong assumptions.
What an ART Prompt Actually Looks Like
Let's return to our original example.
The vague request was:
Help me write a cold email to a SaaS founder.
Here's how the framework restructures it:
ACT AS:
A seasoned B2B sales copywriter who writes
short, specific cold emails that busy SaaS
founders actually read.
REQUEST:
Write one cold email to the founder of a
20-person B2B SaaS company that sells
inventory software to small retailers.
Goal: Book a 15-minute introductory call.
Use only the company name and founder's
first name as placeholders.
TERMS:
1. Length: 75–100 words.
2. Tone: Direct and peer-to-peer.
No buzzwords or exclamation marks.
3. Structure:
- Opening: One specific observation.
- Value: One concrete potential benefit.
- Closing: One low-friction CTA.
4. Do not invent facts about the company.
Leave unknown information unspecified.
5. Avoid generic openings like
"I hope this finds you well."Notice what's changed.
We haven't made the prompt unnecessarily complicated.
We've made the assignment explicit.
The AI now knows which perspective to adopt, what it needs to deliver, and which constraints matter.
If the result is still inadequate, we have something concrete to inspect.
Was the requested outcome wrong?
Was important context missing?
Were the terms too restrictive?
Did the model fail to follow a clearly defined instruction?
Instead of randomly rewriting sentences, we can diagnose the actual problem.
That's the difference between trial-and-error prompting and systematic prompt design.
Why I Built ART as an Agent Skill
I didn't want to create another document that people read once, bookmark, and never use again.
I wanted a practical framework that could become part of an existing AI workflow.
That's why ART is also packaged as an agent skill.
The repository contains a SKILL.md file defining the framework, its conversion process, and its output requirements.
Once the skill is installed in a compatible environment, you can give your agent a rough instruction:
Turn this into a strong prompt using ART: Create a system design document for a real-time chat application.
The skill guides the agent to convert that request into the three ART sections.
It identifies an appropriate role.
Clarifies the deliverable.
Preserves the original requirements.
And adds relevant, checkable constraints without unnecessarily expanding the scope.
The result is a self-contained prompt designed to be copied directly into another AI conversation.
This distinction matters.
ART doesn't require you to use one particular model for the prompts it generates.
The skill provides the instructions for creating the prompt.
The resulting ART prompt is plain text.
You can use it with ChatGPT, Claude, Gemini, or other language models.
The surrounding skill-installation mechanism depends on the agent environment, but the underlying framework is model-independent.
That was intentional.
I didn't want prompt quality to depend on one vendor's interface.
One Rule I Consider Non-Negotiable: Preserve Intent
There's a subtle problem with asking AI to improve prompts.
Sometimes the AI "improves" a request by quietly changing what the user wanted.
It adds new objectives.
Expands the scope.
Introduces unnecessary deliverables.
Or removes constraints it considers inconvenient.
The result looks sophisticated.
But it's no longer the same assignment.
That's not improvement.
That's instruction drift.
ART explicitly addresses this during prompt conversion.
When improving an existing prompt, the skill is instructed to preserve the user's intent and explicit requirements.
Role information belongs in ACT AS.
The task belongs in REQUEST.
Constraints belong in TERMS.
Vague language should become more specific.
But missing requirements shouldn't be silently invented.
If an additional requirement would be genuinely useful, it can be suggested separately.
A prompt-engineering framework should clarify your intent, not replace it with the model's preferences.
This becomes especially important when the prompt describes software architecture, business decisions, financial analysis, or any task where an invented assumption can materially change the outcome.
What ART Is — and What It Isn't
I want to make an important distinction.
ART is not a claim that every task requires a long prompt.
It isn't a promise that three headings will eliminate hallucinations.
And it isn't evidence that one prompt format will outperform every alternative across every model and benchmark.
Modern language models can handle many simple requests extremely well without elaborate instructions.
If you're asking for a straightforward definition, a unit test for a tiny function, or a quick explanation, adding unnecessary structure can waste time and tokens.
Use the complexity the task actually deserves.
ART becomes particularly valuable when the task has several independent requirements, a specific audience, meaningful constraints, or a deliverable that needs to be reproducible.
And even then, prompt structure is only part of the equation.
A model can still misunderstand instructions.
It can still make mistakes.
It can still lack the information needed to produce a correct result.
For consequential work, you still need verification, reliable sources, appropriate tools, and human judgment.
A better prompt improves the specification. It doesn't guarantee the execution.
I think that's an important distinction in a space where prompt-engineering advice sometimes sounds more like mythology than engineering.
Getting Started With ART
The framework is open source and available on GitHub.
Repository: https://github.com/YourAKShaw/art-prompt-framework
Install for Claude Code
Clone the repository into your personal skills directory:
git clone \
https://github.com/YourAKShaw/art-prompt-framework.git \
~/.claude/skills/art-prompt-frameworkInstall With Skills CLI
For supported agent environments:
npx skills add YourAKShaw/art-prompt-frameworkUse It in Claude.ai
Download the repository as a ZIP file, ensure SKILL.md is available at the root of the skill folder, and upload it through Claude's skills interface where supported.
Try It
Once installed, ask your agent:
Write an ART prompt to help me build an automated financial reconciliation pipeline in Python.
Or:
Convert this rough request into the ART framework: Review my backend architecture and recommend improvements.
The skill returns a structured, self-contained prompt with the three headings:
ACT AS:
REQUEST:
TERMS:You can review it, refine it, and use it in a new conversation.
The repository is released under the MIT License, and contributions are welcome.
Why I Decided to Open-Source It
My work increasingly involves software engineering, AI systems, coding agents, research, and business operations.
Across these areas, I've found one recurring problem particularly frustrating.
The cost of ambiguity.
A developer misunderstands a requirement.
A client describes an outcome without explaining the underlying constraint.
An AI agent implements the wrong interpretation of a technically valid instruction.
A research task produces an impressive report that never answers the original question.
Different situations.
Same underlying problem.
The specification wasn't clear enough.
ART is a small attempt to make that problem more manageable.
It doesn't need to become an elaborate methodology.
It doesn't need an entire ecosystem of proprietary tooling.
And it certainly doesn't need to pretend that structured prompting is a revolutionary discovery.
The ideas behind explicit roles, clear objectives, and concrete constraints have existed in various forms for a long time.
What I wanted was a minimal framework that engineers, founders, researchers, writers, and everyday AI users could apply without having to study prompt-engineering theory.
Something memorable enough to use consistently.
Flexible enough to work across domains.
And simple enough to improve.
Three components.
One clear specification.
Less unnecessary guesswork.
That's the idea.
Better AI Outputs Start With Better Questions
We're entering an era where AI systems can do considerably more than generate text.
They can write software.
Analyze documents.
Use tools.
Research complex topics.
Coordinate workflows.
And increasingly operate across multiple steps toward a defined objective.
But greater capability creates an interesting problem.
The more work an AI system can perform, the more expensive a misunderstood instruction can become.
A poorly specified paragraph might cost you a few minutes.
A poorly specified software task can result in hours of unnecessary development.
A poorly constrained automation can produce outcomes that require real human intervention to correct.
That makes clarity more important, not less.
And yet the solution doesn't always require a more sophisticated model.
Sometimes it requires us to become more disciplined about communicating what we actually want.
That's why I built ART.
Not because I think prompt engineering needs another collection of clever tricks.
But because I think AI workflows need better specifications.
And I believe the simplest frameworks are often the ones people can actually sustain.
Stop treating the prompt as a question you throw at a model. Start treating it as a specification for the outcome you're expecting.
Define the expertise.
Clarify the mission.
Establish the boundaries.
Then evaluate the result against what you actually asked for.
That's ART.
And if you're building with AI regularly, I'd encourage you to try it, challenge it, and improve it.
Explore ART Prompt Framework
GitHub: https://github.com/YourAKShaw/art-prompt-framework
License: MIT
Contributions, issues, and constructive feedback are welcome.
I'm particularly interested in hearing from people using AI for engineering, research, and other complex workflows.
When your AI produces a disappointing result, how often do you question the model — and how often do you question the specification you gave it?
#PromptEngineering #AIAgents #GenerativeAI #OpenSource #LLMs
