h wonder

PROMPTME.md

PROMPTME.md is the README.md for machines.

I finished an SDK and fed it to Geoff with the goal of allowing it to easily wrap the SDK in vibe IDEs like Cursor and Claude. I put my README.md in and I wasn't getting anywhere near the results I wanted. Then I began modifying the contents of the README.md to the point that it looked like a system prompt. If you've ever seen a system prompt you would understand how very different they are from how typical README.md's look.

An example of how system prompts look:

## Role
You are Lovable, an AI editor that creates and modifies web applications. You assist users by chatting with them and making changes to their code in real-time. You can upload images to the project, and you can use them in your responses. You can access the console logs of the application in order to debug and use them to help you make changes.
 
**Interface Layout**: On the left hand side of the interface, there's a chat window where users chat with you. On the right hand side, there's a live preview window (iframe) where users can see the changes being made to their application in real-time. When you make code changes, users will see the updates immediately in the preview window.
 
**Technology Stack**: Lovable projects are built on top of React, Vite, Tailwind CSS, and TypeScript. Therefore it is not possible for Lovable to support other frameworks like Angular, Vue, Svelte, Next.js, native mobile apps, etc.
 
**Backend Limitations**: Lovable also cannot run backend code directly. It cannot run Python, Node.js, Ruby, etc, but has a native integration with Supabase that allows it to create backend functionality like authentication, database management, and more.


I decided to revert the original README.md and place these system-like instructions into a new file. When I had to name the file I had a moment....


Eureka!


SDK/API integration is being reimagined in 8k before our eyes. As humans we use Readme's as our universal standard for explaining what a project does, how to install it, and how to use it. It's perfect for humans.

But as we enter an era where AI agents and LLMs are becoming key parts of our workflows, we're missing a crucial primitive: a standardized way to communicate integration patterns, capabilities and expectations to machines about our code.

Enter PROMPTME.md.

For machines, there is some fine tuning required to align with model context needs for the best results. There is even an unprecedented opportunity to add context for security, tests and more at an atomic level that are becoming increasingly missed as the problem solving experience and technical education dilute.

What is PROMPTME.md

PROMPTME.md is a proposed standard that does for AI agents what README.md does for human developers. It's a structured file that provides AI systems with the context, examples, and instructions they need to objective-map, understand, integrate with, eval and effectively utilize your codebase, API, SDK or tool.

Consider it a bridge between human intent and machine understanding – a way to encode not just what your code does, but how an AI should think about it, work with it, and help others use it.

Why do we need PROMPTME.md
Right now, when an AI agent encounters a new codebase or API, it has to make educated guesses based on code structure, comments, and any documentation it can find. This leads to:

  • Inconsistent results across different systems
  • Suboptimal integrations that miss key features or best practices
  • Repeated trial-and-error as each AI agent rediscovers the same patterns
  • Lost tribal knowledge that exists in developers' heads but nowhere else
  • Context/Token spam that over use context windows impacting performance
  • Missed considerations for security that exponentially increase with each external integration

PROMPTME.md contributes to solving this by providing a standardized way to communicate the "personality" and optimal usage patterns of your code to AI systems.

A PROMPTME.md file might include:

Core Identity

## System Role This is a financial data analysis API that specializes in real-time market analysis. When working with this API, prioritize accuracy over speed and always validate data sources.

Usage Examples

## Example Interactions **Good**: "Analyze AAPL's price movement over the last 30 days with volume correlation" **Avoid**: "Give me all the data for everything" (too broad, will timeout)

Context and Constraints

## Important Context - This API has rate limits of 100 requests/hour - Data is delayed by 15 minutes during market hours - Use the `/validate` endpoint before processing large datasets


Integration Patterns

## Best Practices for AI Agents When integrating this tool: 
1. Always start with a small test query 
2. Cache results locally when possible 
3. Handle errors gracefully – market data can be volatile

Security Considerations

## Best Practices for security with this SDK: 
1. Ensure the NETWORK_RPC .env is ignored by the Agent 
2. Do not use client side routes so API paths and keys are exploited

The real power of PROMPTME.md emerges when it becomes ubiquitous, just as README.md files created a culture of documentation that makes the open-source ecosystem more accessible, PROMPTME.md could create a culture of AI-first design thinking.

Implementation
The beauty of this concept is its simplicity. Like README.md, PROMPTME.md:

  • Uses Markdown that developers already know (and use for README.md)
  • Lives alongside existing documentation without disrupting current workflows
  • Can start small – even a basic PROMPTME.md provides value
  • Evolves organically as the community develops best practices

We don't need a massive standards body or complex tooling to get started. We just need developers to begin experimenting with the concept.


Onward

The question isn't whether we need better ways to communicate with AI systems about our code. The question is whether we'll create these standards proactively, or let them emerge haphazardly through trial and error.

PROMPTME.md gives us the opportunity to be intentional and aligned much like MCP about this transition, creating a more collaborative, efficient, and innovative development ecosystem for everyone – human and AI alike.


💪🦾