When I wrote Why I’m Adding Engineering Skills to My AI Workflow, I was starting with a small selection of reusable engineering instructions. I wanted to see whether making my expectations explicit would improve the work an AI agent produced.
Since then, I’ve been using skills extensively across my projects, working heavily with both Claude Code and Codex. This personal site has become one of the places where I’ve developed the setup furthest, with project-specific workflows, framework skills and specialist reviewer briefs.
My experience has been a substantial improvement in code quality, clearer expectations and more consistent results. I’m happier with the work agents produce. That is an observation from using them, rather than a controlled comparison that isolates skills from changes in models, tools or my own prompting.
The most useful lesson has been how much the instructions themselves need to change once you put them to work.
Better expectations make better results
A request to review a change can produce very different answers. One agent might focus on naming. Another might suggest a larger refactor. A third might report that the tests pass without checking whether they cover the behaviour that changed.
I now have a much more concrete expectation for that review: trace the affected behaviour, identify actionable problems, explain their impact and separate verified defects from missing evidence or optional improvements.
The same applies to implementation. “Keep this focused” becomes more useful when the project explains which contracts must remain intact, where the relevant code lives and what checks are appropriate. “Verify it” needs to distinguish compilation, automated tests and actually using the interface in a browser.
Those expectations are easier to reuse when they live alongside the code. I can revise them after a disappointing result instead of relying on another reminder in the next conversation.
That consistency is the biggest improvement for me. There is a clearer shared understanding of what good work looks like and what needs to happen before calling it finished. I still review the result; the instructions give that review a better starting point.
Addy’s skills were the starting point
I originally drew from Addy Osmani’s engineering skills. They gave me useful approaches to debugging, reviews, performance investigation and other recurring work.
They are general workflows, though. They cannot know this repository’s architecture, design decisions, test setup or constraints. Every skill I adopt needs an individual review and adaptation to the project where it will run.
On this site, that has meant replacing generic examples with the actual validation commands, removing database guidance that has no application here, and spelling out which rendering and interaction behaviours must survive a refactor. A component-size rule also needed judgement about cohesion and readability rather than a fixed line count.
The adaptation goes beyond substituting a package-manager command. A skill needs to explain when it applies, when it does not, what evidence it should produce and where its authority ends. A debugging workflow should help investigate a failure without turning a small fix into an unrelated redesign.
I keep the upstream attribution and revision so I can review future changes. I also preserve the local decisions. Updating a skill by overwriting those decisions would throw away much of the value I’ve added.
How the setup has grown on this site
The original six skills now sit within a broader setup. I’ve added guidance for checking uncertain framework behaviour against installed source and documentation, writing readable code, producing project imagery and reviewing changes before a merge. There are also official Next.js workflows for runtime checks, caching, prefetching and bundle analysis.
The responsibilities are deliberately separated:
AGENTS.mddescribes the project’s conventions and points to relevant workflows.- Skills describe how to carry out a particular kind of work.
- Reviewer briefs define focused checks for code, security, testing, accessibility and performance.
The reviewer briefs are instructions for delegated reviews, rather than agents that run automatically on every task. The pre-merge workflow coordinates the applicable reviews and brings their findings together. A copy edit should not need the same process as a rendering change.
The recent bundle work is a concrete example. Using the Next.js bundle optimizer workflow, the agent captured a baseline, investigated imports, made focused changes and compared the resulting bundles. We split unrelated interactive controls into separate client modules and used a smaller Motion entry point for title animations.
The combined changes reduced analyzer-attributed compressed client JavaScript by about 34 kB on Contact and 19 kB on the homepage. Those are build measurements, not measured download savings or proof of faster loading. The changes also went through tests and desktop/mobile browser checks to verify the interactions and animations.
That is the kind of result I want from a performance skill: a specific improvement with evidence and clearly stated limits.
Token usage can go in either direction
In some tasks, I’ve found token usage lower. A more direct approach and fewer rounds of correction can mean less work overall. In others, usage goes up as the agent reads more instructions and supporting references or performs a more thorough review.
There is an important distinction between having skills installed and loading their contents. OpenAI’s skills documentation describes progressive disclosure: Codex starts with skill names and descriptions, then reads the full instructions for skills it selects. Anthropic’s Claude Code documentation describes the same principle of loading a skill’s body when it is used. In both tools, installing a collection does not mean every full skill is included in every task.
Once instructions and references are read into context, they add to what the agent processes. A skill that sends the agent through several long documents can therefore add overhead. Merely linking to those documents is not the same as loading them.
Whether that overhead is offset by fewer retries depends on the task. I haven’t run a controlled token benchmark, so I wouldn’t attach a percentage saving to the setup or promise that skills make every request cheaper.
I care more about the cost of reaching a result I can accept than the size of the first prompt. Still, extra process needs to earn its place. Clear activation criteria and references loaded only when relevant help keep a small task small.
Skills need maintenance too
Frameworks change, and instructions based on an earlier version can become misleading. Test commands change. A migration finishes. A workflow that was useful during adoption may become excessive for routine maintenance.
I’ve already adjusted this site’s skills as the project evolved. The cache and prefetch adoption workflows now distinguish an initial migration from a focused change after adoption. Verification guidance follows the current tools. Reviewer instructions point to the bundle workflow when the change actually affects client JavaScript.
Framework teams are also publishing their own skills. The Next.js team’s bundle optimizer announcement is a useful example: the workflow connects the agent to framework tooling and import-graph evidence that a generic performance checklist cannot supply on its own.
Official guidance still needs local integration. I check the framework version, available tools and assumptions about the workflow before adopting it. Then I decide how it fits the project’s existing instructions, rather than leaving two competing procedures for the same task.
What I’ll keep doing
I’ll keep turning recurring corrections into clearer project guidance, and reviewing that guidance when the project changes. I’ll also keep removing instructions that duplicate other rules or add work without improving the result.
Skills have become a regular part of how I work with AI agents because the results have been better and more consistent. The useful part is the engineering judgement captured in them: what matters here, how to investigate it and what evidence is enough. Maintaining that judgement takes work, but it has been worth it.