TLDR
Here is the complete framework for creating AI skills that can do real work inside a business: where skills live, how agents find them, what belongs inside them, how progressive disclosure works, the five types of skills, and how skills improve through use.
Before you create another skill, you need to understand how the system works. Then you need to make sure the skill learns every time the business does. That is how an AI agent becomes a business learning system.
If you want an agent to do more, the usual answer is to create more skills.
It works. Every new skill gives the agent another process it can follow.
But creating more skills is not the difficult part.
The difficult part is understanding how they work.
Without that understanding, it is easy to end up with a collection of static instructions. The agent can follow more processes, but the processes do not become better when the business learns something new.
A business never stays static. Tools change. People solve new problems. Teams discover better ways to work. Decisions are made.
The skills should move with the business.
This framework gives every skill two jobs: complete the work now, and keep what the work teaches it for next time.
By the end of this article, you will know how skills work from the inside and how to create one that becomes more useful every time your business uses it.
1. Understand where skills live
A skill does not live inside the model.
It lives in the agent’s workspace, as a folder containing files.
The exact folder changes between Codex, Claude Code, Pi, OpenClaw, and other agent harnesses. The principle does not. Each system has a place where skills are stored, and each skill has its own folder inside it.
The first part the agent sees is not the complete skill. It is the skill’s name and description.
The description explains when the skill should be used. It stays available to the agent during the conversation. When your request matches that description, the agent finds the skill folder and opens its SKILL.md file.
This creates a strange little loop.
The description is written inside SKILL.md, but the agent needs the description to know that it should open SKILL.md.
The agent harness solves this by making every skill description available before the skill itself is loaded.
That means the description is not a label you add at the end. It is part of the skill’s behavior.
A vague description makes a good skill difficult to find. A precise description tells the agent what the skill does, when it applies, and when it does not.
Before you write the workflow, answer one question:
What should be happening in the conversation when the agent decides to use this skill?
That is the real starting point.
2. Use SKILL.md as a menu
A skill can be one folder with one SKILL.md file.
For a small task, that may be enough. The file explains what to do, the agent follows it, and the work is finished.
A complex skill needs a different structure.
Trying to place every instruction, example, tool detail, failure, and exception inside one enormous file makes the skill harder to use. The agent has to read all of it, even when the current task needs only one small part.
The better approach is to treat SKILL.md as a menu.
It explains what the skill can do, which route applies, and which file the agent should open next.
The rest can live behind that menu. Every part is still just a file.
skills/platform-slack/
The menu. What the skill can do, which route applies, and which file the agent opens next.
Local truth: the identities, paths, accounts, and boundaries of this business.
What earlier runs discovered, so nobody discovers it twice.
What ran, when, and what happened.
Deeper methods, tool documentation, examples, and boundaries.
Exact actions that should not depend on the model improvising.
Proof that the scripts and the important workflows still work.
Prompt or step files that separate a long process into clear stages.
A small SQLite or JSON store, when structured data beats more prose.
The agent starts with the menu, then opens more only when the work requires it.
This is progressive disclosure.
The goal is simple: give the agent the minimum information it needs to know where the right information lives.
A market research skill can contain methods for customer language, personas, competitors, positioning, and marketing angles. A request about customer language should not force the agent to read the complete competitor workflow.
The menu points to the relevant file. That file can point to a script. The script can produce an output that sends the agent to the next step.
This is what allows a skill to become large without becoming unusable.
You can even add a database without building an interface. If the skill needs to organize structured data, ask the agent to store it in SQLite. The database becomes another file the skill knows how to read and update.
You do not need to become a database engineer first. You need to understand what information belongs there and how the skill should use it.
3. Define the skill with four questions
Once you understand the folder, you can decide what kind of skill you are creating.
I use four separate questions.
They are independent. A platform skill can be active or passive. A tool skill can trigger automatically or through a command. A branch skill can use a schedule.
Do not force them into one taxonomy.
What is its purpose?
Decides the kind of capability the skill preserves.
What triggers it?
Decides how the agent knows it should run.
What is its structure?
Decides how the agent moves through the work.
What is its posture?
Decides whether you invoke it directly, or it supports decisions in the background.
The five purpose types are the naming system I use. They are not an industry standard.
Shapes how the agent approaches work. Planning, building, research, and review live here.
Helps the agent maintain itself or the wider agent system. Session recovery and token management are examples.
Preserves knowledge about one external tool. Instead of rereading the same documentation every time, the agent keeps the useful routes, limits, and lessons in one place.
Produces a repeatable outcome. Creating an artifact, running market research, or producing static ads fits here.
Preserves the working knowledge of one business function. Product management, media buying, customer support, and other roles can build a shared capability this way.
The name matters less than the question behind it:
What kind of knowledge should still be available the next time this work happens?
That answer determines the skill.
4. Give the skill two jobs
A static skill has one job. A learning skill has two.
a static skill
- Follow the current instructions.
a learning skill
- Complete the work using the best method it knows.
- Preserve verified knowledge that should improve the next run.
This does not mean rewriting the skill after every small surprise.
It means giving the work a clear place to leave useful knowledge behind.
In my setup, the loop has three moments.
Before the run
The agent reads the current method, the local context, and any lessons relevant to the request.
The work starts from what the skill already knows about this process, this tool, and this business.
During the run
Something new can happen.
A tool behaves differently from its documentation. A research source fails. A team discovers that an approval needs to happen earlier. The agent checks the situation, finds another route, tests it, and completes the work.
After the run
The agent records what happened, then sends each part of it to the right place.
A verified local fact.
A reusable discovery.
A proven change to the method, or the reference file that holds it.
A one-time event. It stays in the run history and changes nothing else.
A platform skill shows this clearly.
Imagine the skill was created from the current documentation for Notion. Later, you ask the agent to merge two pages using a route that is not inside the skill.
The agent checks the documentation, tries a route, fails, finds the correct one, verifies the result, and finishes the task.
A static skill forgets that work.
A learning skill records the working route in the relevant reference file. The next request begins where the previous one ended.
The same thing happened while staging earlier versions of this article.
Cloudflare reported a successful deployment. The deployment URL showed the new page, but the custom domain briefly showed the previous one.
The useful lesson was not “purge the cache.” It was more precise:
Verify the deployment URL and the custom domain before changing anything. The custom domain can converge a few seconds later.
That lesson was stored in the Cloudflare skill. The next deployment used it instead of repeating the investigation or changing healthy configuration.
One run improved the route used by the next one.
That is the learning system.
Human judgment stays in the loop
The skill should not treat every event as a new rule.
A temporary workaround may never help again. A failed source may have been unavailable for five minutes. One unusual request should not change the policy of the whole system.
Run history can record facts automatically.
Local context can change after the agent verifies that something actually changed.
The reusable method should change only when the lesson is likely to help again. Larger changes still need human judgment.
Policy, security, behavior, and writing rules should not rewrite themselves because of one task.
the point
The goal is not continuous rewriting.
The goal is to stop useful knowledge from disappearing.
5. Create the skill after completing the work
The strongest skills do not begin in a skill library.
They begin with work.
A public skill can give you a useful structure or starting method. It cannot know which sources your team trusts, how your approvals work, where your data lives, which exception matters, or what your company considers a good result.
That knowledge appears while the work is happening.
The process I use is simple.
First, define the outcome
Do not begin by telling the agent which files to create.
Explain the result you want. Ask questions. Think through the problem together. Research what is missing.
Continue until the desired outcome is clear.
Second, complete the work
Ask the agent to execute.
Inspect the result. Correct what is wrong. Change the route when needed. Keep iterating until the output matches your standards.
At this stage, you are not creating a skill. You are discovering how the work should be done.
Third, document the successful route
Once the result is good, the conversation contains the material for the first version:
- the real outcome;
- the context that changed the answer;
- the tools and sources that worked;
- the routes that failed;
- the judgment that shaped the result;
- the proof that showed the work was complete.
Now create the skill.
Fourth, test it in a fresh conversation
A skill can look perfect while still benefiting from the context of the conversation that created it.
A fresh conversation removes that hidden help.
Run the same process on a different example. Watch where the agent hesitates, opens the wrong file, skips a check, or produces the wrong output.
Correct the skill, then start another fresh test.
Fifth, keep the loop running
The first passing version is not the final version.
It is the first version that can now learn from real work.
The market research skill shown in the video is a useful example.
It is a branch skill. One SKILL.md file acts as the orchestrator, then routes the work through separate step files for customer language, personas, competitors, positioning, and marketing angles. References hold the method. Prompt files define the research jobs.
The diagram shows the architecture I built.
The results below are my observations, not an independent benchmark.
The skill can complete a full brand research project in one to two hours. Getting there required repeated testing. Some iterations ran through ten or twelve fresh conversations before the agent considered the route stable.
Agent-led testing often reached about 80 percent of the result. My judgment still decided whether the research was useful, whether the business conclusions made sense, and whether the skill was ready.
That last part matters.
The agent can run tests, compare behavior, find failures, and correct files. It cannot decide what “good” means for your business without your judgment.
A team skill turns personal learning into company learning
The same framework can preserve the knowledge of a business function.
One product management example started with the problems already appearing in the team’s work. Existing conversations showed what the team was dealing with. External research supplied useful methods and tools. That material became the first version of a product management skill.
The skill then loaded whenever the team handled that kind of work.
When someone faced a new problem, the agent could research it, try a route, test the result, and preserve the useful lesson.
The important choice was to make it a team skill, not a person skill.
Everyone in that function could begin with the same capability. New knowledge returned to the same place. A new team member did not have to begin with an empty conversation.
This is where the phrase “business learning system” becomes real.
The business does the work.
The skill preserves what the work teaches.
The next person starts from there.
This example is anonymized. It shows the knowledge structure, not a measured productivity benchmark.
Six mistakes that keep skills static
Creating more skills without a system
Every new description competes for the agent's attention. Overlapping skills make discovery harder and leave the agent unsure which process owns the work.
Create a new skill when the capability has a clear boundary. Otherwise, improve or reorganize what already exists.
Putting everything inside SKILL.md
A giant instruction file defeats progressive disclosure.
Keep the route in the menu. Move deep methods, examples, scripts, and data into the files that need them.
Treating a downloaded skill as business knowledge
A public skill can teach a method. It cannot know your business before your business teaches it.
Use public skills as references and starting points. The advantage comes from the context, corrections, and decisions your own work adds.
Testing inside the creation conversation
The original conversation contains context the finished skill may not have later.
Always test in a fresh conversation. Better still, test with a different example.
Saving every event as a lesson
A log is history. A lesson is something likely to help again.
Do not let one unusual run quietly rewrite the method.
Removing human judgment
The agent can test whether it followed the files. It cannot fully judge whether the result makes sense for your company.
Let the agent handle the iteration. Keep the final standard human.
Build one business learning skill
Choose one process you have already completed successfully with an agent.
Not the largest process. Not the most impressive one. Choose something that happens often enough for the next run to matter.
Then give the agent this:
Use the process we just completed to create a skill.
Before writing any files:
1. State the exact outcome this skill must reproduce.
2. Identify the context, sources, tools, decisions, and checks
that shaped the result.
3. Separate the main route from deeper references, scripts,
tests, and structured data.
4. Write a precise name and description so the agent knows
when to use the skill.
5. Add a learning loop that records each run and preserves
only verified, reusable lessons.
6. Define what the skill may never change automatically.
7. Test the skill in a fresh conversation with a different
example.Read the result.
If everything sits inside one enormous file, ask the agent to turn SKILL.md into a menu.
If the description could match several skills, narrow it.
If the skill has no place for context, lessons, or run history, add one.
If one event can rewrite policy, close that boundary.
Then run the fresh test.
Creating more skills gives your agent more things it can do.
Understanding how those skills work, then letting them learn with the business, gives the company something more valuable:
A capability that compounds.
Watch the complete walkthrough: How to make your business smarter over time.
If you want the system I use to create, improve, reorganize, and retire skills, see Skill Forge.