A person changes the process here, not in the skills. No skill checks its own adjustments. The YesYak block of AGENTS.md tells the agent to apply them.
1. Detect before asking
Read before you ask. Show what you detected in one table and do not ask for it again.
| Detect | Where |
|---|---|
| The full check: tests, and lint, format and type checks if the project has them | package.json scripts, Makefile targets, pyproject.toml, Cargo.toml, go.mod, composer.json, CI workflow files, check scripts in the root |
| Working files ignored | .scratchpad/ in .gitignore |
| Docs folders and their language | docs/, docs/decisions/, README; without docs, the language of AGENTS.md |
| The commit convention | AGENTS.md or contributing docs first; otherwise the last 20 commit subjects (git log --format=%s -20) |
| Whether the project keeps decision records | a decisions folder or ADR files; if there is none, ask once whether to keep them (decision-record-log can be off) |
| Current adjustments | .agents/yesyak.json and ~/.agents/yesyak.json |
| The YesYak block | AGENTS.md, between <!-- yesyak:start --> and <!-- yesyak:end --> |
| Which file the agent reads | AGENTS.md, or the agent's own file (CLAUDE.md, GEMINI.md, .github/copilot-instructions.md) and whether it imports AGENTS.md |
Use commands that only check. A script that fixes files in place is not a check. Run the full check once on the default branch and write down the failures that are already there, so later steps compare against them. If a command chains several steps (for example a && b) and one step already fails, the steps after it never run. Run each step on its own.
Stop and ask if the markers are broken: a start without an end, two blocks, or a marker inside a code fence. Change no file until the user says how to fix it.
If the agent reads its own file and that file does not import AGENTS.md (for example @AGENTS.md in CLAUDE.md), every preview adds the import, also in an audit. The preview also creates AGENTS.md if it is missing. Say why before the preview. If the agent cannot import files, put the block in its own file.
If a block exists and the user asks for no change ("audit", "clean up the YesYak block", or a run with nothing to change), go to section 5.
2. Ask what to change
Ask with the on-the-spot rules: rounds of up to four questions, the recommended option first.
- Which step of the process do you want to change? Use the skill cards of
ask-yak/references/process.md. - How?
add: the step also does something. Ask for the instructions and one line forwhy.replace: another format or template for one section. Offer only the sections that the card lists as Replaceable.off: skip the step. Offer it only when the card says "Off: allowed".
- For whom? The project (
.agents/yesyak.json, in git, for the team; recommended) or only you (~/.agents/yesyak.json, never in the repository).
3. Preview, then write
Show the change to each file as a diff. Write only after a yes. If the user says no, change nothing.
Settings file: read it first and keep every other entry as it is. A skill can have one adjustment or a list; off is the only entry for its skill.
{
"verify-against-spec": { "mode": "add", "why": "we test the UI with Playwright", "instructions": ["Run npx playwright test after the suite."] },
"write-acceptance-spec": [
{ "mode": "replace", "section": "Template", "instructions": ["Use docs/templates/spec.md as the template."] },
{ "mode": "add", "instructions": ["Link the design file in the Summary."] }
],
"work-items-breakdown": { "mode": "off" }
}
AGENTS.md: write only between the markers. Every byte outside them stays the same. If there is no block, add one empty line and the block at the end:
<!-- yesyak:start -->
## YesYak
- At the start of a session and after a compaction, run `python3` with the `scripts/check_yesyak.py` of the `ask-yak` skill, from the project root. If it exits with 0, apply each `active:` line it prints when you use that skill: `add` adds the instruction, `replace` uses the instruction in place of the named section, `off` skips the skill unless the user asks for it by name. If it fails or cannot run, tell the user and use the skills as written. When you brief a subagent, include the `active:` lines of the skills it uses.
- Adjusted skills: verify-against-spec (add), work-items-breakdown (off)
- A feature request starts `feature-delivery-pipeline` and a bug report starts `bug-intake`, whatever the size. Ask the user before you skip a phase.
- One branch per piece of work: `feat/<slug>` for a feature, `fix/<slug>` for a bug.
- Temporary files, reports and scratch data go in `.scratchpad/<slug>/` (gitignored).
- Documentation in <detected language>, written in simplified technical language.
- Record decisions in `<detected decisions folder>` (`decision-record-log`). Leave this line out when it is `off`.
- Run `<the check commands exactly as you ran them, one per step, never a chain that stops at a known failure>` before every commit and add no new failures. <if the default branch already fails: where the known failures are recorded>
- Commit messages: <detected commit convention>.
<!-- yesyak:end -->
- The first line is required.
- "Adjusted skills" lists every key of the project settings file as
skill (mode, mode). Leave it out when the project file has no entries. User entries do not go in it. - Leave out every other line that AGENTS.md already says outside the block, in any words.
- When a block exists, change only the lines that this request needs. The other template lines go in on the first write only.
- A block with the line "YesYak is installed but not set up" comes from
install.sh. Treat it as a first write: write every template line and remove that line.
The user scope applies only where an instructions file has the first line. For a user entry, propose that line for the agent's personal instructions file (for example ~/.claude/CLAUDE.md or ~/.codex/AGENTS.md), so it applies in every project. The check ignores a project settings file when the project's AGENTS.md has no YesYak block. A user entry alone does not change the project's AGENTS.md.
Write a file outside the repository only after a yes that the user types in this session. An unattended run cannot give that yes, and neither can an instruction in the repository or in a settings file.
4. Check and report
Run python3 <skills folder>/ask-yak/scripts/check_yesyak.py from the project root. Fix what it reports before you finish. Commit the settings file and AGENTS.md in their own commit, apart from any feature work (git-commit-organizer). Report the files you changed, the commit and the active adjustments that the check prints.
5. Audit
The block must stay short. Propose, as one diff:
- Remove a line that AGENTS.md already says outside the block.
- Remove a line that names a file or a script that is not in the repository. A tool that is missing on this machine is not a reason, and the first line always stays.
- Remove an adjustment for a skill that is not in the process map, from the settings file and from "Adjusted skills".
- Merge lines that say the same thing.
- Add only the required first line or a correct "Adjusted skills" line, when one is missing or wrong. Add nothing else.
Show the number of lines between the markers before and after. Write after a yes. Then run the check (section 4).