Agent workflows & engineering practices
I turn project knowledge and engineering standards into repeatable AI workflows, with clear instructions, useful tools and evidence your team can review.
01 / Project instructions
Capture the expectations your team would explain to a new engineer: where to look, how to make a change and how to demonstrate that it works.
In Codex, project instructions can be layered from the repository root toward the working directory. More local guidance can refine the rules for a particular area.
Illustrative content. Replace paths and agreements with those used by your team.
# Project working agreements
## Context
- Read docs/architecture.md before changing module boundaries.
- Follow the existing API error format and validation patterns.
## Delivery
- Keep changes within the agreed task.
- Add checks for the behavior being changed.
- Run the relevant checks documented in CONTRIBUTING.md.
- Report changed behavior, check results and any unresolved risks.
## Escalation
- Ask before changing a public API contract or data schema.
- Leave production releases to the team's approval process.02 / Reusable procedures
Package recurring work into focused procedures: investigate an incident, review a change, add an endpoint or prepare release evidence.
A skill contains instructions with a name and description, plus optional scripts, references and assets. The description helps an agent choose when to use it; the full instructions are loaded when selected.
Define the trigger, inputs, steps, expected output and stopping conditions. Start with one task you can evaluate.
Official skill authoring guidance ↗Illustrative SKILL.md for a skill directory. Adapt it to your agent tool and repository.
---
name: api-change
description: Implement a scoped API endpoint change in this project. Use for endpoint behavior, validation and tests; exclude infrastructure changes and production releases.
---
1. Read the endpoint contract and the applicable project rules.
2. Find an existing endpoint with the same conventions.
3. Implement the smallest change that meets acceptance criteria.
4. Check success, invalid input and unauthorized access cases.
5. Run the relevant repository checks and inspect the diff.
6. Summarize the change and actual results; flag blocked checks.These examples use AGENTS.md and SKILL.md conventions supported by Codex. File discovery, precedence and available capabilities vary between agent tools; the implementation should match your environment.
03 / From request to evidence
Illustrative task: add an endpoint that lets an authorized user retrieve an order’s delivery status. The workflow connects the request to project standards and executable checks.
Agree the endpoint behavior and acceptance criteria.
Read the architecture, conventions and change boundaries.
Apply the procedure for a scoped API change.
Use repository tools to implement and run checks.
Inspect the diff, test evidence and unresolved questions.
A focused diff, an explanation of behavior, results for the relevant tests and an explicit list of anything unverified.
If the contract is ambiguous, access is missing or a schema change is needed, the agent surfaces the decision before continuing dependent work.
04 / Practices I apply
Instructions help direct the work. Reliable delivery also needs maintained context, enforced permissions and a way to judge the result.
Describe decisions, commands and boundaries the agent needs. Link to maintained documentation for deeper detail and remove conflicting rules.
Start with the relevant code, contracts and examples. Retrieve company knowledge when needed; treat retrieved content as evidence, not authority to change the task.
Use scoped credentials, sandbox boundaries and tool permissions. A sentence in AGENTS.md does not technically prevent an unauthorized action.
Use tests and acceptance criteria tied to changed behavior. Record what actually ran, what failed and what still needs human review.
Keep representative tasks, including cases where a skill should stay inactive. Compare task success, rework, time and cost as instructions evolve.
Version shared instructions and skills alongside code. Assign an owner and review them when architecture, tooling or team practices change.
For a practical approach to testing skill selection and outcomes, see OpenAI’s guide to evaluating agent skills.
05 / A useful first engagement
Bring a recurring task where agents need repeated correction or struggle to follow your project conventions. We define a focused pilot and how to judge it.
Scope, access and deliverables are agreed before work starts.
Discuss an agent workflow pilot ↗