How AI Agents and Claude Skills Work, Clearly Explained

The models are good now. Really good.

Opus 4.6 and GPT 5.4 are capable enough that arguing about which one is better at interfaces or back-end code can distract from a more useful question: What information are you giving the model, and what tools can it use?

You can take a capable model and get excellent work. You can also take that same model and get slop. The difference often comes down to context, the agent harness, and whether you have actually defined what a successful result looks like.

My approach has become simpler, not more complicated: less always-on instruction, more custom skills, and one reliable workflow before a whole team of agents.

How an AI Agent’s Context Window Works

Think of context as the information available to the model while it works. It includes much more than the message you just typed.

In a coding agent such as Claude Code, that information can include:

• The system prompt: foundational instructions about how the agent should behave, what it should do, and what it should avoid.
• Project instructions: files such as AGENTS.md or CLAUDE.md that provide persistent guidance.
• Skills: descriptions of available workflows, with more detailed instructions loaded when relevant.
• Tools: definitions that tell the model what operations are available, such as reading files or writing code.
• Project material: code, documents, and other information the agent reads while completing the task.
• The conversation: your requests, corrections, tool results, and the agent’s previous responses.

The harness is the software around the model that makes this useful. The model can request a tool operation; the harness executes it and returns the result. That surrounding system matters because producing text and taking action are not the same thing.

All of this occupies space measured in tokens. A conversation might begin with roughly 20,000 tokens of material and grow substantially as work continues. The exact capacity depends on the model and product. Eventually, tools such as Claude Code and Codex compact the conversation to make room.

The practical point is simple: context is a limited working resource, not a storage closet for every instruction you have ever written.

Why I Usually Skip Large AGENTS.md and CLAUDE.md Files

My hot take is that about 95% of people do not need the large instruction files they are building. That is my practical estimate, not a universal rule.

A lot of these files repeat things the agent can already discover.

If your codebase uses React, the agent can inspect the project and see that. Telling it repeatedly that the project uses React is a little like reminding someone who records podcasts for a living that they need a microphone.

They know.

The more useful question is whether the instruction contains something the model cannot infer:

• Proprietary company information that genuinely matters throughout the work.
• A company-specific methodology that applies to every task.
• A persistent business requirement that is not obvious from the project.

Those are good reasons to keep project instructions. Generic knowledge usually is not.

For example, telling an agent that financial reports should use a dollar sign adds little. Telling it which currency your business reports in may be important. One is general knowledge; the other is a specific requirement.

In the setup I am describing, project instruction files are part of the ongoing context. A thousand-line file might contribute thousands of tokens whether or not its instructions are relevant to the current task. Exact loading and billing behavior varies by tool, but the design question remains: does this information need to be always available, or only available when needed?

For instructions that apply to a particular workflow, I generally prefer a skill.

How Claude Skills Use Progressive Disclosure

A skill has three basic pieces:

1. A name.
2. A description explaining when to use it.
3. Detailed instructions for carrying out the work.

The important mechanism is progressive disclosure. Initially, the agent gets the name and description. It reads the full instructions when it determines that the skill is relevant.

Suppose you have a skill for creating a Notion report. You ask for that report, the agent recognizes the matching skill, and then it loads the workflow. It does not need the whole reporting procedure sitting in context while it handles an unrelated task.

That is why I am so enthusiastic about skills. They let you make specific knowledge available without making all of it always present. The Agent Skills specification provides additional detail on this structure.

But a well-packaged file is not automatically a good workflow. That is where people get into trouble.

Build the Workflow First, Then Create the Skill

The wrong sequence is easy to fall into: identify something you want to automate, immediately ask AI to write a skill, and assume the job is done.

The missing ingredient is evidence of what success looks like.

You would not hire someone, give them a vague assignment, and declare that their first interpretation should become your permanent operating procedure. You would work through the task, answer questions, correct mistakes, and clarify your standards.

Do the same thing with an agent.

Example: Screening Sponsor Emails

