My AI assistant kept guessing my conventions, so I built a CLI that asks me once

What's the most important part of a new building? Not the paint, and not the windows. It's the foundation (Payo). If the foundation is wrong, each new floor leans more.

Software works the same way. And these days, an AI assistant lays a lot of the bricks.

Payo is the Gujarati word for foundation. It's also the open-source CLI I built after many sessions where my assistant worked on the wrong foundation. If you code with Claude Code, Cursor, Codex or Copilot, you probably have the same problem.

The message I kept pasting

Every new chat with my AI assistant started the same way. I pasted a block of text from a notes file. It always explained the same things:

• where each kind of file goes
• how to split the code into files and modules
• where the test file sits
• what goes into a commit message
• how to handle errors

When I skipped a part, the assistant made its own choices. It put files wherever it felt right. A database migration had column and constraint names that matched nothing else in the schema. It wrote a function again from scratch, a few files away from the same function in the shared utils. The code worked. But it did not match the rest of my project.

I'm not the only one. Most developers I talk to keep some version of that notes file, in a gist, a pinned message, or their head. For teams, the problem is bigger, because each person's assistant follows a different half of the rules.

I knew the proper fix. Write an AGENTS.md and skills under .agents/skills/. Every major assistant reads them now. I just never did it. Good guidance takes a long time to write by hand.

So on June 7 this year I started Payo. I wanted every new project to get a solid foundation of rules on day one, so the assistant builds on it instead of guessing. I now run it on every repo I touch.

This post covers why generic skills don't fix this, what does, and three layers of guidance that work even without Payo.

What I tried first

First I tried skills packs and awesome-lists. They weren't bad, but their authors wrote them for everyone, so they fit no one in particular. One skill told the agent to put files in the right place, but never said which file goes where. Another said not to duplicate code, but never said where the shared code lives. None of them said how to write a commit message. Every rule ended one step before the part I needed.

Every team builds its own way, and a generic skill can't know it. It will never say that you prefer TypeORM over Drizzle. Worse, it can tell the agent to use Drizzle, because its author does. Now your skill and your codebase disagree, and the agent has to pick one. That does more harm than good.

So what would work?

Skills written for one project. Your stack, your structure, your rules.

You can ask the AI to write them, and that half works. In one prompt, neither of you remembers everything. You forget the commit format, the AI fills the gap with its own default, and you are back at generic.

Wouldn't it be better if a tool asked you about every part of the project that matters? You pick the answer that fits, and the tool writes the skills from your answers.

That's what Payo does

Payo is an interactive CLI. It has a bank of 200+ questions that covers 30 frameworks, 29 ORMs and 17 databases across eight languages. It asks only the questions your stack needs. For most of them you pick an option, or choose Custom and type your own answer. Most questions have a recommended default, so you often only press Enter.

At the end, it writes an AGENTS.md and a set of skills under .agents/skills/ from your answers.

Payo uses the agent CLI you already have (claude, codex, cursor-agent, copilot, or agy) to write the skills, several at a time. No agent CLI installed? Payo fills its built-in templates with your answers. The text is plainer, but the rules are still yours, and that already beats a generic pack.

Payo works best on a new project. You answer the questions before the first line of code. It can also write a prompt that tells your assistant to create the project with the framework's tooling. It works on existing projects too. It detects your stack from the manifests and asks only about the rest.

What Payo covers

• Project and stack. Project type, language, framework, and framework conventions.
• API and frontend. REST, GraphQL, gRPC or tRPC, plus styling and state management.
• Data and auth. Database, ORM, naming, migrations and auth approach. The agent asks you before it runs destructive SQL.
• Quality. Validation, logging, and unit, integration and E2E tests.
• Tooling and conventions. Package manager, formatter, linter, folder structure, coding standards, and the git workflow it reads from your history.

Each topic becomes its own skill, and only if your project needs it. Payo also offers two optional skills:

• change-audit checks your change against the project skills before you push.
• pr-review reviews your changes, a branch, or a PR against the project skills. It asks what to focus on before it reads any code. It checks each finding against the code around it. It never runs PR code and never approves a PR.

A real run, in a language I don't know well

