Agent Skills Engineering: From Tools to Portable Practices

Most agents today call tools. Fewer encode the judgment about when and how to use them. That gap is where skills live.

A tool is a function: give it input, get output. A skill is a workflow: it knows the steps, the quality gates, the gotchas. When an agent has only tools, it reinvents best practices every time. When it has skills, it applies them consistently.

What Skills Actually Are

Think of a skill as an onboarding guide for a new team member. You wouldn't hand a new hire a list of APIs and say "figure it out." You'd give them the process: how to review code, when to escalate, what the architecture decisions were and why.

Skills work the same way. They package:

• Workflows: Step-by-step procedures for complex tasks
• Best practices: Domain knowledge that prevents repeated mistakes
• Quality gates: Validation steps that catch issues before they ship
• Context: When to use this approach and when to avoid it

Key insight: progressive disclosure. Skills don't dump everything into context at once. They load in layers:

1. Metadata (always loaded): Just the name and description. What this skill does and when to use it.
2. Instructions (loaded when triggered): The full workflow and guidance.
3. Resources (loaded as needed): Reference docs, scripts, templates.

This means you can install hundreds of skills without bloating context. Only the relevant ones activate.

How the Big Three Implement Skills

Anthropic's Approach: Filesystem-Based Skills

Anthropic treats skills as directories on a virtual machine. Each skill has a SKILL.md file with YAML frontmatter:

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
---

Without a good description, the skill never triggers. Claude matches your request against it to decide whether to activate. "Extract PDF text" triggers the skill. "Help me with documents" might not.

When triggered, Claude reads the SKILL.md file using bash. Only then do the instructions enter context. If those instructions reference other files, Claude reads those too. Scripts run through bash, and only their output enters context.

This architecture means skills can be comprehensive without being expensive. A skill can include dozens of reference files, but if your task only needs one, that's the only file loaded.

Vercel Eve: Markdown Playbooks with Tools

Eve takes a similar approach but with tighter tool integration. Skills are markdown files in the agent/skills/ directory. Each skill's description appears alongside a load_skill tool.

When a request matches a skill's description, the model calls load_skill, and Eve appends that skill's markdown to the active turn's context.

Interesting: tools stay visible whether a skill is loaded or not. A skill adds instructions, not new execution surfaces. If you need typed runtime behavior, you use a tool instead.

Eve supports both flat markdown files and packaged directories. A flat file can skip the description frontmatter and use the first non-empty line as a weak routing hint. Packaged skills must carry description frontmatter.

Google ADK: Four Patterns for Different Needs

Google's Agent Development Kit offers more flexibility with four distinct patterns:

1. Inline skills: Simple checklists defined in Python code
2. File-based skills: Directories with SKILL.md and optional references
3. External skills: Pulled from community repositories
4. Meta skills: Skills that generate new skills on demand

ADK introduces SkillToolset with auto-generated tools. Frontmatter becomes L1 metadata visible in every call. Instructions become L2, loaded only when the agent decides the skill is relevant.

Meta skill pattern is particularly interesting. You can build a skill that creates other skills based on your needs. It's like having a skill factory that produces exactly what your project requires.

The Skill Orchestrator Pattern

Here's where things get practical. Instead of having agents choose from dozens of skills, you build a single skill that routes to the right one based on context.

Think of it like a senior engineer who knows which specialist to call for each problem. The orchestrator skill:

1. Analyzes the request to understand what's needed
2. Checks available skills to find the best match
3. Loads the appropriate skill with full context
4. Executes the workflow following the skill's guidance

Matt Pocock's /ask-matt skill exemplifies this. It's a router that directs you to the right skill for your situation. Need to grill a design decision? It loads the grilling skill. Want to break work into issues? It loads the issue breakdown skill.

You can build your own orchestrator or use existing ones. For a general project, an existing orchestrator gives you a quick start. As you scale, you'll want one fine-tuned to your specific use case.

Orchestrator pattern has two flavors:

• Pre-hook orchestrator: Runs before the main task to gather context and choose the right approach
• Post-hook orchestrator: Runs after to validate results and apply quality gates

Why Skills Prevent Generic Outputs

Without skills, agents default to generic patterns. They solve problems the same way every time because they have no encoded preferences or constraints.

Skills change this by injecting domain-specific thinking. When you have a skill for code review, it doesn't just check for syntax errors. It knows your team's conventions, your architecture decisions, your common pitfalls.

Paul Bakaus from Renaissance Geek puts it well: "If everybody uses the same skill to do frontend design work, everything ends up looking the same." But that's actually a feature, not a bug, when the skill encodes your organization's specific best practices.

Key: writing skills that capture your unique approach. Not "review this code" but "review this code following our security checklist, checking for the five common mistakes we've made before, and validating against our API conventions."

Writing Skills That Work

Start with the description. It's the most important field because it determines when the skill activates. Include 4-6 natural trigger phrases. "SEO optimization checklist for blog posts" tells the agent exactly when to activate. "A helpful skill" does not.

Keep instructions lean. The SKILL.md body should stay under 500 lines. Move detailed reference material to separate files in a references/ directory. Scripts go in scripts/.

Include examples. Agents reason better with concrete patterns. Show what good output looks like. Show what bad output looks like and why.

Test across agents. One skill should work in Claude Code, Copilot, Cursor, and beyond. If it only works in one agent, you've built a tool, not a skill.

Version your skills. As models improve, your skills need updating. Each new model release is like a student growing from middle school to high school. You have to change the curriculum to get the benefits of the new capabilities.

The Bigger Picture

Skills represent a shift from imperative to declarative agent engineering. Instead of writing code that tells agents what to do, you write skills that tell them how to think.

This matters because agents are becoming more capable but not more consistent. Without skills, better models produce more sophisticated generic outputs. With skills, better models produce more consistently excellent outputs.

Skill orchestrator ties it all together. One entry point that routes to the right knowledge for each situation. Build it yourself for tight integration with your workflow, or use an existing one to move fast.

Either way, you're encoding the judgment that separates good engineers from great ones. And that's portable best practices at their finest.