How to Build AI Agent Skills That Actually Work

Remember when we all spent hours crafting custom GPTs, only to watch them gather digital dust because they were locked inside ChatGPT forever? Yeah, me too. Turns out there's a better way, and it's already here.

Nufar Gaspar just walked through a masterclass on agent skills—the portable, markdown-based playbooks that tell AI tools how to do what you actually need them to do. This isn't theory. According to Gaspar, 44 tools now support skills, from Claude to Cursor to GitHub, with new ones joining weekly. The format is human-readable, transferable, and increasingly standard. Which means we might finally have something that survives the next platform shift.

The core concept is straightforward: skills are folders containing instructions, scripts, and resources that agents can either discover automatically or that you trigger manually. "They work in two modes," Gaspar explains. "An agent can discover the skills that you enabled in the environment and it can do so automatically and invoke them on its own or us humans can trigger them manually." Say "research this topic," and a properly configured skill fires—not a generic research process, but your specific methodology.

When Building Makes Sense (And When It Doesn't)

The obvious triggers: you've done something more than three times, you keep pasting the same instructions, or you need consistent output. But Gaspar pushes further. Skills aren't just efficiency tools—they're standardization opportunities. Want your team to approach competitive analysis the same way? Build a skill. Want to finally tackle research projects you never had bandwidth for? Build a skill.

The harder question is whether to build or reuse. Gaspar is refreshingly direct here: "I would advise to lean on more heavily towards building at this day and age." The marketplaces exist—OpenClaw has plenty, as does Anthropic's skill repo—but finding the exact fit often wastes more time than just building your own. Plus, since these are markdown files, you can treat downloaded skills as templates rather than finished products. Change what doesn't fit.

One exception worth noting: Anthropic recently released a skill creator tool that interviews you to extract expertise, runs evaluations, and does A/B testing. If you're a Claude user, that's worth exploring. Otherwise, understanding the anatomy of effective skills matters more than any specific tool.

The Anatomy That Actually Matters

The most critical component? The trigger. "It's probably the most important line because if your trigger is not very precise or very specific, then your skill will just not be used and selected by the agent," Gaspar notes. Make it loud, not subtle. Models skip past subdued descriptions. Be explicit about when this skill should fire.

The body should read like a playbook—numbered steps or bulleted lists, not prose. AI tools "really like structured instructions dramatically because that will also turn to be their action plan if it's very very concrete." But here's where nuance matters: prescriptive steps work for fragile tasks like database migrations. Creative tasks need guidance with room to breathe. Over-railroad the model and results suffer.

Include output formats—better yet, include output examples. Show the model a table structure, not just a description of one. Document sections, not just "make it look professional."

Then there's the section most people skip: the gotcha. "This is probably the highest signal content in any skill," according to Gaspar, "because it's the area where gets the model to go out of its own patterns." Document where the model typically goes wrong. What assumptions does it make that it shouldn't? Every failure you encounter should end up here. Frame it directly: "I know you want to do X but don't. Here's why."

What Kills Skills Dead

Weak triggers top the list. If the agent can't identify when to use your skill, the skill doesn't exist—at least not functionally. Overdefining process kills skills too. So does stating the obvious. Don't waste tokens telling the model things it already knows.

Skipping the gotcha section means accepting suboptimal results. And cramming everything into one monolithic file instead of using folder structure? That's the encyclopedia approach when you need a playbook. Keep skills under 500 lines. Move reference materials to separate files within the skill folder. Put long input/output examples in their own examples.md file.

The decision on what stays bundled versus what gets referenced externally is practical: if it's context specific to this skill that should travel wherever the skill goes, bundle it. If it's general information about you or your company, point to external sources.

The Security Reality Nobody Wants to Discuss

Here's the part that matters for anyone downloading third-party skills: they're code. They can execute with your agent's permissions. "If you download that it can execute scripts and sometimes it can be a malicious script," Gaspar warns. Treat downloaded skills like any software package. Read them carefully. Verify the source. Don't install unvetted skills on work machines.

This isn't hypothetical paranoia—it's basic security hygiene in an ecosystem moving fast enough that best practices haven't fully formed yet.

Skills Worth Building Now

Gaspar walked through four practical examples that most knowledge workers could use. A research skill with built-in fact-checking methodology that compares sources and assigns confidence scores. A devil's advocate skill that stress-tests proposals while explicitly looking for blind spots and biases—both yours and the AI's—then ends with constructive alternatives.

A morning briefing that pulls priorities, calendar, pending items, and relevant news while binding to your personal context files. And a board of advisors skill that simulates multiple expert perspectives—not just "think like a CFO" but a structured set of viewpoints tailored to your actual decision-making needs.

The meeting prep example Gaspar detailed goes deeper: it identifies attendees, collects context, analyzes the agenda, runs scenario analysis (what could go wrong), and generates a structured brief. Nested within it is another skill that simulates the meeting itself with six or seven difficult scenarios. Someone with a hidden agenda. Tough questions. Sales objections. You prep for meetings by literally practicing them.

The Pattern That's Emerging

Skills are becoming the standard way to extend AI tools because they solve the portability problem that plagued custom GPTs and gems. They're not locked to platforms. They're human-readable, which means your team can actually understand and modify them. And they're spreading fast enough that betting against them feels unwise.

Whether this becomes the standard or just another format that fragments over time—well, I've been around long enough to know that promising standards can splinter. But right now, with 44 tools supporting them and more joining weekly, the momentum is real. And unlike previous waves of AI customization, the barrier to entry is low enough that individual users can actually participate.

The question isn't whether skills are useful. They clearly are. The question is whether organizations will adopt them systematically or whether they'll remain individual productivity hacks. Gaspar's betting on the former—hence the talk of organizational skill libraries, governance, and versioning.

Maybe this time really is different. Or maybe we're just in the early euphoria phase before reality sets in. Either way, the tools exist now, the frameworks are solid, and the portability is genuine. That's more than we had with most previous attempts to make AI tools actually useful.

—Mike Sullivan, Technology Correspondent