From Prompt Writer to Skill and Workflow Designer

After prompt engineering: installing a working method into AI coding agents

AI coding agents have a strange kind of speed.

You ask for a feature. They inspect files, edit code, add a test or two, and say they’re done. The first time this happens, it feels like a productivity jump. Then you open the PR.

The requirement is still fuzzy.
The assumptions are buried in the code.
The tests mostly cover the happy path.
The diff is wider than expected.
The final answer says "completed", but there isn't much evidence to review.

The problem usually isn’t that the agent can’t write code. It writes code too soon. A decent engineer slows down before implementation. They ask what counts as done. They make the boundary explicit. They write down what they’re assuming. They decide what test would prove the change works.

Most agents skip that work unless we force them through it.

That’s why Addy Osmani’s agent-skills repo is interesting. It’s a skill pack for AI coding agents built around production-grade engineering habits. The README frames the workflow around DEFINE, PLAN, BUILD, VERIFY, REVIEW, and SHIP. The point is simple enough: don’t rely on a longer prompt when what you actually need is a repeatable way of working.

The question I wanted to test was narrow.

Can I change the agent’s first reaction by installing an engineering workflow, not by writing another clever prompt?

Prompts give instructions. Skills give procedures.

Most prompt engineering starts as a sentence.

Write tests too.
Be careful.
Make it production-grade.
Think about edge cases.

Those are reasonable instructions. They’re also easy to satisfy rhetorically. An agent can say it considered edge cases. It can say it tested the change. It can call something production-ready.

That doesn’t mean it followed a reliable sequence.

A skill is a different unit. In Addy’s getting-started guide, a skill is a SKILL.md file that describes an engineering workflow. When the agent loads it into context, it gets workflow steps, verification steps, common rationalizations to avoid, and exit criteria.

I read the distinction like this.

prompt = an instruction for this conversation
rule = a constraint that keeps applying
skill = a procedure for a specific kind of work
workflow = several skills connected into a development path

That distinction matters. A prompt lives in the chat. A skill lives in the project. A prompt asks the agent to do better this time. A skill gives the agent a gate it has to pass.

For coding agents, the better question is not “How do I write a perfect prompt?”

The better question is “What procedure should the agent be unable to skip?”

• The first failure is often before the first line of code

When people talk about AI coding agents, they usually talk about implementation quality. That makes sense, but it misses an earlier failure mode.

The agent often starts coding before the task is stable.

Say I ask for this:

Add full-text search to this tiny markdown notes project.

A plain agent will probably inspect the project and start wiring up search. It may find where notes are stored, add a string match, return an array of results, and move on.

A human engineer would likely pause first.

Should search cover titles, filenames, body text, or all three?
Should matching be case-sensitive?
Do results need ranking, or is a simple contains match enough?
Should the project build an index, or scan files on every search?
Is this a UI feature, a CLI feature, or an API feature?
Can we add a dependency?
What should happen for an empty query?
What should happen when there are no results?

None of those questions show up directly in the diff. Still, they shape the diff.

If they’re skipped, the implementation becomes a guess.

• The workflow unit is the gate

The workflow I want from an agent is boring on purpose.

idea
 ↓
discovery skill
 ↓
assumption map
 ↓
spec skill
 ↓
implementation plan
 ↓
build skill
 ↓
test skill
 ↓
review gate
 ↓
ship note

The order matters.

No spec, no build. No assumptions, no plan. No negative test, no review. No test output, no “done.”

That sounds strict until you’ve reviewed enough agent PRs. Then it sounds like basic hygiene.

The useful unit is the gate.

spec gate
test gate
review gate
ship gate

Once these gates exist, the agent stops behaving like a code generator and starts behaving more like a process runner.

• Trying Addy Osmani’s agent-skills in a small repo

I didn’t want to invent a toy skill and then claim victory. I wanted to use a real repo with a lot of attention from working developers.

So I cloned Addy’s agent-skills repo and copied three skills into a small demo project.

The official quick start first shows the Claude Code plugin path:

/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills

That’s the cleanest route if you’re using Claude Code.

I was testing with Codex, so I used the Markdown files directly. Addy’s own post says the skills are plain Markdown with frontmatter, and that tools like Codex, Aider, Windsurf, OpenCode, or anything that can accept a system prompt can still read them.

Here’s the setup I used.

git clone - depth 1 https://github.com/addyosmani/agent-skills.git /tmp/agent-skills

mkdir -p /tmp/addy-skills-demo/.agents/skills

cp -R /tmp/agent-skills/skills/spec-driven-development \
 /tmp/addy-skills-demo/.agents/skills/

cp -R /tmp/agent-skills/skills/test-driven-development \
 /tmp/addy-skills-demo/.agents/skills/

cp -R /tmp/agent-skills/skills/code-review-and-quality \
 /tmp/addy-skills-demo/.agents/skills/

I started with those three because the getting-started guide recommends them as the minimal setup:

spec-driven-development = define what to build
test-driven-development = prove it works
code-review-and-quality = verify quality before merge

That trio covers the gaps I see most often in AI-assisted coding: unclear scope, weak evidence, and shallow review.

After copying the files, the project had this shape.