I use an OpenClaw agent to help evaluate sponsorship inquiries. It has its own email account. I forward selected messages rather than giving it access to my primary inbox because I am careful about security and have dealt with being hacked before.

My first instruction was roughly: check for forwarded emails every 15 minutes, research the sponsor, and tell me whether the company is worth working with.

The results were basically all positive. Legitimate. Looks good. Great opportunity.

That was not useful. I needed screening, not a rubber stamp.

The problem was that I had not defined what research meant or what should trigger rejection. So I worked through an actual inquiry with the agent:

1. Identify the company. Establish who is making the offer and what the business does.
2. Check specific sources. Look at its X presence, YouTube, Trustpilot, and whether it has raised funding.
3. Apply my decision rule. In this workflow, if two of those signals are missing or not in good standing, reject the opportunity.
4. Record the outcome. Update our Google Sheet with the decision, including a no-contact status where appropriate.
5. Escalate strong opportunities. Email me when a company meets the standards for a worthwhile partnership.

That rejection rule is my screening preference, not a universal test of whether a company is legitimate. The important thing is that the agent now had an explicit decision process.

We worked through the process successfully, repeated it, and only then turned it into a skill.

The Three-Step Skill-Creation Method

1. Identify a recurring workflow. Choose a real task you already need to complete.
2. Work through it with the agent. Give instructions, inspect results, correct errors, and establish what right and wrong look like.
3. Ask the agent to document the successful process as a skill. Have it review what actually worked, not invent a procedure from a vague goal.

I do not handwrite all my skills. AI can write them. There are even skills for creating skills. Skill inception.

What matters is that the agent has the context of a successful run before it writes the instructions.

These systems generate responses from learned patterns and available context. Their fluent language can make it feel as though they share your understanding of the business. Do not mistake that fluency for knowledge of your specific standards.

Why I Do Not Blindly Install Other People’s Skills

I will review someone else’s skill. I might give it to my agent and ask what we can learn from it. But I do not assume that downloading a workflow makes it suitable for my business.

There are two reasons.

First, security. A skill can influence an agent that has access to tools and data. Instructions from an unknown source deserve scrutiny.

Second, fit. Someone else’s process reflects their assumptions, tools, preferences, and definition of success. Yours may be different.

A marketplace full of skill files is not the same thing as a collection of tested operating procedures. I do think there could be a real market for carefully developed, well-defined skills. But the value would come from the workflow quality, not simply from putting instructions in a Markdown file.

Study useful examples. Then build and validate your own version.

Improve Skills Recursively Instead of Starting Over

Creating the first skill does not mean the workflow is finished. It will encounter gaps, unexpected data, or API failures.

That is not a reason to throw the whole thing away. It is your next improvement opportunity.

My loop looks like this:

1. Run the skill on real work.
2. Identify the failure. Ask what operation failed and what error was returned.
3. Work with the agent to fix it. Correct the call, resolve the account issue, or clarify the missing instruction.
4. Verify that the corrected process succeeds.
5. Update the skill with the fix. Preserve the lesson so future runs can handle that situation.

If an agent says it could not finish, ask it why. Get the actual error. You may discover that the problem is insufficient API credits rather than an inability to perform the task.

The distinction matters. Otherwise, you are blaming the model for something that needs an account or integration fix.

My YouTube report generator pulls from about eight sources, including Notion, Dub Analytics, YouTube Analytics, and X analytics. That was not going to become a reliable workflow from one prompt.

I went through roughly five rounds of this improvement loop. After that, the workflow was completing reliably in my use, taking around ten minutes per report.

The lesson is not that five iterations guarantee success. It is that fixing a run and updating the reusable instructions are two separate jobs. If you do only the first, you leave useful knowledge behind in the conversation.

For Coding Agents, the Codebase Is Context Too

When building software, people often fill instruction files with stack descriptions: React and Convex, Next.js and Supabase, this framework and that library.

Much of that information is already in the project.