My current side project is a file backup tool. I plan to open-source it soon too. I wanted to write it in Rust, and I'm not a Rust expert. That's the hardest case for an AI assistant. I can't see when its Rust is wrong, and I don't know the conventions well enough to write them down.

So before I wrote a single line of code, I ran Payo in an empty folder.

It asked only what my stack needed. About 30 questions. My Rust knowledge is basic, but each question had a recommendation. I could pick what most developers use without researching every crate. The interview took about two minutes. The whole run finished in under five.

It showed me the skill list before it wrote anything. It offered project-overview, coding-standards, framework-conventions, data-layer and error-handling-logging. A backup tool has no login and no HTTP API, so there was no auth skill and no API skill. Not a stub, not an "N/A" section. The file doesn't exist.

Then it wrote one copy that every tool reads. One SKILL.md per topic under .agents/skills/, an AGENTS.md that tells the agent to read the skills before it writes code, and symlinks for Claude Code. No copies per tool to keep in sync.

The skills themselves are the part every generic skill missed. They say which file goes where, and they give the real table and column names, the same names my migrations kept getting wrong. I do not know Rust well enough to write these rules myself.

Hooks, the part I didn't expect to build

A skill is prose. An agent can skip prose. Even with good skills in the repo, agents often miss AGENTS.md or CLAUDE.md and never open the skills. Over time an agent stores some of your rules in its memory. That's still a guess, and you never know which rules it kept.

I learned this on another project. The skills said our database columns were camelCase. The agent never read them and wrote a table migration with snake_case columns. Nothing stopped it. I found it only in PR review.

So Payo now writes the thing that enforces a rule, not only the rule:

1. A git hook that blocks the commit or push. Lefthook, Husky, pre-commit or plain .githooks/, your pick. It runs gitleaks, your tests, your linter, and a format check. It blocks humans too.
2. A native pre-tool gate. The hook the agent runs before a tool call, like Claude Code's PreToolUse, for Claude, Cursor, Copilot, Codex and others. Database changes ask me first. The change-audit gate denies git push until the agent checks the diff against the project skills and records a pass for that exact change. People approve confirm prompts without reading them, so this gate is a hard deny. Only I can approve the push.

That migration is exactly the kind of change it catches. Here it is in my backup project, the other way around. The agent wrote a camelCase column, and the skills say snake_case.

I also learned not to make the agent and the hook run the same checks. My first version ran the test suite twice per commit. Now the skills tell the agent to skip what the hook runs.

The three layers of guidance

Layer	What it is	What it stops
Prose	AGENTS.md and skills	Nothing. The agent reads it and can still skip it
Gate	The agent's own pre-tool hook	The agent, before it runs the command
Git hook	Lefthook, Husky, pre-commit	Everyone, humans included

Most repos have only the first layer. Prose tells the agent what you want. The other two layers make sure it happened.

What changed for me

• I stopped explaining the basics. I don't tell the agent where a file goes or which naming convention to follow. I don't need the notes file anymore.
• I stopped worrying about code quality and side effects. The agent works inside the rules instead of guessing.
• PR review got easier. I get small atomic commits instead of one large commit. Each has a proper message.
• change-audit and the hooks check the rest. Before a push lands, the agent checks the change against the skills, gitleaks scans for secrets, and the tests and lint run.

Next steps

• Add one skill without the full interview. Today Payo asks every question, even if you only want pr-review. Next, you name the skill and answer only its questions.
• More languages, libraries and frameworks, with recommendations from people who work in those stacks every day.
• An audit flow. Payo compares your skills with the current codebase and shows where they no longer match.
• A better flow for existing projects.

Try it

On macOS or Linux:

curl -fsSL https://payo.uttamgelot.com/install.sh | sh

On Windows (PowerShell):

irm https://payo.uttamgelot.com/install.ps1 | iex

Or npx @uge/payo if you have Node. It's MIT licensed, and the code is at github.com/uttam-gelot/payo

If you run it on your repo, tell me what it got wrong. Most fixes in Payo came from these reports.

If you do not try it, answer this question. What do you keep telling your AI assistant in every new chat? I want to know which rules everyone repeats.

Whatever you build next, give it a good Payo first.