V
“Add this article to my website” leaves several decisions open. Should the AI write a draft, change the local project, check the page in a browser, or publish it?
You may have one result in mind while the agent stops at another. A saved file can be useful, but it is not a finished website update if the page still has broken links or a missing cover image.
OpenAI's guide to prompts and skills for GPT-6 Astra recommends reviewing the instructions you give Codex. It highlights focused skill descriptions, relevant supporting files, clear approval rules, and an explicit definition of completion.
I cover these ideas in my Codex video tutorial. This article works through one example: preparing a website article for local review. The prompts, skill, and file paths below are teaching examples. Replace the paths and checks with those from your project.
A task prompt, a skill, and an
OpenAI documents skills as reusable workflows and AGENTS.md as persistent project guidance.
For the website example, the current article's title belongs in the task prompt. The process for preparing article previews belongs in a skill. The site's content folder and build commands belong in its project instructions.
This also makes updates easier. If the project changes its build command, you have one project rule to update instead of several copied versions inside different skills.
Start with the work you want to receive. Add the information that changes how the agent should do it.
A vague request might be:
Here is a more useful version for a local draft:
The prompt defines an output, the inputs, the checks, and the stopping point. It also explains what the agent should preserve.
OpenAI's prompting documentation recommends including the goal, relevant context, output, and boundaries when they matter. For a small request, a sentence may cover all you need.
You do not need to prescribe every file read or tool call. If the order of work matters, explain why. Otherwise, let the agent inspect the project and choose a suitable approach.
Missing information needs a rule too. If the article has no publication date, the agent should report that gap rather than invent an approved date. It can still inspect the layout and prepare work that does not depend on that decision.
Once you repeat the same workflow, a skill can hold its reusable instructions.
For this example, the job is to add a supplied article to an existing website and prepare a local preview. Writing the article from scratch, redesigning the site, and publishing it are separate tasks.
That scope should appear in the skill description.
A description like this is too broad:
A request to fix a navigation menu could match it, even though the skill has nothing useful to say about navigation.
A more precise description is:
The description matters because Codex first sees a skill's name and description. It reads the full
Put the main job near the start. A long list of related topics can make it harder to tell when the skill actually applies.
For a repository skill, create this example structure:
OpenAI lists repository
Save this in
The file explains what the skill should produce and how to review it. It leaves project-specific commands in the project instructions.
The supporting file,
A small skill could keep these checks in the main file. A separate reference is useful if the checklist will grow or needs its own maintenance. Splitting files is a choice, not a requirement.
In Codex CLI, you can invoke the example explicitly:
The official skills guide documents
A skill can become harder to use when it grows into a large collection of unrelated instructions.
Suppose the article workflow later supports video embeds and translations. A video task may need embed rules. A translation task may need language guidance. An ordinary text article may need neither.
You could add these references:
Then explain when they apply:
OpenAI calls this approach progressive disclosure: make supporting instructions available when the task needs them. Its GPT-6 Astra guide recommends using a short main skill file to direct the model to relevant material.
Apply the same care to project documentation. A change to an article does not automatically need a database migration guide. Point to that guide when a task changes the database.
Keep mandatory project requirements intact. The aim is to explain when a document matters, without removing information that the task needs.
The example skill ends with a local draft because that is the workflow we chose. Another workflow might include publication when the user has authorized it.
Write the rule around the action and target:
This gives the agent a useful place to stop. “Ask before every step” would also interrupt the work needed to prepare that result.
Before applying the rule, check what the commands actually do. A command run on your computer may contact a live service. A build script may include deployment. A preview may be publicly accessible.
For publication approval, the agent should be able to show the prepared page, identify the site that will change, and report the relevant checks and unresolved issues.
Written instructions and technical access are separate controls. OpenAI's sandbox documentation explains that the sandbox limits command access to files and network resources, while approval settings control how requests at those boundaries are handled.
A prompt cannot grant a missing account permission or remove an enforced restriction. If access blocks the task, use the appropriate permission flow and report the work that remains.
A saved page still needs review. Check the requirements that could make this particular result unusable: missing content, broken rendering, incorrect metadata, or publication before the intended review.
Keep the project's required checks. If a check fails, fix the relevant problem and rerun the affected checks. If it passes and nothing relevant changes afterward, avoid repeating it without a reason.
A successful build also does not prove that a cover is readable or that a long code block fits on a phone. Those need a visual check when suitable tools are available.
Try the skill in a practice project with inputs you can change. Include requests that should use it and requests that should not.
These are expected behaviors to test, not results from a benchmark.
Compare changes on the same practice tasks. If you shorten a description, check that the skill still matches the right requests. If you remove a step, confirm that the output still meets the requirement that step was protecting.
An unexpected pause may come from the task prompt, a skill, project guidance, or a tool permission. Identify the source before changing it.
You can ask:
OpenAI's GPT-6 Astra instruction-following guidance recommends making the responsible skill and instruction visible when unclear guidance causes a pause.
For a broader review, use an audit prompt:
This audit stops at proposed edits because changing shared instructions affects future tasks. That is a different stopping point from preparing a local article preview.
Start with one workflow you already repeat. Write the result you expect, move its reusable rules into a focused skill, and check it with a complete input, a missing input, and an unrelated request.
My video tutorial covers seven ways to improve instructions for GPT-6 Astra in Codex. The full guide on my website includes more examples for prompts, skills, and
You may have one result in mind while the agent stops at another. A saved file can be useful, but it is not a finished website update if the page still has broken links or a missing cover image.
OpenAI's guide to prompts and skills for GPT-6 Astra recommends reviewing the instructions you give Codex. It highlights focused skill descriptions, relevant supporting files, clear approval rules, and an explicit definition of completion.
I cover these ideas in my Codex video tutorial. This article works through one example: preparing a website article for local review. The prompts, skill, and file paths below are teaching examples. Replace the paths and checks with those from your project.
Give each kind of instruction a clear purpose
A task prompt, a skill, and an
AGENTS.md file can all guide Codex, but they serve different purposes.| Instruction | What belongs there | Example |
|---|---|---|
| Task prompt | The result and inputs for this request | Add this article using this cover image |
SKILL.md | A workflow you expect to reuse | Prepare an article page and a local preview |
AGENTS.md | Rules for working in the project | Where posts live and which checks are required |
OpenAI documents skills as reusable workflows and AGENTS.md as persistent project guidance.
For the website example, the current article's title belongs in the task prompt. The process for preparing article previews belongs in a skill. The site's content folder and build commands belong in its project instructions.
This also makes updates easier. If the project changes its build command, you have one project rule to update instead of several copied versions inside different skills.
Write a prompt that describes the finished result
Start with the work you want to receive. Add the information that changes how the agent should do it.
A vague request might be:
Code:
Add my article to the website. Make sure it looks good.Here is a more useful version for a local draft:
Code:
Add drafts/tutorial.md to this website using
assets/tutorial-cover.png as its cover.
Use the existing article layout and author details.
Keep the supplied title, wording, code examples, and source
links unchanged. Follow the project's content conventions.
You may make the local changes needed for this draft.
Run the checks required by the project instructions.
Confirm that the commands you use do not also deploy
or change live data.
Inspect the rendered page at desktop and mobile widths
if browser tools are available. Check the cover, headings,
code blocks, and links. Fix problems caused by this change.
Finish with the changed file paths, the local preview
address or instructions, and the checks you completed.
Report missing inputs, failed checks, and checks you
could not perform.
Leave deployment for a separate instruction.The prompt defines an output, the inputs, the checks, and the stopping point. It also explains what the agent should preserve.
OpenAI's prompting documentation recommends including the goal, relevant context, output, and boundaries when they matter. For a small request, a sentence may cover all you need.
You do not need to prescribe every file read or tool call. If the order of work matters, explain why. Otherwise, let the agent inspect the project and choose a suitable approach.
Missing information needs a rule too. If the article has no publication date, the agent should report that gap rather than invent an approved date. It can still inspect the layout and prepare work that does not depend on that decision.
Give a skill one job
Once you repeat the same workflow, a skill can hold its reusable instructions.
For this example, the job is to add a supplied article to an existing website and prepare a local preview. Writing the article from scratch, redesigning the site, and publishing it are separate tasks.
That scope should appear in the skill description.
A description like this is too broad:
Code:
description: Help with websites, articles, content, design, and publishing.A request to fix a navigation menu could match it, even though the skill has nothing useful to say about navigation.
A more precise description is:
Code:
description: Add a supplied article to an existing website and prepare a checked local preview.The description matters because Codex first sees a skill's name and description. It reads the full
SKILL.md after selecting the skill. The skills documentation also explains that descriptions may be shortened when many skills are available.Put the main job near the start. A long list of related topics can make it harder to tell when the skill actually applies.
Write a small SKILL.md
For a repository skill, create this example structure:
Code:
.agents/skills/site-article-preview/
SKILL.md
references/
preview-checklist.mdOpenAI lists repository
.agents/skills/ folders among the locations where Codex loads local skills.Save this in
SKILL.md:
Code:
---
name: site-article-preview
description: Add a supplied article to an existing website and prepare a checked local preview.
---
# Prepare an article preview
Use the article and assets named in the user's request.
Follow the applicable project instructions. Inspect the
content structure and a relevant existing article before
choosing where to place the new content.
Preserve the supplied wording, names, dates, code examples,
and source links unless the user asks to revise them.
Report missing required inputs. Continue work that does
not depend on those inputs.
Make the needed local changes. Run the checks required
for this change by the project instructions.
Use references/preview-checklist.md to review the result.
Fix problems introduced by this change. Report checks
that fail or cannot be completed.
Finish with changed file paths, a local preview address
or instructions, and the check results.
This skill prepares a local draft. Leave deployment,
external messages, and changes to shared data outside
this workflow.The file explains what the skill should produce and how to review it. It leaves project-specific commands in the project instructions.
The supporting file,
references/preview-checklist.md, could contain:
Code:
# Article preview checks
Compare the saved article with the supplied source.
Check the title, author details, code examples, and links.
Confirm that required metadata is present.
Report missing values instead of inventing them.
If browser tools are available, inspect the article
at desktop and mobile widths. Check that the cover
loads, text remains readable, and code blocks fit.
If a browser check is unavailable, say so.
Do not describe that check as passed.
Confirm that the result remains a local draft.
List unresolved issues before calling it ready for review.A small skill could keep these checks in the main file. A separate reference is useful if the checklist will grow or needs its own maintenance. Splitting files is a choice, not a requirement.
In Codex CLI, you can invoke the example explicitly:
Code:
$site-article-preview
Add drafts/tutorial.md using assets/tutorial-cover.png.
Prepare the local page for review.The official skills guide documents
$ mentions and /skills for selecting skills in Codex CLI. If the skill does not appear, check its location, file name, and metadata, then restart Codex if needed.Load supporting files when they help the task
A skill can become harder to use when it grows into a large collection of unrelated instructions.
Suppose the article workflow later supports video embeds and translations. A video task may need embed rules. A translation task may need language guidance. An ordinary text article may need neither.
You could add these references:
Code:
references/
preview-checklist.md
video-embeds.md
translation-style.mdThen explain when they apply:
Code:
Read preview-checklist.md when reviewing the local page.
Read video-embeds.md when the supplied article includes a video.
Read translation-style.md when the user requests a translation.OpenAI calls this approach progressive disclosure: make supporting instructions available when the task needs them. Its GPT-6 Astra guide recommends using a short main skill file to direct the model to relevant material.
Apply the same care to project documentation. A change to an article does not automatically need a database migration guide. Point to that guide when a task changes the database.
Keep mandatory project requirements intact. The aim is to explain when a document matters, without removing information that the task needs.
Set approval rules around specific actions
The example skill ends with a local draft because that is the workflow we chose. Another workflow might include publication when the user has authorized it.
Write the rule around the action and target:
Code:
Prepare and check the article in the local project.
Show me the result before publishing to the live website.This gives the agent a useful place to stop. “Ask before every step” would also interrupt the work needed to prepare that result.
Before applying the rule, check what the commands actually do. A command run on your computer may contact a live service. A build script may include deployment. A preview may be publicly accessible.
For publication approval, the agent should be able to show the prepared page, identify the site that will change, and report the relevant checks and unresolved issues.
Written instructions and technical access are separate controls. OpenAI's sandbox documentation explains that the sandbox limits command access to files and network resources, while approval settings control how requests at those boundaries are handled.
A prompt cannot grant a missing account permission or remove an enforced restriction. If access blocks the task, use the appropriate permission flow and report the work that remains.
Check the result and the skill's scope
A saved page still needs review. Check the requirements that could make this particular result unusable: missing content, broken rendering, incorrect metadata, or publication before the intended review.
Keep the project's required checks. If a check fails, fix the relevant problem and rerun the affected checks. If it passes and nothing relevant changes afterward, avoid repeating it without a reason.
A successful build also does not prove that a cover is readable or that a long code block fits on a phone. Those need a visual check when suitable tools are available.
Try the skill in a practice project with inputs you can change. Include requests that should use it and requests that should not.
| Practice request | What to check |
|---|---|
| Add a complete supplied article | The page is prepared, required checks run, and a preview is provided |
| Add an article with a missing required cover | The missing asset is reported and dependent work stays marked incomplete |
| Fix a navigation menu bug | The article-preview skill is not chosen just because the request concerns a website |
| Prepare a preview when browser tools are unavailable | The agent reports that visual inspection remains incomplete |
| Prepare a local draft for review | The workflow leaves the live site unchanged |
These are expected behaviors to test, not results from a benchmark.
Compare changes on the same practice tasks. If you shorten a description, check that the skill still matches the right requests. If you remove a step, confirm that the output still meets the requirement that step was protecting.
Investigate pauses before rewriting the rules
An unexpected pause may come from the task prompt, a skill, project guidance, or a tool permission. Identify the source before changing it.
You can ask:
Code:
Explain the action that is blocked.
If a written instruction requires this pause, identify
its source file and quote the relevant wording.
If a tool permission blocks the action, identify that
restriction instead.
Explain which remaining work can continue within the
current instructions and permissions.OpenAI's GPT-6 Astra instruction-following guidance recommends making the responsible skill and instruction visible when unclear guidance causes a pause.
For a broader review, use an audit prompt:
Code:
Review the task instructions, relevant skills, and
applicable AGENTS.md guidance for this workflow.
Look for unclear skill descriptions, conflicting rules,
unnecessary required reading, repeated checks, and
missing completion criteria.
For each finding, name the file and instruction, explain
the problem with a concrete task example, and suggest
replacement wording.
Preserve required checks, security controls, and intended
approval points. Propose edits for review before changing
these instruction files.This audit stops at proposed edits because changing shared instructions affects future tasks. That is a different stopping point from preparing a local article preview.
Start with one workflow you already repeat. Write the result you expect, move its reusable rules into a focused skill, and check it with a complete input, a missing input, and an unrelated request.
Video and references
My video tutorial covers seven ways to improve instructions for GPT-6 Astra in Codex. The full guide on my website includes more examples for prompts, skills, and
AGENTS.md.