Choose a skill when you need a reusable way to do a task. Choose a hook when you need an action tied to an event. For a one-off request or a simple project rule, you may need neither.
Start with the job you need done
- A clear prompt
- Ask for one specific change. There is no recurring workflow to package.
- Project instructions
- Keep a stable rule, such as preserving existing URLs. The rule applies across tasks.
- A skill
- Follow the same review or writing method repeatedly. The task needs reusable steps and examples.
- A hook
- Run a check or add context when a supported event happens. The timing is part of the requirement.
- Both
- Supply an event-based reminder and follow a reusable method. The hook supplies the reminder; the skill supplies the method.
You can add the second tool later. Start with the one that solves the problem you actually have.
Use this prompt to choose your setup
Describe the recurring problem and where you use your agent. This asks for a recommendation before anything is installed or changed.
Help me choose the simplest setup for [task or recurring problem]. I use [agent product and environment]. The behaviour I want is [specific result]. It should happen [when needed or at a particular event]. Preserve [important constraints]. Compare a clear prompt, project instructions, a skill, a hook and a combination. Explain what each would do for this exact task. Recommend the smallest useful option and say why the others are unnecessary for now. Check current official documentation before naming supported events, paths or configuration fields. Ask about any missing detail that changes the choice. Do not install, edit or enable anything. Give me a proposed setup and one practical check that would show whether it works.
One code review, three different jobs
Suppose you want an assistant to review a change without editing the code. Here is what each part contributes.
On a narrow screen, scroll the table sideways to read every column.
| Part | What it contributes | What it does not do |
|---|---|---|
| Project instruction | “During a review, report findings before making changes.” | It does not define a complete review method. |
| Review skill | Read the diff, trace affected behaviour, check tests and report findings with file references. | It is not an event trigger that runs after every edit. |
| Prompt-submission hook | Add a reminder about review boundaries when a prompt is submitted. | It does not inspect the diff or guarantee that the skill is loaded. |
For most occasional reviews, start with the instruction and a clear request. Add a skill when you want the same method reused. Add a hook only when its timing is useful enough to justify the extra configuration.
What is a hook?
A hook runs a configured script or tool when a particular event happens.
For example:
- A user submits a prompt.
- The assistant is about to use a tool.
- A tool finishes running.
- A session starts.
- The assistant reaches the end of a turn.
The hook’s handler performs the configured action. Depending on the event and supported output, that action can add context, run a check, or block an operation. Codex hooks documentation
Think of a hook as this rule:
“When this event happens, run this action.”
A hook could launch a simple script or a more complex service. Its usefulness depends on what that script or service actually does.
What is a skill?
A skill is a reusable package of instructions, references, and optional scripts that guides an assistant through a type of work.
Think of a skill as:
“When doing this kind of task, follow this method.”
For example, a resource-writing skill could explain how to identify the audience, research claims, structure the article, and check the draft.
Skills can be explicitly requested or selected by the agent when the task matches their description. They are not guaranteed to run on every message. Official skills guide
Hooks and skills compared
On a narrow screen, scroll the table sideways to read every column.
| Question | Hook | Skill |
|---|---|---|
| What is its main purpose? | Connect an event to a configured action | Provide a reusable way to perform a task |
| What starts it? | A configured lifecycle event | An explicit request or the agent selecting it |
| What does it contain? | Configuration pointing to a script or tool | Instructions, references, and optional scripts |
| Where does the reasoning happen? | In the handler or any model it calls | In the assistant following the workflow |
| What is a good example? | Run a check before a tool executes | Follow a structured code-review process |
| Can it be useful alone? | Yes | Yes |
| Can they work together? | It can request skill use through added context; this is not a direct skill-invocation API | The agent loads and follows the skill when appropriate |
The distinction is about responsibility. A hook handles an event-driven action. A skill describes the working method.
Try a small review skill
In a local Codex project, create .agents/skills/focused-code-review/SKILL.md and paste the text below. Keep any existing skill with that name; choose a different name and folder if needed.
--- name: focused-code-review description: Review a requested code change for concrete defects and missing tests. Use for code-review requests, not implementation or general explanations. --- # Focused code review 1. Identify the requested diff and base revision. Ask if either is unclear. 2. Read the applicable project instructions and inspect the changed code. 3. Trace affected behaviour and check relevant tests. Do not modify files. 4. For each supported finding, give the file location, failure condition, consequence and evidence. Separate uncertainty from confirmed defects. 5. Return the findings in priority order, followed by checks performed and checks still needed. If you found no defects, say so without claiming that the change is guaranteed to be correct.
In Codex CLI or the IDE extension, select it with $focused-code-review and name the diff you want reviewed. In the desktop app, use the skill picker. If the new skill does not appear, restart Codex. These locations and invocation options follow the official skills guide.
Try it on a small diff you understand. Check that the review cites real locations and leaves the files unchanged. A useful test includes a known defect and a harmless change, so you can see whether the findings distinguish them.
Add a reminder hook only if you need one
This optional example is for local Codex in a Git repository on macOS or Linux, with Python 3 and Git installed. It adds context when you submit a prompt; it does not run a review, block commands or load a skill directly.
Show the hook files and setup
Create .codex/hooks/review_reminder.py in the repository. The script reads the event from standard input and returns a short reminder.
import json
import sys
def main():
try:
event = json.load(sys.stdin)
except (ValueError, UnicodeError):
return
if not isinstance(event, dict):
return
if event.get("hook_event_name") != "UserPromptSubmit":
return
print(json.dumps({
"hookSpecificOutput": {
"hookEventName": "UserPromptSubmit",
"additionalContext": (
"For code-review requests, inspect and report findings without "
"editing files. Use the focused-code-review skill if available "
"and applicable. For other tasks, follow the user's request."
)
}
}))
if __name__ == "__main__":
main()
Add the following to .codex/hooks.json. If that file already contains hooks, merge this entry into its hooks object instead of replacing the file. If you use inline hooks in config.toml, keep that representation rather than configuring the same handler twice.
{
"hooks": {
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "repo_root=$(git rev-parse --show-toplevel) && python3 \"$repo_root/.codex/hooks/review_reminder.py\"",
"timeout": 5
}
]
}
]
}
}Open the trusted repository in Codex CLI and use /hooks to review and trust the new hook definition. Changed definitions need review again. The configuration, trust steps and response fields are described in the Codex hooks documentation.
Submit a review request and check the hook activity before relying on it. This hook runs on every prompt submission and only phrases its reminder conditionally; it does not detect review intent. If that adds noise, a project instruction may be the better choice.
Five places hooks can help
Start with checks that belong at a specific event. These examples describe setups you would build.
Check a proposed command before it runs
Before a command runs, a checker can compare the proposed operation with a policy for protected directories. A supported blocking response can stop a matching operation.
The checker must handle the actual command semantics. Simple text matching can miss equivalent commands or reject harmless ones.
Run a focused check after a file changes
After a supported file-editing tool finishes, run a focused formatter check or linter and return its findings to the assistant.
Choose a check that fits the edit. Running the entire test suite after every change can slow the work unnecessarily.
Add an interpretation reminder when a prompt is submitted
When your requests are informal, add a reminder at prompt submission to identify the intended outcome and flag important ambiguity. For “make signup easier”, the assistant still needs to work out whether you mean fewer fields, clearer wording or another change.
In Codex, UserPromptSubmit adds context alongside the original message; it does not provide a direct replacement-message field. Prompt submission hooks
Load useful project context when a session starts
At session startup, load a current project summary so the assistant knows, for example, that a database migration is in progress.
Keep stable rules in a normal project instruction file; a hook is more useful when the context must be refreshed.
Check for missing validation before a turn finishes
At the end of a turn, inspect validation records and flag a required check that has not run.
Use actual records. The word “tested” does not establish which checks ran or what they proved.
Five places skills can help
Use a skill when the method is worth repeating. Open the other examples if they match your work.
Review code systematically
Read the intended change, trace affected behaviour, inspect relevant tests and report concrete defects with file locations and evidence.
A skill keeps the review method available across different changes. It still takes judgment to decide whether a finding is supported.
Turn a vague request into a clear working brief
For “the signup flow feels messy”, inspect the current flow, separate requirements from assumptions and identify what must stay unchanged. Ask a focused question only when the answer would change the work.
The output is a working brief grounded in the request, not an invented requirement to replace signup with Google login.
Write a resource article consistently
Reuse a method for identifying the audience, explaining unfamiliar terms, developing examples and checking factual claims.
The topic changes; the editorial checks stay consistent. The result is a draft with useful explanations and supporting sources.
Compare products using consistent criteria
Establish the requirements, compare each option against the same criteria and check current official information.
Keep unknowns visible. Tie the recommendation to the reader’s needs instead of choosing the product with the longest feature list.
Investigate a bug without guessing
Gather symptoms, try to reproduce the failure, inspect the relevant code and logs, then test possible explanations. Make a scoped repair only when authorised and recheck the affected behaviour.
Each step depends on what the investigation finds. The result may be a supported cause and repair, or a precise account of the evidence still missing.
Choose your next step
- One task — write a clear prompt and try it.
- A stable rule — put it in the project instructions.
- A repeated method — start with the small skill template and adapt it to your task.
- An event-based action — identify the supported event, then test a small handler such as the reminder hook.
- Both — keep their roles separate. The hook adds context at the chosen event; the agent loads and follows the skill when appropriate.
A hook can ask the agent to use a skill, but that is a request, not a direct skill-invocation API. For the review example above, first check whether the skill solves the problem on its own. Add the hook only if the reminder earns its place.