A2 — Make CLI agents follow the same method every time¶
← A1 — Safely complete your first CLI task · Track A: CLI Power User Stop 2 · Next: Stage 5 Track A core
This stop answers one question: How do you make a CLI agent remember the same way of working when it enters the same repo next time?
You will put rules that must always be known into Project instructions, turn frequently repeated steps into a Skill, and leave temporary tasks in a One-off prompt. It is like changing “explain everything again every day” into “the rules are on the wall, and the toolbox has an instruction card.”
🧩 Three Core Terms First¶
| Core term | What it is, in plain language | How A2 uses it | What it is not |
|---|---|---|---|
| Project instructions (project rules) | Rules you read every time you enter the workshop | Put the project purpose, forbidden actions, test commands, and delivery format here | Not one-off tasks or long reference material |
| Skill (reusable instruction card) | An instruction card you take out when needed | Put repeated review, release, and document-cleanup processes here | Not a universal path, permission set, or frontmatter format |
| One-off prompt (single-task prompt) | Instructions needed only today | Put this task’s scope, inputs, and success conditions here | Not a place to repeat project rules used every time |
📌 Learning Goals¶
- Use four fields to write short, clear project instructions.
- Turn a repeated review process into a read-only Skill.
- Tell apart what can be shared from filenames, permissions, and commands that must be adjusted for each tool.
Expand time, prerequisites, environment, and cost
- Time: Complete CLI-5 and CLI-6 first; CLI-7 and CLI-8 can wait, so you do not need to finish everything at once.
- Prerequisites: Complete A1, know how to use
git statusandgit diff, and have a secret-free, recoverable demo repo. - Environment: Choose one primary CLI agent. Claude Code, Codex, Gemini CLI, and OpenCode do not use exactly the same filenames; the comparison below shows the differences.
- Cost: Writing project-instructions files and Skills does not incur model charges; asking a CLI to test them may use quota or API tokens. Check the official usage/pricing page for the current date.
If you have not completed A1, go back and run “read-only inspection → view the plan → make a small change → git diff → restore” once.
📚 Required Reading¶
- First read the official project-instructions documentation for your primary tool: Codex uses
AGENTS.md, Claude Code usesCLAUDE.md, Gemini CLI usesGEMINI.md, and OpenCode usesAGENTS.md. - Then read your tool’s Skill documentation: Codex/ChatGPT, Claude Code, Gemini CLI, and OpenCode.
- Finally, revisit Stage 2 — Prompt Engineering and add the “task, scope, and success conditions” to your one-off prompt.
Expand the project-instructions and Skill locations for four CLIs
Official information checked on: 2026-08-30 UTC.
| Tool | Project instructions | Project Skill | What to note |
|---|---|---|---|
| Codex | AGENTS.md |
.agents/skills/<name>/SKILL.md |
Rules are layered by directory; the closer rule loads later |
| Claude Code | CLAUDE.md |
.claude/skills/<name>/SKILL.md |
Old .claude/commands/ remains compatible, but new workflows should prefer Skills |
| Gemini CLI | GEMINI.md |
.agents/skills/<name>/SKILL.md or .gemini/skills/… |
Skill activation asks for consent; do not put secrets in a Skill |
| OpenCode | AGENTS.md has priority; without it, use CLAUDE.md |
.opencode/skills/…, .agents/skills/…, or .claude/skills/… |
Check rules, skills, and permission settings first |
The common part is what you need to explain; filenames, search locations, permissions, and extra settings differ. Do not treat one tool’s special feature as something every CLI has.
🛠 Hands-on Exercises¶
Hands-on exercise CLI-5: Make a minimal project-rules card¶
Outcome: Every time the CLI agent enters the repo, it knows what the project does, what it must not touch, how to verify changes, and what to report when finished.
First choose the project-instructions file for your tool from the comparison above, then add these four things:
# Project rules
- Purpose: This is a practice documentation repo.
- Do not: Do not delete files, read secrets, or auto-commit or push.
- Verification: Run `git diff --check` after changes.
- Report: Explain what changed, the verification results, and what remains unhandled.
This card should contain only what must be known every time. Do not pack long tutorials, API references, or processes you use only occasionally into it.
Expand CLI-5 creation and verification steps
- Create your primary tool’s project-instructions file in a clean demo repo. Run
git status --shortfirst so you do not overwrite someone else’s unfinished changes. - Replace the four fields above with real content for this demo repo. Commands must be copyable; do not write vague instructions such as “fix the formatting” when success cannot be checked.
- Open a new CLI session and ask it to read only the rules and restate them in its own words. If it cannot find the file, check the official filename and loading scope first.
- Give it a test that touches a forbidden action, such as “commit this change directly.” The correct result is for the agent to stop or ask first, not commit by itself.
- Run
git status --short -- <rules-file-path>first to see whether the rules file is old or new. - Existing file: inspect it with
git diff -- <rules-file-path>. Usegit restore -- <rules-file-path>only if that exact file was clean before the exercise. - New file: Git shows
??;git restorecannot remove it. You may keep it as the exercise result. To discard it, verify the full path, delete only that file with your file manager, and rungit status --short -- <rules-file-path>again.
No line count can guarantee that rules are good. Keep only content that changes behavior; move a section used only for a specific task into a Skill or another on-demand document.
Hands-on exercise CLI-6: Turn a repeated review into a Skill¶
Outcome: You can ask the agent to run the same read-only review and output PASS or concrete problems without committing, pushing, or deploying by itself.
Claude Code uses .claude/skills/review-changes/SKILL.md; Codex, Gemini CLI, and OpenCode can use .agents/skills/review-changes/SKILL.md. After creating the file, put in:
---
name: review-changes
description: Review the current git diff and report concrete risks. Use when the user asks to review local changes.
---
1. Read `git diff --no-ext-diff HEAD` without changing files.
2. Check for secrets, unsafe commands, broken links, and missing verification.
3. Report `PASS` when no problem is found; otherwise list each problem with its file and reason.
4. Do not edit, commit, push, deploy, or send messages.
name is the instruction-card name; description tells the agent when to take the card. The body is the set of steps to follow.
Expand CLI-6 testing, permissions, and compatibility notes
- Read
SKILL.mdall the way through first, confirming that it does not download unfamiliar programs, read secrets, or change external systems. - Make a small documentation change in the demo repo, but do not commit it. Ask the agent to “review my local changes” and observe whether it finds the Skill; you can also enable it manually according to the tool’s documentation.
- Compare the report with
git diff. Rungit status --shortafter testing to confirm that the Skill did not quietly change files. - To share one Skill across multiple CLIs, share the core content above first, then adjust the folders, permissions, and tool-specific frontmatter for each tool. Unknown fields may be ignored; do not assume every setting is valid everywhere.
Claude Code’s .claude/commands/<name>.md can still create a same-named /name, but Skills already include custom commands and support attached files and on-demand loading. This tutorial uses Skills; understand legacy commands only when maintaining an older project.
Hands-on exercise CLI-7: Break a large task into visible small steps¶
Outcome: You can split a recoverable documentation task into “inventory → plan → modify → verify,” with a visible result at each step.
Expand CLI-7 comparison exercise and multi-agent extension
Choose a small task, such as “add the same run command to two README files.” The first time, ask the agent for a plan without changing files; the second time, ask it to inventory the two files, list the differences, make the change, run git diff --check, and report what remains unhandled.
When comparing the two results, ask only: Were any files missed? Can the changes be recovered? Did verification actually run? Do not assign every small step to a different agent just to make the process look impressive. If tasks must wait for one another, touch the same batch of files, or have unclear success conditions, start with a single agent.
The complete subagent, agent team, background-work, and review processes are in Stage 5.5. A2 only practices making the work clear.
Hands-on exercise CLI-8: Make a portable prompt comparison card¶
Outcome: You can keep the same task core while clearly marking which filenames, permissions, commands, and activation methods must change when you switch tools.
Expand CLI-8 cross-tool testing steps
- Put only four fields in the shared core: task, scope, forbidden actions, and success conditions.
- Run it once in a clean demo repo with the first CLI, recording the CLI version, model/provider, permission settings, and
git diff. - Restore the changes, then switch to the second CLI. Do not let two file-writing sessions operate on the same directory at the same time.
- Also record the differences: project-instructions filename, Skill location, shell/sandbox permissions, tool names, login, and cost.
“Portable” means the core meaning is easy to carry over; it does not mean the whole text and settings can be copied without changes. If the second tool has no same-named feature, return to the success conditions and choose a method it actually supports.
🎯 Curated Projects¶
The resources below are divided into five groups by purpose. Each group shows its category only once so repeated text does not stretch the table.
| Type | Resource | What to look at first | When it is useful | Rating | Source |
|---|---|---|---|---|---|
| Official project instructions | Codex AGENTS.md | Layered loading and precedence | Writing repo rules for Codex | ⭐⭐⭐⭐⭐ | Official docs |
Claude Code CLAUDE.md | When to put something in rules and when to move it to a Skill | Writing persistent rules for Claude Code | ⭐⭐⭐⭐⭐ | Official docs | |
Gemini CLI GEMINI.md | Directory scope and loading method | Adding project context for Gemini CLI | ⭐⭐⭐⭐⭐ | Official docs | |
OpenCode AGENTS.md | Rules loading, merging, and fallback | Writing rules for OpenCode | ⭐⭐⭐⭐⭐ | Official docs | |
| Official Skill docs | Codex/ChatGPT Build skills | SKILL.md structure and loading location | Making a reusable Codex process | ⭐⭐⭐⭐⭐ | Official docs |
| Claude Code Skills | On-demand loading, legacy commands, and permissions | Making a Claude Code Skill | ⭐⭐⭐⭐⭐ | Official docs | |
| Gemini CLI Agent Skills | Discovery, installation consent, and activation consent | Managing Gemini CLI Skills | ⭐⭐⭐⭐⭐ | Official docs | |
| OpenCode Agent Skills | Supported locations, frontmatter, and permission | Making an OpenCode Skill | ⭐⭐⭐⭐⭐ | Official docs | |
| Standards and readable examples | Agent Skills specification | Minimum requirements for a shared format | Making the core content easier to carry across tools | ⭐⭐⭐⭐ | Standard |
anthropics/claude-plugins-official | Skills and commands inside official plugins | Seeing how a Skill is packaged for sharing | ⭐⭐⭐⭐⭐ | GitHub repo | |
mattpocock/skills | Short Skill examples used in engineering work | Comparing different writing styles | ⭐⭐⭐⭐ | GitHub repo | |
obra/superpowers | How real workflows are split into Skills | After completing your first Skill | ⭐⭐⭐⭐ | GitHub repo | |
| Indexes and prompt practice | hesreallyhim/awesome-claude-code | Finding Claude Code resources by type | When you know the need and want more examples | ⭐⭐⭐ | GitHub repo |
anthropics/prompt-eng-interactive-tutorial | Comparing prompt approaches step by step | When the shared core in CLI-8 is unclear | ⭐⭐⭐⭐ | Official GitHub repo | |
| Repo context tools | yamadashy/repomix | Creating a one-off codebase snapshot | When you need to organize repo contents for an agent | ⭐⭐⭐⭐⭐ | GitHub repo |
langchain-ai/openwiki | Creating a continuously updated repo wiki | When a large repo needs on-demand document lookup | ⭐⭐⭐⭐ | GitHub repo |
✅ Self-check before Stage 5¶
- I can distinguish project instructions, Skill, and one-off prompt in my own words.
- My project-rules card states the purpose, forbidden actions, verification command, and delivery format, and the agent can read it.
- My review Skill reads changes only; after testing,
git status --shortshows no unexpected modifications. - I know that a “shared core” does not mean every CLI has the same filenames and permissions.
Once all four are done, go to the Stage 5 Track A core, read 5.1–5.4, then continue to A3. If not, return to the demo repo and repeat CLI-5 or CLI-6; you do not need to read every supplement first.
Expand common questions and fixes
- The rules are long, but the agent still misses them: Delete background stories and repeated sentences first, keeping only observable behavior. Safety checks that must run every time should use the tool’s hook/policy instead of relying only on text reminders.
- The Skill does not appear: Check the folder, the capitalization of
SKILL.md, YAML frontmatter, and the locations supported by the tool, then reload or reopen the session according to the official method. - The Skill performs a dangerous action by itself: Change deploy, send, commit, and push to actions that users must explicitly enable, and test with a read-only version first. Read all third-party Skill content and scripts before using it.
- The same Skill breaks in another CLI: Keep the shared goal and steps, then compare the frontmatter, permissions, and tool names recognized by that tool; do not guess.
- There is too much project information: Treat project instructions as a map only; put details in
docs/, the Skill’sreferences/, or another on-demand document. Longer rules are not automatically more reliable.
Safety baseline: Rules and Skills are text instructions, not absolute protection. Do not put API keys, tokens, or personal data in them. Any workflow that writes files, commits, pushes, deploys, or calls an external service needs a visible permission boundary and verification steps.