Install the align skill and choose which records to review. Your agent reads conversation logs, commits, and PR comment threads, saves the preferences you confirm in ALIGNS.md, and uses them in future work.
Say “That’s not what I meant” or “The goal or loop went wrong.” Your agent uses align to find the mismatch and ask what needs clarifying.
Automatic skill invocation depends on your agent and project setup.
How it worksModel developers train for broad goals such as helpfulness and safety. Your project still has its own choices: move fast or keep things simple, experiment or change as little as possible. Here, alignment means agreeing on those priorities and checking the work against them. ALIGNS.md records that agreement; it does not retrain the model.
The criteria you agree on carry over to the next task. Your agent uses the preferences it already knows, so you spend less time explaining how you want things done or making each choice yourself.
When a result misses what you had in mind, revise the criteria together and use them in the next task.
Read the protocol and resultsFewer additional replies is better.
Four profiles, each completing three tasks. Counts are pooled across profiles.
| Condition | Workshop | Guide | Demo |
|---|---|---|---|
| Generic instructions only | 4 | 7 | 9 |
| ALIGNS.md + align skill (saved preferences) | 0 | 0 | 0 |
Your agent won't know every preference unless you tell it. Explain what you want to achieve, what comes first, and where you're willing to compromise. Include the limits it needs to respect.
Keep these expectations in ALIGNS.md so the agent can refer to them while it works. That gives you less to explain again and fewer misunderstandings to correct.
“Prefer the simplest solution I can maintain. Add complexity only when the benefit is clear.”
What you want can change as the project takes shape. A separate file makes the current agreement easy to find and revise without mixing it into setup details or working instructions.
Connect ALIGNS.md through your main client’s instructions, such as AGENTS.md or CLAUDE.md. The skill maintains the method; your file keeps the current agreement.
As it works, the agent compares its choices with ALIGNS.md. It can correct a mismatch on its own when the correction stays within what you agreed.
Return to the skill when an important decision misses your intent, the same correction keeps coming up, or you are unsure what to do next. Revisit the open question, without starting the whole interview again.
“This adds complexity beyond our agreement. Is that a one-time exception, or has your priority changed?”
This is the practice of self-alignment: checking the work against your expectations. The agent must not rewrite the agreement to excuse its own choices.
Say you're building a small tool for your team. Choose what matters most and see how it could change the agent's approach.
“Prefer tools I already know and can maintain.”
One way to act on itUse the existing stack and build the essential workflow with fewer dependencies.
The skill checks your primary CLI and existing instructions. It connects ALIGNS.md without replacing distinct rules or creating competing copies of the skill.
For a new project, clarify what you want before implementation. For existing work, check what still fits. Save the agreed criteria and the way to call the skill in ALIGNS.md. With brief requests, use existing context first and ask about gaps that would materially change the result. Agree on when to ask; save only confirmed lasting preferences.
Review consequential drift and unresolved choices. Before a long autonomous run, try a few hypothetical decisions together. Fix clear errors directly; keep settled questions settled.
Use supported automatic updates or an agreed refresh when alignment starts. Updating the skill does not change your criteria or confirmation date. Keep current criteria in ALIGNS.md and use Git for history when available.
Write down the expectations that affect decisions, along with why they matter.
A sample agreement.
# Project Alignment
## Purpose
Make a small tool our team can maintain.
## Priorities
Clarity before flexibility.
Reuse familiar tools before adding new ones.
## Decision boundaries
Make reversible changes within this scope.
Ask when a trade-off changes our priorities.
Use project context before asking for more detail.
## Things to avoid
Speculative features and unnecessary complexity.
## Revisit alignment
Client: Codex. Instructions: AGENTS.md.
Use $align to review an important mismatch.
Update policy: [agreed at setup]
Last aligned: [user-confirmed date and time]Copy the installation request to your agent. It installs the maintained skill, connects your project, and sets up supported updates. New and existing projects both work.
npx skills add hmmhmmhm/aligns.md --skill alignOnce set up, ask: “Use align. That decision was different from what I meant.”
Update and activation support depends on your client. The setup records what is actually enabled.
Keep the decisions your team agrees on in code reviews and agent conversations. With the context and reasons for each correction, they can become examples for fine-tuning your coding agent.
Use option 8 to collect examples. Submit selected batches manually at an agreed cadence. Export the examples a team reviewer approves against your shared criteria.
Collect and export with ALIGNS.md. Your team chooses how to train and evaluates the result.
Shared deliberately. Reviewed together.