Topic: AI agents

Agent Skills: Build Verifiable Workflows

Agent Skills matter when they preserve decisions, safety checks, and repeatable verification—not when they merely restate public knowledge in a longer prompt.

Looking at the Agent Skills ecosystem today, it is easy to walk away with two completely opposite impressions.

On one side, an introduction featured on daily.dev describes Skills as an open, cross-tool format for packaging procedural knowledge and loading it on demand. On the other, Reddit recently asked a blunt question: Why do all the Claude Code skill files online seem completely pointless?

Both sides are right.

Agent Skills solve a real problem, but a SKILL.md file does not magically turn ordinary advice into expertise. It tells an agent when to load a particular way of working. Whether that method deserves to be loaded still depends on whether it preserves anything genuinely scarce.

The format solves how content loads, not whether it is good

According to the official Agent Skills specification, a skill needs only a SKILL.md containing name, description, and Markdown instructions. It can also include:

• scripts/: executable code
• references/: supporting documentation
• assets/: templates and other resources

The central idea is progressive disclosure. At startup, the agent sees only each skill’s name and description. It loads the full instructions after deciding that a task is relevant, then reads scripts and reference material only when needed.

This is a sensible design. It keeps every rule from consuming context in every conversation, while making workflows versionable, shareable, and maintainable.

But the format governs the container, not the quality of what goes inside. Putting “write clean code, use meaningful variable names, and remember to test” into a skill still amounts to repeating what the model already knows.

The least useful skill teaches the model what it already knows

Many public skills read like tutorials for beginners. They explain accessibility, REST, or how to split React components. The material may be correct, but the model’s training data probably already contains plenty of it.

These skills tend to share three problems:

1. The trigger is too broad: Touch anything related to frontend or databases and the skill loads, consuming context for little gain.
2. They offer adjectives instead of decisions: They demand “robust,” “production-ready,” and “best practice” work without saying how completion will be judged.
3. They ignore the environment: They overlook the project’s actual scripts, deployment path, compatibility requirements, and failure conditions.

They make the agent read more without helping it guess less.

What deserves to be preserved is usually not public knowledge. It is the detail you have repeatedly paid to learn at work: which check cannot be skipped, which state requires an immediate stop, which source is authoritative, and what evidence must exist at the end.

A good skill preserves decisions and brakes

Consider a release workflow. A weak version says, “Check the code, create a commit, deploy it, and confirm the site works.” Any agent can produce that sentence, but it does not address the places where releases actually go wrong.

A more useful version looks like this:

---
name: safe-release
description: Use when publishing a completed change to the current release branch.
---

1. Read repository instructions and existing deploy scripts.
2. Stop if the worktree contains unrelated changes or conflicts.
3. Run the smallest repository-defined check covering the change.
4. Stage only files created or changed by this task.
5. Use the existing deploy path; do not create a second one.
6. Verify the production URL contains the expected release marker.

None of these steps is sophisticated. Their value is practical: they preserve the boring gates agents are most likely to skip. The skill is not teaching the model what deployment means. It is making sure every deployment begins with a dirty-worktree check, stages only task-owned files, and ends with evidence from production.

The recent paper Authoring Agent Skills: A Software-Engineering Approach treats a skill as a software artifact: the description is the interface that determines whether it activates, while the body and bundled resources are its implementation. That analogy forces two questions more useful than “Is the documentation complete?”:

• Does the agent select the skill when it should?
• Does the skill stay out of the way when it should not run?

A skill is not really verified until both cases have been tested.

Give deterministic work to code and judgment to the model

Anthropic’s original introduction to Agent Skills points out that some operations are better suited to traditional code execution. That boundary matters.

If a parser, schema validator, test, or exit code can decide something, do not spend a paragraph asking the model to “check carefully.” For example:

• Is the frontmatter valid? Use a validator.
• Is an artifact missing? Use a script.
• Did the build succeed? Read the exit code.
• Does the change meet the requirement? Let the agent judge it in context.

That does not mean every skill needs a script to look serious. A script earns its place when a deterministic operation repeats, is easy to get wrong, or would waste substantial context when performed manually. If one existing command solves the problem, use that command.

A skill is guidance, not a security boundary

A skill can influence an agent’s choices, but it cannot guarantee compliance. Writing “do not read secrets” in SKILL.md is not access control.

This matters even more when installing third-party skills. A skill may bundle Python, Shell, or JavaScript code that typically runs with the file and network permissions available to the agent. Red Hat’s Agent Skills security analysis therefore recommends treating skills as a supply-chain concern: review their source and scripts, restrict file permissions, isolate execution, minimize network and tool access, and never embed credentials in a skill.

The official specification includes an experimental allowed-tools field, but not every agent supports it. The real security boundary still belongs in sandboxes, operating-system permissions, human approval, and platform controls—not in natural-language instructions.

An open format does not guarantee identical behavior everywhere

The open Agent Skills format makes the core directory structure and metadata portable across tools. That is a useful starting point. But “can read it” and “will run it the same way” are different promises.

A skill can fail elsewhere as soon as it depends on an agent-specific tool, a fixed directory, an undeclared binary, or implicit permissions. Reusable skills should declare their environment requirements, use relative paths, and fail early when required tools are missing. Cross-tool compatibility should be a test result, not an assumption based on the .md extension.

Seven questions to ask before publishing a skill

1. Does this problem actually recur? A one-off task does not need a skill.
2. Does the description say both what the skill does and when to use it?
3. Does the content preserve a workflow, constraint, or organizational context the model would not otherwise know?
4. Does it define the conditions that require a stop, approval, or report?
5. Do deterministic decisions have a minimal executable check?
6. Are third-party scripts, permissions, and network requirements visible and restrictable?
7. Have both positive and negative activation cases been tested?

If most answers are unclear, do not publish it yet. The material may belong in documentation, a project rule, or a one-time prompt. It does not need to be forced into a skill.

Conclusion: A skill should be a scar, not an encyclopedia

A good skill usually begins with a real failure: a missed migration, someone else’s work overwritten, a deployment never verified, or untrusted input mistaken for an instruction. The team converts that cost into triggers, steps, brakes, and evidence so the next agent does not repeat it.

A bad skill merely stuffs a technical article into the context window and hopes the model becomes more senior.

Agent Skills are worth using, but the measure should not be how many rules they contain. Ask instead: Does this skill eliminate one more guess, prevent one more skipped gate, and leave behind a verifiable result?

External references

• Agent Skills specification
• Anthropic: Equipping agents for the real world with Agent Skills
• daily.dev: What are Agent Skills and How Agents Use Them?
• Reddit: Why are all the Claude Code skill files I see online completely pointless?
• Authoring Agent Skills: A Software-Engineering Approach
• Red Hat: Agent Skills: Explore security threats and controls