Stop Repeating Prompts. Turn Them Into Skills.

Every AI coding team eventually builds a private prompt graveyard.

It starts innocently. One engineer writes a good instruction for code review. Another writes a better one for test generation. Someone has a migration prompt, a bug triage prompt, a release notes prompt, a "please follow our design system this time" prompt, and a long paragraph they paste into every agent session because the agent keeps making the same mistake.

For a while, this feels like leverage. Then it becomes drag.

The prompts live in GitHub, Slack, Notion, personal notes, old chats, local shell aliases, and memory. Nobody knows which version is current. Nobody reviews changes. Nobody can tell whether the prompt works across tools. The best workflow on the team belongs to whichever engineer remembers the magic paragraph.

That is not team infrastructure.

Skills are the next step. Skills matter because they give teams a way to package repeatable agent work as versioned, inspectable, portable assets.

A good skill is not a clever prompt. It is a small operating procedure for an agent. It says when the procedure applies, what to read, which steps to follow, which scripts or templates to use, where output belongs, and what evidence proves completion.

The progression: prompt, checklist, skill, operating system

Most teams do not need to start with a formal skill. They need to notice repetition.

The first signal is a repeated prompt. You catch yourself typing the same instruction three times:

That is useful, but it is still fragile. It depends on the person remembering it. It may omit a step next time. It is hard to diff. It is hard to review. It is hard to share outside the tool where it was written.

The second stage is a checklist. The repeated instruction becomes explicit:

Now the work is clearer. A human can review it. A teammate can improve it. But the checklist still sits beside the workflow. Someone has to remember to paste it or point the agent at it.

The third stage is a skill. The checklist becomes an agent-loadable procedure with metadata:

The skill has a name and description so an agent can recognize when it applies. It has instructions precise enough to guide the work, examples loaded only when needed, and scripts that produce mechanical evidence. It is no longer a private snippet. It is a reusable asset.

The fourth stage is a team operating system. Skills connect to repository context, review gates, CI, release workflows, and ownership. The database migration skill is not alone. It sits beside code review, incident writeup, API design, frontend QA, security review, eval design, and release note skills. Each skill handles a coherent unit of repeatable work. The repository's context files route agents to the right skill and the right source material.

That is the practical maturity curve:

This is the difference between individual productivity and organizational capability. A prompt helps one person move faster. A skill helps the team standardize a class of work.

What belongs in a skill

A skill should package procedural knowledge that is reusable, bounded, and easy to recognize.

First, the task repeats. If you only do something once, a skill is overhead. If three engineers keep asking agents to perform the same class of work, the pattern is ready to capture.

Second, the task has team-specific judgment. "Write tests" is too generic. "Write tests for our Next.js server actions using the local fixture builders, with regression coverage for auth and cache invalidation" is team infrastructure.

Third, the task benefits from a consistent process. Code review, database migrations, API client generation, security triage, design QA, release notes, customer bug reproduction, eval writing, and incident summaries are all good candidates because skipped steps create real cost.

A skill should contain what the agent would not reliably know otherwise:

• Team conventions.
• Required files and routing rules.
• Fragile sequences that must happen in order.
• Known failure modes.
• Examples of accepted output.
• Scripts or commands that verify the work.
• Boundaries around what not to do.

It should not become a dumping ground for everything related to the topic. Agents already know general concepts. They do not need a lecture on what a database migration is. They need the team's migration rules, the dangerous edge cases, the exact verification command, and the definition of done.

The strongest skills are closer to runbooks than essays. They give the agent a procedure, not a philosophy.

What belongs in context files instead

Skills and context files solve different problems.

Context files are routing infrastructure. They tell the agent where it is, what matters in this part of the repository, which documents must be read, which files should be skipped, and what local standards apply. In the Geist Labs model, files like `AGENTS.md` and `CONTEXT.md` define the operating environment.

Skills are execution infrastructure. They tell the agent how to perform a repeatable class of work once the task has been identified.

Use a context file when the instruction is location-specific or always relevant inside a workspace:

• "Before working in `apps/frontend`, read the design system notes."
• "Use `pnpm` in this repository."
• "Draft blog content belongs in `content/blogs/drafts`."
• "Do not inspect archived strategy files unless explicitly asked."
• "Verification evidence must be included before claiming completion."

Use a skill when the instruction is task-specific and reusable across locations:

• "Perform a production incident writeup."
• "Review a pull request for auth and data access risks."
• "Create a regression test from a bug report."
• "Generate a customer-facing changelog from merged commits."
• "Convert a repeated support issue into an eval case."

The boundary matters because global context is expensive. Every instruction loaded on every task competes with the actual work. If a database migration procedure lives in root instructions, the agent sees it while drafting a blog post, editing a homepage, or reviewing CSS. That is context bloat.

A well-designed system routes from stable context to task skill:

This is progressive disclosure as an engineering discipline. Load the small index first. Load the procedure when relevant. Load deep references only when the task needs them.

Skills make agent work portable

Tool-specific prompts are a weak asset. They depend on one chat surface, one memory system, one model behavior, and one person's habits.

Skills are more durable because they are filesystem-native. The emerging format is intentionally simple: a directory with a `SKILL.md` file, plus optional `references/`, `scripts/`, and `assets/`. The important idea is not the folder names themselves. The important idea is that the procedure is a normal artifact that can live in version control.

That changes the ownership model.

A prompt snippet is usually personal. A skill can have code owners.

