In the meeting room, Lin Zhean (an illustrative character — an internal systems administrator at a small accounting firm, not a real client) opened his screen share, ready to demo the ‘monthly branch report roll-up skill’ he’d spent all of last Saturday night building. His manager was sitting next to him, and the client was already on the call waiting to see the result. He hit run. The AI Agent quickly pulled every branch’s numbers into one report — except the grand total in the very last column didn’t match the subtotals next to it.
The room went quiet for three seconds. His manager spoke first: ‘Where… did this number come from?’ Lin Zhean couldn’t answer, because he himself had no idea how the AI had added those figures together. All he knew was that he’d asked the AI to write this ‘skill’ for him the previous Saturday night, it looked reasonable enough once it was done, so he just started using it.
That night, he pulled the whole thing apart and realized he’d walked straight into several of the most common mistakes people make with ‘AI Agent Skills’ — the kind of mistakes that are invisible until you actually put them to use.
His Skill That the AI Never Even Opened
Lin Zhean opened the skill.md file he’d written and reviewed it again, and found that the ‘description’ field at the top of the YAML was vague — something like ‘generates monthly report roll-ups.’ The problem is, an AI Agent doesn’t load the full content of every skill when it starts up; it only looks at each skill’s name and description first, and uses those few words to judge whether this is the right moment to use it. With a vague description, the Agent is likely to conclude ‘maybe useful, maybe not’ and just skip it, calculating everything on the fly instead — which turned out to be the first layer of why his demo failed: the skill may never have been triggered at all, and the AI simply worked out that report on its own, in its own way.
He rewrote the description into something much more explicit: clearly stating what the skill does and exactly when it should be used — for example, ‘Consolidates each branch’s monthly revenue details into a monthly report; use when the user asks for a monthly report, month-end roll-up, or branch figure summary.’ He’d also heard that models are naturally more prone to under-using a skill than over-using one, so the description should lean toward being direct — even a bit of unabashed ‘self-promotion’ — rather than staying too conservative or understated.
The Skill the ‘AI Wrote for Him’ Actually Taught It Nothing
Once the triggering problem was solved, Lin Zhean opened the body of the skill and read it again, and found that most of the content was generic, works-anywhere filler like ‘please verify the input data is correct’ and ‘handle error cases properly’ — things the AI already knows, so writing them into a skill is effectively writing nothing. What actually belongs in a skill is the part the AI could never figure out on its own: your specific way of doing this particular job — which step tends to go wrong, what got kicked back by his manager last time, what odd exception rules are hiding in the old reports.
So he dug up the old reports that had been sent back three times by his manager the previous month, along with the revision comments from back then, and went through them one by one, writing down exactly what had gone wrong each time and how it had eventually been fixed. These ‘lessons already learned the hard way’ turned out to be the truly valuable part of the skill — because that’s the detail the AI has no way of looking up on its own; only someone who has actually done this job knows it.
The More Patches He Added, the More the AI Started to ‘Space Out’
After patching in one lesson after another, the skill file kept growing longer, until eventually the Agent’s execution slowed down and it even started missing points it had been told about earlier. That’s when Lin Zhean understood: once a skill is selected, its entire content gets loaded into the current conversation context, competing with everything else being processed for the same slice of attention budget. The longer it is, the more of the AI’s available ‘thinking room’ gets crowded out by its own instruction manual, right at the moment it’s supposed to be doing the actual work.
The fix isn’t to strip the content back down to nothing, but to layer it: keep the skill body itself limited to only what the AI genuinely needs in the moment — roughly 500 lines, translating to somewhere around 5,000 tokens (this is a rule of thumb from the original video’s speaker, not an official conversion standard from this site or any platform; actual token counts vary by model and tokenizer). Finer details that aren’t needed every single time — like an exception rule specific to one particular branch — go into a separate subfolder instead, which the AI only reads when it actually runs into that specific situation, rather than eating into the everyday execution budget for nothing. This was the first time Lin Zhean realized that writing a skill is really its own kind of careful token-budget planning — more detail doesn’t automatically mean safer.
That Total That Didn’t Add Up Wasn’t a Coincidence
Back to the roll-up problem that failed in front of the client. On inspection, Lin Zhean found that for the addition step, he’d originally just let the AI read the numbers and add them up itself in its head — but a language model is, at its core, ‘predicting’ the most likely next output, not actually performing exact arithmetic. The more fields there are and the messier the numbers get, the easier it is for the AI to get the sum wrong — and to sound completely confident while doing it.
He changed that ‘addition’ step from ‘let the AI calculate it itself’ to a small, fixed piece of calculation logic that the skill calls directly to do the summing; the AI no longer does the arithmetic in its head, and is only responsible for organizing the data and dropping the calculated result into the report. The kind of total-mismatch error that had blown up in front of a client became a category of error that simply couldn’t happen again — because correctness is no longer something the AI is ‘guessing’ at in the moment, but something decided by a piece of logic that produces the same result every single time it runs. He also realized this principle isn’t limited to arithmetic: any step that must be precise and consistent every single time should be handed off to fixed logic, with the AI responsible only for deciding when to call it.
He Almost Installed a Skill File Someone Else Had Already Written
After fixing the skill and getting the monthly report to produce the right numbers, Lin Zhean saw someone in an industry Line group share a ready-made ‘invoice reconciliation skill’ as a zip file, with a note saying, ‘Just drop it in and use it, super convenient.’ He almost installed it on the spot — after all, it’s just some text instructions and a couple of scripts, how bad could it be?
But then he remembered the skill he’d just fixed himself: it could execute code, read and write local files, and potentially even touch API keys already configured in the system — in other words, installing a stranger’s skill is, in some sense, running a program written by someone you don’t know, directly inside your own environment. He later learned that the same video explaining these best practices also mentioned an audit of roughly four thousand publicly circulating skills, in which about 35% were found to have some kind of security flaw, and roughly 13% contained something more serious — like malicious code or techniques designed to trick the AI into taking unintended actions (this figure is the video speaker’s characterization of some audit, and the video did not further identify its source; it is a secondhand account not independently verified by this site or AITK, provided only as a general risk-awareness reference, and does not represent the actual proportion for any specific public skill repository).
He didn’t install the zip file directly. Instead, he spent ten minutes opening up its instructions and scripts and reading through them first, to confirm exactly which files it would touch and whether it would send anything out externally — the same way you’d evaluate whether to add a new package to a project. From then on, ‘read it before you use it’ became his default move for any skill he hadn’t written himself.
The Following Week, Same Meeting Room, He Hit Run Again
The following week’s monthly report demo, Lin Zhean hit run again — same meeting room, same manager, same client. This time, the total matched on the very first try, with no extra waiting or stalling on screen. Nobody made a point of praising it — a report that’s correct isn’t supposed to earn praise; it’s just supposed to be correct.
But after the meeting ended, Lin Zhean did one more thing on his own: he turned everything he’d learned the hard way over those past few weeks into a shared ‘pre-launch skill checklist’ for his team — so that from now on, anyone connecting a new skill to a live workflow has to go through that checklist first, instead of doing what he did the first time: write it, have it look reasonable enough, and go straight to demoing it in front of a client.
FAQ
Q1: What’s the difference between an AI Agent Skill and a regular prompt?
A prompt is usually a one-off instruction given in the moment, within a single conversation. A skill, on the other hand, is a persistent, file-based ‘operating manual’ that teaches the AI the specific way you want a particular job done, once and for all — you don’t need to re-explain it every time, and the AI decides on its own, when needed, whether to call on it.
Q2: Is a skill file better the more detailed it is?
No. Once a skill is selected and run by an Agent, its entire content occupies the current processing budget — writing it too long actually crowds out the AI’s attention for everything else and slows its response. The rule of thumb is: only write down the ‘specific approach that’s uniquely yours’ that the AI couldn’t have figured out on its own; details that aren’t needed every day should be split off into a supplementary folder and loaded only when actually needed.
Q3: Why does an AI that seems so smart still get something as simple as addition wrong?
Because a language model is, at its core, ‘predicting’ the most likely next output, not actually performing precise computation. The more fields and the messier the numbers, the easier it is for the AI to make a mistake doing mental math on the fly. Any step that must be precise and consistent every single time should instead be handled by fixed program logic, with the AI responsible only for deciding when to call it.
Q4: Is it okay to just install a ready-made skill file someone else shared?
It’s best to treat it the same way you’d treat introducing a new software package: a skill file can contain code that actually executes, and it may touch local files or API keys already configured in your system. Reading through it and confirming what it actually does before installing is far safer than ‘it sounds convenient, so just use it.’
Q5: Do these practices only apply to Claude products?
According to the original video, this ‘folder plus instruction file’ approach to skills is being pushed as a cross-platform open standard (agentskills.io), and the video also mentions that other Agent platforms, such as OpenAI Codex, work in a similar way. This is a secondhand account from the video’s speaker — this site has not independently verified whether the actual specs are fully identical across platforms — but the judgment principles this article covers (write precise descriptions, keep content lean, don’t let the AI guess at steps that matter) are general engineering thinking, not limited to any single vendor’s tools.
Source Note
This article is based on a video from the YouTube channel ‘IBM Technology,’ published on August 10, 2026, titled ‘5 Best Practices for Building AI Agent Skills’ (presented by Martin Keen and Bri Kopecki), reorganized and told as a narrative rather than translated verbatim. ‘Lin Zhean’ in this article is an illustrative character used for explanation, not a real client; the monthly report demo scenario and the fixes described are an illustratively reconstructed situation, not the case record of any real client. The section stating that a public skill security audit found roughly 35% with security flaws and about 13% with serious issues is the video speaker’s account of some audit; the video itself does not further identify the source, and this site has not independently verified it — it is provided only as a general risk-awareness reference and does not represent the actual proportion for any specific skill repository. The skill file structure described (skill.md, references, and scripts folders) and the line-count/token guidance are also drawn from the original video; actual specifications should be checked against the agentskills.io public standard and each platform’s official documentation. The statement that ‘agentskills.io is a cross-platform open standard’ and that ‘platforms like OpenAI Codex work in a similar way’ is likewise a secondhand account from the video’s speaker, and this site has not independently verified whether the actual specs are fully identical across platforms.
Take Action
Figuring out when an AI Agent Skill should actually be triggered, how much content it needs, and which steps shouldn’t be left to the AI to guess at is really the same exercise as figuring out how many tokens your AI automation is burning through every month — both start with laying the invisible usage out where you can see it, so you know where to draw the line. Try AI Token King for free, and let us lay out exactly how many tokens every agent and every skill on your team is actually using, so you can set the right usage boundaries for your team.