/tmp/addy-skills-demo
└── .agents
 └── skills
 ├── spec-driven-development
 │ └── SKILL.md
 ├── test-driven-development
 │ └── SKILL.md
 └── code-review-and-quality
 └── SKILL.md

The file copy is the least interesting part. The real question is whether the agent actually reads the skill as a workflow.

So I ran Codex in read-only mode. No file edits. No implementation. I only asked it to use the spec-driven-development skill and show what it would surface before coding.

codex exec \
 - cd /tmp/addy-skills-demo \
 - sandbox read-only \
 - ephemeral \
 'Use the spec-driven-development skill. Do not edit files. For a feature request "add full-text search to this tiny markdown notes project", show only the assumptions you would surface before coding and the gate you would require before implementation.'

That small constraint matters. If the agent modifies files, it’s already past the point I want to observe. I wanted the first reaction.

• The first reaction changed

With a plain prompt, the agent usually starts like this:

I'll inspect the project structure, 
find where notes are stored, then implement search.

That response isn’t bad. It’s just already leaning into implementation.

With spec-driven-development loaded, the response shifted. The agent stopped at assumptions and a gate.

Assumptions:
1. Search runs locally over existing markdown notes.
2. Search covers title, filename, and body text.
3. Results are case-insensitive.
4. Basic relevance ranking is enough.
5. No new dependency unless built-in matching is insufficient.
Gate Before Implementation:
Do not implement until the user approves a short spec with concrete success criteria.

That’s the behavior I wanted.

The search algorithm didn’t improve yet. No code had been written. The useful change happened earlier: the agent exposed its assumptions before turning them into implementation.

That’s where skills earn their keep. They move hidden judgment into reviewable text.

• Reading the skill pack as a workflow system

Addy’s repo shouldn’t be read as a folder of prompt snippets. The README describes a lifecycle, and the commands map cleanly to that lifecycle.

The command set includes:

/spec = write the spec before code
/plan = break work into small tasks
/build = implement one slice at a time
/test = use tests as proof
/review = check quality before merge
/code-simplify = prefer clarity over cleverness
/ship = prepare the change for release

The getting-started guide also maps commands to skills. For example, /spec invokes spec-driven-development, /test invokes test-driven-development, and /review invokes code-review-and-quality.

A typical skill file has a structure like this.

- -
name: spec-driven-development
description: Creates specs before coding…
 - -
Overview
When to Use
Gated Workflow
Common Rationalizations
Red Flags
Verification

The best parts are not the nice wording. The best parts are the uncomfortable sections.

Common Rationalizations matters because agents rationalize shortcuts. Red Flags matters because agents often miss warning signs. Verification matters because “looks right” is not evidence.

This is the part I would copy into my own agent setup first. Not the prose. The gates.

• Loading fewer skills is part of the discipline

There’s a temptation to load the whole skill pack into context and hope the agent becomes a senior engineer. That’s usually the wrong move.

Addy’s getting-started guide says to load skills selectively because more context isn’t always better. The docs also recommend starting with spec-driven-development for non-trivial work, always loading test-driven-development when writing code, and not skipping verification steps.

That matches what I’ve seen in practice.

Too little process and the agent rushes. Too much process and the agent gets noisy. The useful middle is a small set of gates tied to the task at hand.

For a small feature, I would start with three:

spec-driven-development
test-driven-development
code-review-and-quality

For security-sensitive work, I’d add the security skill.

For a UI-heavy task, I’d add the frontend or accessibility skill.

For a cleanup task, I’d use the simplification skill instead of dragging in the full lifecycle.

The point is to route the agent to the right procedure, not to drown it in every procedure.

• What changed in my mental model

Before this experiment, I treated agent instructions mostly as text. Better wording. Better constraints. Better examples.

After reading and trying agent-skills, I’m more interested in file-backed process.

A prompt can improve one session. A skill can improve a repository. A workflow can improve the way a team delegates work to agents.

That last part is the shift.

A team already has engineering habits, even if nobody writes them down. Keep PRs small. Explain the tradeoff. Add a negative test. Don’t change unrelated files. Show the command output. Don’t call it done without evidence.

When humans work together, those habits live in code review comments, onboarding conversations, and the senior engineer’s head.

When agents join the workflow, those habits need a different home.

SKILL.md is one practical place to put them.

• Prompt writer to workflow designer

The first wave of AI coding work was prompt-heavy. People wrote better instructions, gave the model a role, specified output formats, and added more reminders.

That still helps. I’m not throwing prompts away.

But prompts are too soft for production work by themselves. They don’t reliably carry team habits. They don’t create durable gates. They don’t leave a workflow behind in the repo.

Engineering habits need to be written down in a form the agent can execute.

PRs should stay small. The reason for the change should be visible. Tests should include failure cases. Security boundaries should be named. Completion should come with evidence.

“Be careful” won’t preserve those habits. A workflow might.

The old version of the job was writing better prompts.

The next version is designing the path an agent has to walk before it’s allowed to say done.

https://github.com/addyosmani/agent-skills “addyosmani/agent-skills” https://addyosmani.com/blog/agent-skills/ “Agent Skills — Addy Osmani”