Taking a Skill apart, simple to complex

The last post took apart make-photo-stamp-archive. It’s actually a very simple Skill: no complex code, mainly a design method and a prompt template, and it still produces quite stable results.

Digging further, I think the best way to understand Skills isn’t to memorize folders like scripts / references / assets first, but to look at the two ends:

how simple can the simplest Skill be? And why does a complex Skill need to become complex?

At its simplest, a Skill can be just one SKILL.md

The minimum structure of Agent Skills is really just:

my-skill/

└── SKILL.md

It contains a name, a description, and the instructions AI should follow when doing this kind of task.

So a simple Skill really can be very close to a well-organized prompt / SOP. Normally the agent first judges from the name and description whether the Skill is relevant to the current task, and only loads the full content when it’s really needed.

make-photo-stamp-archive is close to this kind.

What it mainly needs to solve is:

• what kind of composition works well;
• which stamp different photos should get;
• what must not be changed;
• how to check the generated result at the end.

The model can already look at images and understand text, and has image generation tools. This Skill doesn’t need to handle databases, call complex APIs, or run large amounts of deterministic code.

So what the author most needs to give AI is a stable design method.

A task like this naturally doesn’t need to be complex.

Why Skills start to become complex

Switch to a different task, and things are completely different.

OpenAI’s official chatgpt-apps Skill is meant to help Codex build ChatGPT apps. It can’t possibly get by with a few hundred words in SKILL.md.

Building an app, the agent has to deal with:

• what architecture different kinds of apps should use;
• how the MCP server and the UI connect;
• which official example to reuse;
• what minimum requirements the project structure must meet;
• how to create scaffolding when there’s no suitable template;
• and finally how to verify the implementation is correct.

So besides SKILL.md, it has lots of references, plus a ready-made scaffold script.

Here a distinction appears that I think matters a lot:

a Skill’s complexity isn’t a measure of skill level, but of how many different kinds of information and operations the task needs.

Converting image style mainly lacks a method and aesthetic rules; one document may be enough.

Building a complete app needs a method, plus technical knowledge, project templates, deterministic code and a verification process, so it naturally becomes much more complex.

Why not put everything into SKILL.md?

In theory you could write one tens-of-thousands-of-words super Skill.

But that’s usually not good design.

An agent’s context is limited. OpenAI’s Skill Creator explicitly recommends providing only the extra information the model really needs; the Agent Skills best practices also recommend keeping SKILL.md core and lean, and splitting detailed content out to be loaded as needed.

So a common way to split things:

SKILL.md

Holds what’s needed every time the task runs:

• the overall flow;
• key judgments;
• rules that must be followed;
• when to read other material.

references/

Holds large amounts of knowledge you only look up occasionally.

For example:

references/

├── api-docs.md

├── database-schema.md

└── business-rules.md

Read the API docs when you need the API; look at metric definitions only when you need them.

references are for AI to read.

scripts/

Holds programs that are already very deterministic, with no need to have the model write them afresh each time.

For example:

scripts/

├── validate_output.py

└── convert_data.py

File conversion, data validation, fixed-format processing — having an already-tested script do these is usually more stable than the model writing them on the spot every time.

OpenAI’s Skill Creator also explicitly suggests: if the agent keeps rewriting the same code, it’s worth turning it into a script.

scripts are for AI to run.

assets/

Holds things the final output can reuse directly:

• a starter project;
• templates;
• images;
• style files;
• document skeletons.

assets are for AI to use.

So a complex Skill isn’t simply “a prompt that keeps getting longer.”

The better approach is actually to keep things of different natures apart.

If you want to try it yourself, try one from each end, simple and complex

If you just want a first feel for Skills, start with a simple task.

For example, make your own:

a README-review Skill

with only a SKILL.md:

• what a README should be checked for;
• what counts as missing information;
• which phrasing should be avoided;
• what format the final review is output in.

No scripts or references for now.

That makes it easiest to feel the difference between a Skill and “writing a one-off prompt”: every future README review can reuse the same method directly.

Image tasks are also good for getting started. make-photo-stamp-archive is a great ready-made example.

If you want to see what a complex Skill actually looks like, go read OpenAI’s chatgpt-apps Skill directly; if you do development yourself, you can also have Codex actually use it to build a very small ChatGPT app. It’ll show you how references, scaffolding, validation and the main Skill work together.

PDF processing is also a very typical kind of complex Skill: reading, splitting, rotating, forms, OCR, encryption and other tasks need different tools and reference methods. Anthropic’s public PDF Skill already has a main instruction file of over two hundred lines, with more advanced content placed in further reference files.

If you make your own Skill

These days I think the more practical way to judge is to look at your own everyday work first.

If something meets all of the following, it’s fairly worth making into a Skill:

• it happens again and again;
• the input differs each time, but the method is broadly stable;
• you’ve already built up some clear judgments, rather than going by feel each time;
• AI often makes mistakes in similar places;
• there’s a way to check the result.

Then start with the simplest version.

If all the rules fit into one SKILL.md, stop there for now.

After actually using it, you may find:

some background material is too long and isn’t needed every time → put it in references

AI keeps writing the same code → make it into scripts

the same template gets generated from scratch every time → put it in assets

In other words, complexity should grow out of real problems, not start with a folder designed to look complete.

How I understand Skills now

Simple Skills and complex Skills aren’t two different species.

They solve the same thing: turning a kind of recurring work into a method AI can reuse.

Some tasks only ever need one page of instructions.

Some involve lots of knowledge, tools and deterministic operations, so they need references, scripts, assets, even a fuller verification process.

What really needs designing isn’t the folders but the boundaries:

• what the model should judge, and what can already be fixed;
• what needs knowing every time, and what only gets looked up in particular cases;
• what’s worth leaving to AI to handle on the spot, and what should just be given to it as a reliable tool.

So the first time you make a Skill, don’t aim for complexity.

First find something you’ve already done again and again, and really know how to do.

Starting with one SKILL.md is enough.

You could try:

• Review-type Skills, such as README review, PR review, résumé review, design review. The best for getting started, because there’s usually already a fairly stable set of checks, and one SKILL.md is enough to begin.
• Fixed-output-style Skills, such as make-photo-stamp-archive this time, or a fixed style for reports, charts or documents. The point isn’t writing “premium, clean,” but breaking out your real judgments: proportions, structure, what to avoid, what choice to make in which situation.
• Repeated project checks, such as checking config, tests, docs, permissions and error handling before every release. These suit gradually adding scripts, so deterministic checks don’t rely on the model re-judging every time.
• Tasks that need fixed reference material, such as always looking up the same set of metric definitions when analyzing business data, or always consulting the same internal guidelines when writing APIs. Put these in references/ and read them when needed.
• Work where you’ve already formed your own method, such as synthesizing user research, breaking down requirements, competitive analysis, reviewing articles. These may actually have the most personal value, because the Skill holds not just the steps but the judgment you’ve built up over time.

I filter with a very simple standard:

Does this happen often? Does the input change each time, while my way of doing it stays roughly the same? Do I already know where AI is most likely to go wrong?

If the answers are mostly “yes,” it’s worth first making the simplest Skill to try.

And a first version with only one SKILL.md is completely fine. After using it a few times, if you really find it’s missing material, scripts or templates, grow references / scripts / assets slowly.

A Skill doesn’t need to start from “complex”; it should start from “I really do have a method worth repeating.”