Before I started using Pi seriously, I kept hearing one thing.
“Pi has a very slim system prompt.”
Of course, I could have opened the GitHub repository and read the prompt directly.
But that wouldn’t be as fun.
So I built a small Pi extension that prints the exact payload sent to the AI model. It dumps everything into JSON: the system prompt, available tools, loaded skills, and other request data.
If you’re curious, I’ll share the GitHub repository at the end of this post.
Pi agent harness, from pi.dev.
Looking at the real payload
After seeing the payload myself, I understood why Pi feels lightweight.
The system prompt is indeed small.
Most of it is not “AI instructions.” Instead, it tells the model:
- what tools are available (only basic Pi tools such as read, write, edit, and bash)
- what skills exist
- how Pi itself can be customized
The interesting part is the last one.
Pi ships with very well-written documentation. Instead of stuffing everything into the system prompt, it references those documents so the model knows how the framework works.
It is already much smaller than many coding agents I have seen.
But after reading the payload, I started asking another question.
Can it be optimized further?
My experiment
I noticed that a good portion of the prompt was about Pi’s own documentation.
That information is useful.
But honestly…
I don’t need the agent to remember how to build Pi extensions every single request.
Most of the time, I’m just asking it to write code.
So I tried moving those documentation instructions into a separate skill.
I called it pi-docs.
Now, whenever I need Pi-specific knowledge, I simply tell the agent:
use pi-docs
Pi loads the skill only when it is actually needed.
The rest of the time, those tokens stay out of the context window.
The result
The difference was bigger than I expected.
A simple prompt like:
hi
now uses only around 1,2K context tokens.
I like that.
Small requests stay small.
Pi only loads additional knowledge when I explicitly ask for it.
It feels closer to the Unix philosophy.
Load only what you need.
Rebuilding the system prompt
That experiment also made me think about another idea.
Instead of keeping Pi’s original system prompt, why not make one that matches my setup?
So I extracted the original prompt into a SYSTEM.md file, placed it in ~/.pi/agent/SYSTEM.md, and started customizing it.
Not because I thought the original was bad.
It simply didn’t know anything about the extensions I installed.
My Pi has tools that don’t exist in a fresh installation.
For example:
subagenttodoweb_search- and a few others
Without mentioning them, the model has no idea those tools exist or how to use them correctly.
So I expanded the prompt to explain what each tool does and when it should use it.
The result wasn’t a longer prompt for the sake of being longer.
It was a prompt that better described my environment.
That’s a trade-off I’m happy to make.
One thing I like about Pi
This experiment reminded me of something I appreciate about Pi.
The framework doesn’t try to hide how it works.
The prompt is easy to inspect.
Skills are just files.
Tools are easy to discover.
If I don’t like something, I can usually change it.
That makes experimentation fun.
Instead of wondering what the agent is doing, I can inspect it, modify it, and measure the result.
That’s the kind of developer experience I enjoy.
Final thoughts
Did moving the documentation into a skill suddenly make Pi smarter?
No.
That wasn’t the goal.
The goal was to optimize the system prompt for my workflow: keep essential context by default, load Pi documentation only when needed, and explain the extra tools I use.
For my workflow, it worked surprisingly well.
And maybe that’s the biggest lesson from this experiment.
Prompt optimization isn’t just about making it shorter.
It’s about putting the right information in the right place, at the right time.
If you’d like to try the same setup, I’ll share the repositories for:
Feel free to use them as a starting point or customize them for your own workflow.