Prompting in practice

Vague prompts get vague work; a clear shape gets work you can check. This page gives you the shape and templates to copy.

Why today's prompts were so short

"Start the Analyst step." is four words. It worked because the Analyst skill in your repo contains the long instructions: which questions to ask, which files to write, what to leave out. A skill is a prompt written once, with care, and used many times.

For work outside the Roles you write the prompt yourself. Then the shape below helps.

The shape

Almost every useful prompt has five parts. Say all five:

Inputs: which files or facts to read first.
Outputs: what you want back, and in which file.
Scope: what not to touch.
Constraints: the rules it has to keep, such as your design brief.
Verification: how you both know it worked.

Vague

"Make my site better." The agent has to guess what "better" means, where to change it, and when it is done.

Shaped

"Read design/brief.md. Make the project cards easier to see, with the surface colour from the brief. Change only site/assets/styles.css. Run node tools/check.mjs and show me the result."

Templates for your portfolio

A small fix. Say what is wrong and where, and which file to change.

Agent chat

Read <file>. Fix this: <what is wrong, and where you see it>.
Change only <file>.
Then run node tools/check.mjs and read the change back to me.

A new piece of content. Point to the schema (the list of what the content file may contain), so the content file stays valid.

Agent chat

Read site/content.json and site/content.schema.json.
Add <what> to my content, in the shape the schema allows.
Change nothing else. Then run node tools/check-content.mjs
and read the change back to me.

A question, without changes. Make clear that no file may change.

Agent chat

Look at site/ and tell me <what you want to know>.
Do not change any file. I decide what to do with your answer.

Speak instead of typing

When you speak, you give more detail in less time, and the five parts come almost by themselves. Every system has dictation built in: on a Mac press the Fn key twice (or choose Edit → Start Dictation), on Windows press Win+H. On Linux it depends on your desktop.