Give the agent somewhere to look.
I’m building Agent Skills to put the judgment behind good engineering into instructions a coding agent can use. One question keeps the work concrete: what should an instruction make the agent do differently?
“Be careful with changes” gives the agent very little to work with. Where should it start? Which parts of the system matter? What would a careful change look like?
Follow one real operation
Clear Code asks the agent to start here:
Trace one representative operation from entry point to state change and effects.
That means following something the system actually does. Find where the request enters, which code makes the decision, what gets saved, and which other parts use the result.
The portfolio’s publishing flow is a small example. Saving a project creates a private draft. Publishing checks its fields and copies the draft into a public snapshot. The public pages read that snapshot. An edit stays private until it is published again.
If a project needs an overview before it has a public repository, the rule requiring an external link belongs in that publishing flow. The editor, private preview, and public page also need to handle a missing link. Following the operation tells the agent where to look before it starts changing files.
Turn the instruction into something you can check
For that change, the checks have a clear purpose:
- A saved draft stays private.
- An overview can be published without an external link.
- A supplied unsafe link is rejected.
- A failed publication leaves the previous public version intact.
Those checks describe behavior someone cares about. A passing build alone would leave several of these questions unanswered.
The instruction also needs a sensible limit. Tracing this publishing flow should lead to the relevant code and its callers. It shouldn’t turn a small change into a review of the entire application. Clear Code makes that scope explicit.
A skill is something to investigate
I want these skills to be easy to inspect and improve. A reader should be able to point to an instruction, explain the behavior it asks for, and decide whether that behavior helps with the task.
The next question is whether the agent follows it when it matters. A useful experiment would compare the same kind of change with and without the instruction, then inspect the decisions and missed checks. That would give me evidence for revising the skill.
For now, the collection is available to read and use. Start with a task you know well, choose a relevant skill, and look at what the agent actually does with it.