A solid codebase gives the agent examples of how the application is structured. That makes the starting foundation important. Instead of writing pages explaining how you want ordinary code to look, you can often give the agent a project that already demonstrates it.

This is why I think good software templates could have a renaissance. A useful template is not just a shortcut for a human developer. It is a working example for the agent to build on.

That does not mean coding skills are unnecessary. A skill makes sense when it captures something specific, such as your preferred review structure or a distinctive operational workflow.

I have a code-structure skill for reorganizing generated code so it is easier for me to review. Its value is not that it teaches the model programming. Its value is that it expresses my preference for how the result should be organized.

Protect the Context Window, Not Just the Token Bill

That code-structure skill is 116 lines long. In the tokenizer demonstration, the full instructions came to 944 tokens. The name and description came to just 53.

That is a concrete example of why progressive disclosure matters. The short description helps the agent discover the skill; the full instructions become available when needed.

You can explore this distinction with the OpenAI tokenizer, although token counts vary across tokenizers.

The benefit is not only cost. It is also avoiding unnecessary pressure on the context window.

In my own use, I try to keep sessions comfortably below full capacity, roughly within the first 70% when practical. That is a working preference, not a guaranteed performance threshold. Different models and tasks behave differently.

The principle is more durable than the percentage: give the agent relevant information, not the maximum amount of information.

Do not spend context reminding the model of general knowledge. Spend it on what is unique to your business, your workflow, your strategy, and your taste.

Start With One Agent, Then Add Subagents

I use subagents. This is not an argument against them.

It is an argument against setting up 15 agents and 30 skills before you have made one workflow useful.

That is like starting a company with ten employees before you have ever managed anyone. More people do not automatically create a functioning business. More agents do not automatically create productivity.

I started with one main agent handling spreadsheets, sponsor emails, and research. Once those workflows were defined, I could delegate coherent responsibilities to subagents.

Eventually, my setup grew to five subagents, including ones focused on marketing, business, and personal work. They had a reason to exist because there were already skills and context to give them.

The sequence matters:

1. Make one agent useful.
2. Build and refine repeatable skills.
3. Identify a meaningful area of responsibility to delegate.
4. Add a subagent with the relevant context and skills.

Tools such as Paperclip can be interesting and useful. I try these systems too. But adopting an impressive architecture is not a substitute for understanding what work you actually need done.

Scale for productivity, not for what looks cool.

Expect an Upfront Investment

My own OpenClaw setup took about two weeks of initial work before it began making sense for me. At first, I was frustrated too. The system seemed confused, and I wondered why it could not understand straightforward requests.

Then I realized I was treating it like a colleague who already knew the business.

If someone who works closely with you asks for a financial report in Notion, you may know exactly what they mean. A new employee does not know which sources to use, which figures matter, or what format is expected.

It is the same problem as asking someone for a “rundown” without explaining what a rundown means in your organization. The word feels clear to the person making the request. The recipient is missing the context.

Expect an early period of teaching, correction, and integration work. My two weeks is an experience, not a promised setup time. The point is that useful automation often has an investment phase before the payoff.

The Skill You Are Really Building Is Your Own

There is plenty of anxiety about AI and white-collar work. I do not find fatalistic language about a “permanent underclass” useful. It makes change sound hopeless when there is practical work people can do now.

Learning to define a workflow, identify a failure, evaluate output, and turn a successful process into reusable instructions is valuable. You are not just building SKILL.md files. You are getting better at directing these systems.

It is also worth resisting the urge to overthink every opportunity. More people can build software and automate work now. You still have to release something, learn from the result, and improve it.

None of this requires a shiny new tool every week. Sometimes a clearer explanation of the basics does more for someone’s business than another product launch.

The tools will change. Memory systems will improve. Some of today’s advice may need revisiting. But my current approach is straightforward: trust capable models with general knowledge, supply the context they cannot know, build skills from successful work, and expand only when it makes the system more useful.

Start with one real task. Work through it. Make it repeatable. Then scale.