A prompt snippet is copied by hand. A skill can be installed, updated, reviewed, and tested.

A prompt snippet is hard to compare. A skill can have versions.

A prompt snippet usually lacks evidence. A skill can include verification commands and eval cases.

A prompt snippet is often tied to one tool. A skill can be adapted across skills-compatible agents and, even when exact compatibility differs, the core procedure remains readable Markdown.

This is why skills are team infrastructure. They turn agent behavior into something closer to code: stored in the repository, changed through review, improved from incidents, and reused across environments.

The portability point is not that every tool will interpret every skill identically. They will not. Tooling differences matter. Some clients support automatic activation. Some support slash invocation. Some support bundled scripts differently. Some have their own memory model. But a skill that captures the team's actual workflow in Markdown is still far more portable than a prompt trapped in a chat transcript.

Markdown is the bridge. Humans can review it. Agents can consume it. Git can version it. CI can validate it. Teams can improve it.

How skills reduce repetition

The obvious benefit is fewer keystrokes. The real benefit is fewer repeated decisions.

Without skills, every agent session starts with hidden setup work. Which files should the agent read? What examples matter? What standards apply? Which commands verify the output? What should the final response include? Which mistakes has the team already learned from?

If the human has to answer those questions every time, the team has not automated the workflow. It has outsourced the typing.

A skill removes repeated setup by packaging the decision path:

That reduces context rebuilding. It also reduces review noise. Reviewers no longer have to say "please follow the same migration pattern" or "include the reproduction steps" or "run the visual check" on every task. Those corrections move upstream into the skill.

The feedback loop is important. Every repeated review comment is a candidate skill improvement. Every agent failure is a diagnostic signal. If agents keep skipping a step, make the step explicit. If they keep loading irrelevant files, tighten the trigger and routing. If they follow the skill when they should not, narrow the description. If the output is technically valid but not useful, add examples and assertions.

This is how the system compounds. The team does not just get better prompts. It gets better operating procedures.

Reviewing skills like infrastructure

If skills shape agent behavior, they deserve review.

Do not treat a skill change like a documentation typo. Treat it like a change to a build script, CI workflow, code generator, or production runbook. A bad skill can quietly waste tokens, create inconsistent output, bypass review expectations, or teach agents to perform risky steps with too much confidence.

A practical skill review should ask seven questions:

• Is the trigger clear? The description should say what the skill does and when to use it. "Helps with backend work" is useless. "Use when creating or modifying database migrations in the billing service" is much better.
• Is the scope coherent? A skill should cover one unit of work. If it includes database migrations, API design, incident response, and release communication, it is not a skill. It is a junk drawer.
• Does it include only high-value context? Every token in `SKILL.md` competes with task context. Cut generic explanation. Keep project-specific rules, fragile steps, examples, and verification requirements.
• Are references loaded on demand? Large examples, API details, schemas, and style guides belong in referenced files. The main skill should tell the agent when to load them. "Read `references/auth-review.md` if the diff touches auth, session handling, permissions, or data access" is better than "see references for more."
• Is the procedure prescriptive where it needs to be? Deployment, migrations, compliance checks, and data deletion workflows need exact sequences and hard stops. Creative drafting, research synthesis, and design critique can allow more judgment.
• Does it require evidence? The agent is not done when it says done. The skill should define what proof is required: test output, lint output, screenshots, generated artifacts, reproduction steps, eval results, or a written risk review.
• Has it been tested against real tasks? Do not evaluate a skill only by reading it. Compare output with and without the skill, or compare the new version with the previous version. Record what improved, what got worse, how much time or token cost changed, and which assertions passed.

Skill review is where teams turn experience into infrastructure. The goal is not to make the skill longer. The goal is to make it more reliable per token.

A simple skill lifecycle

Teams do not need heavyweight governance to start. They need a lightweight lifecycle.

Extract the pattern when a human repeats an instruction, a review comment appears for the third time, or an incident reveals a missed operational detail. Package it as a skill with a clear trigger, a short procedure, on-demand references, and scripts only when they produce repeatable mechanical value.

Test it on real work. Use representative tasks. Compare the skill's output to the baseline. For mechanical requirements, write assertions: did it include the required files, run the command, produce the artifact, and avoid the known failure mode?

Review it like code. Keep the diff small. Check that it is easier to invoke, follow, and verify. Make sure it does not conflict with repository context files or other skills. Then version it, assign owners for important skills, retire duplicates, and mine usage for the next improvement.

The operating system view

The strongest teams will not ask, "What prompt should we use?"

They will ask:

• What work repeats across the team?
• Which parts require local judgment?
• Which context should be global, local, or task-specific?
• Which procedures deserve skills?
• Which outputs require proof?
• Which failures should update the source instruction?
• Which assets should be portable across tools?

That is AI Systems Engineering. The model matters, but the system around the model increasingly determines whether the work is reliable, cheap, and repeatable.

Skills are one layer in that system. They do not replace repository context. They do not replace tests. They do not replace code review. They do not replace human judgment. They make all of those easier to apply consistently because they package recurring work into a reusable execution unit.

The mistake is treating skills as a personal productivity hack. That keeps the value trapped at the individual level.

Treat skills as team infrastructure instead.

Put them in version control. Review them. Test them. Keep them scoped. Connect them to context routing. Improve them from real failures. Make them portable enough that the team's operating knowledge survives tool changes.

The future is not better prompt hoarding.

The future is engineered AI workflows, and skills are one of the simplest ways to start building them.