Your first prompt

This walkthrough takes about 15 minutes. You will add a practice prompt, preview and write its page, run the checker, and read the result. Then you will remove the practice files. Nothing is sent to an AI model.

Before you start

Clone the repository and open a terminal at its root. Run every command there.
Skim the Prompt file format section if you want the reasons behind each field.

Step 1: Check your Python version

python3 --version

The tools need Python 3.10 or newer. On some systems, for example macOS, the default python3 can be older. The tools then stop with one line on standard error and exit with status 2, and they show no traceback. The line reads like this:

check: this tool needs Python 3.10 or newer, but this is 3.9. Run it with a newer python3.

If you see it, install a newer Python and run the commands below with that python3.

Step 2: Create the prompt file

Create the file prompts/op/first-prompt-practice.md. Create the op folder first if it does not exist. Paste in this content.

---
id: "P-OP-99"
title: "First prompt practice"
stage: "OP"
purpose: "Practice adding a prompt."
placeholders: ["TOPIC", "AUDIENCE"]
capabilities: ["llm"]
---
````text
Explain {{TOPIC}} to {{AUDIENCE}} in three short sentences.
Define any term that the audience might not know.
````

This prompt exists only for the walkthrough. Delete it when you finish.

The fields work like this.

id is P for prompt, OP for operating practices, and 99, a number chosen for practice.
stage is OP. It matches the ID and the folder name op.
placeholders lists the two names that the prompt uses. capabilities lists what the prompt needs from a platform.
The four-backtick fence holds the prompt. The text after it is notes.

Step 3: Preview with a dry run

python3 -B scripts/site/sync.py

The -B flag stops Python from writing __pycache__ folders. The command prints a plan and writes nothing. The plan should list the page for your prompt, docs/prompts/op/p-op-99.md. It may also list the index page for the op folder and an update to the prompt library index.

If the prompt has an error, you get no plan. The tool prints one line and exits with status 2, as in this example.

sync: prompts/op/first-prompt-practice.md: line 7: unknown capability 'gpu'

The tool is working as intended. To see every problem, run the checker in Step 5. It reports the same file under rule R08, which names the line to fix, and under rule R11. Fix the R08 errors first, then run the dry run again.

Step 4: Write the generated page

python3 -B scripts/site/sync.py --write

Run the same command a second time. The second run should report nothing created and nothing updated.

Step 5: Run the checker

python3 -B scripts/site/check.py

Every run prints R10 private-term check skipped: no list supplied on standard error when you give it no private list. That is normal.

Each finding is one line: path:line RULE message. A summary line, check: N errors, M warnings, comes last. The command exits with status 0 when there are no errors, 1 when there is at least one error, and 2 for a usage error or an unreadable input.

Look for lines that name your prompt or its generated page. Fix the source file, run sync.py --write again, and then run the checker again. If you skipped Step 4, expect R11 findings, because the generated files are missing.

Step 6: Read the generated page

Open docs/prompts/op/p-op-99.md in a text editor. Its title is the ID followed by the title. It holds a table with the purpose, the capabilities under “Needs”, the placeholders, and a link to the source file. Below the table are a Prompt section with your text and a Notes section with the text after the fence.

The table has a “Used in” row only when some page lists the ID under prompts:. No page lists this prompt, so the row is absent.

Do not edit this file. The sync tool owns it, and your edits would be reported as drift.

Step 7: Clean up

Delete prompts/op/first-prompt-practice.md.
Run python3 -B scripts/site/sync.py --write --prune. It deletes the stale generated page. It also deletes the index page for the op folder if no other prompt uses that folder, and it rewrites the prompt library index.
Run python3 -B scripts/site/sync.py --check. It exits with status 0 when nothing has drifted.

Without --prune, the tool only reports stale files. With --prune but without --write, it only prints what it would delete.

Next steps

To add a real prompt, read Authoring conventions and pick an ID and a folder. List the ID under prompts: on the page that uses it, and link the generated page in that page’s Prompts section. Then work through the Release checklist.