Everyone Is Talking About AI Agents. They Should Be Talking About AI Skills.

A practical framework for building reusable, testable, and scalable AI systems

Pixabay

1. Why Skills Matter More Than Agents

Most people building AI systems obsess over agents — who they are, what model powers them, what their persona is.

[embed]Agent Skills Agent Skills are modular capabilities that extend Claude's functionality. Each Skill packages instructions, metadata…platform.claude.com

But here’s a counterintuitive truth:

Skills are more important than agents. An agent without skills is a blank slate — capable of conversation, but incapable of doing anything reliably.

Skills are the unit of repeatable, composable intelligence.

They encode the how of getting things done, while agents simply provide the who to coordinate execution.

Think of an agent like a surgeon, and skills like surgical procedures.

You don’t hire a surgeon because of their personality — you hire them because they can perform specific procedures reliably.

The value of any agent comes entirely from the skills they can execute.

Five Reasons Skills Outrank Agents

• Skills are reusable — the same skill can be called by multiple agents across domains
• Skills are testable — you can validate a skill in complete isolation, without an agent
• Skills are composable — complex workflows are built by connecting simple skills
• Skills are version-controllable — iterate on a skill without touching the agent definition
• Skills outlive agents — agents change; a well-designed skill library persists forever

“Don’t build agents. Build skills. Agents are just the delivery mechanism.”

2. What Is a Skill?

A skill is a standalone, reusable unit of AI-executable work, defined in a SKILL.md file with structured front matter and natural language instructions.

[embed]GitHub - anthropics/skills: Public repository for Agent Skills Public repository for Agent Skills. Contribute to anthropics/skills development by creating an account on GitHub.github.com

A skill answers the question: given this context and these inputs, what exactly should an AI do?

Three Core Properties

• Self-contained — describes one thing, with all context needed to execute it
• Declarative — describes the what and why, not just the how
• Dual-layer — machine-readable front matter + human-readable instructions

Anatomy of a Skill

Every skill lives in its own folder:

my-skill/
  SKILL.md          ← The skill definition (front matter + instructions)
  references/        ← Python / JS scripts the skill invokes
  scripts/           ← Shell scripts

A Minimal Skill Example

---
name: health-task-flag-upcoming-refill
type: task
description: >
  Checks the medication list for any refills due within 14 days.
  Returns a list of medication names and their refill-by dates.
trigger: called-by-flow
risk: safe
---

# Flag Upcoming Refills
Read vault/health/medications/active.md. For each medication,
check the refill_by date. Flag any where:
  refill_by <= today + 14 days
Output format:
- [Medication name] - refill by [DATE] ([N] days remaining)
If no refills are due: return "No refills due within 14 days."

Skill Frontmatter

Front matter is the machine-readable DNA of a skill.

Orchestrators, dashboards, and skill registries parse it to understand what a skill is, who calls it, when it runs, and how it connects to other skills.

Front matter sits between --- delimiters at the top of SKILL.md.

Core Parameters

• name — unique identifier used in tool calls (health-task-lab-review)
• description — one-paragraph purpose, read by tools and other skills
• type — skill category: op, flow, task, or app
• trigger — what activates the skill: cadence, called-by-flow, on-demand
• cadence — for ops only: how often the skill runs (monthly, weekly, daily)
• context — how context window is handled when nested: inherit, fork, reset
• agent — which agent runs this skill
• allowed-tools — restricts which tools the AI can use
• risk — safety classification: safe, unknown, or destructive

The context Parameter — Your Most Powerful Tool

This is one of the most powerful and underused parameters in skill design:

• **inherit (default)** — runs with full conversation history of the caller. Use for short tasks needing prior context.
• **fork** — runs in a new, isolated context window. Enables parallelism. Use for large outputs, parallel flows, independent research.
• **reset** — starts from a completely clean context. Use for fully independent one-shot tasks.

Use context: fork whenever a skill generates large outputs, can run in parallel with sibling skills, or does independent data gathering. Using fork correctly can make your ops 3–10x faster through parallelism.

3. The Four Types of Skills

Skills form a deliberate four-layer hierarchy. Understanding this hierarchy is the single most important architectural concept in skill design.

Layer 1: App Skills — The Connectors

App skills are thin wrappers around external systems.

They define how to authenticate, what data is available, and where to find it.

They contain no business logic — only connection details.

Examples: Fidelity API connector, Apple Health export reader, Stripe webhook handler.

Layer 2: Task Skills — The Executors

Task skills are the atomic units of work — they do one thing and do it well.

Rules: fewer than 60 lines of instructions, no sub-calls, one clear input source, one clear output.

Layer 3: Flow Skills — The Coordinators

Flow skills coordinate a cluster of related tasks toward a specific sub-goal.

They call 2–5 task or app skills, collect their outputs, and synthesize a result.

Example: health-flow-check-refill-dates calls a medication task and an HSA balance app skill, then synthesizes both into a "Upcoming Refills + Cost" summary.

Layer 4: Op Skills — The Orchestrators

Op skills are the highest layer — they run on a cadence, orchestrate multiple flow skills in parallel via context: fork, and produce the final deliverable written to the vault.

They are the "manager" of the skill hierarchy.

---
name: health-op-monthly-sync
type: op
trigger: cadence
cadence: monthly
context: fork
---
# Health Monthly Sync

Run in PARALLEL (context: fork):
  1. Call health-flow-sync-wearable-data     → wellness data
  2. Call health-flow-build-lab-summary      → lab results
  3. Call health-flow-check-refill-dates     → medication status
  4. Call health-flow-build-wellness-summary → wellness score
Aggregate all outputs. Write to vault/health/state.md.

4. Nesting Skills and context: fork

Nesting is the art of building complex, reliable workflows from simple, composable parts.

No skill should do more than one type of thing. If a skill is gathering data AND synthesizing it AND orchestrating other calls, it is doing too much. Break it into the layer that matches its scope.

The context: fork Pattern

When an op calls flow skills with context: fork, each flow receives its own isolated context window — flows run in parallel and their outputs don't accumulate in the op's context, preventing token overflow.

Op Skill (context: fork on all calls)
  |
  ├──[fork]── Flow A  ← isolated context window
  |             ├── Task 1  (inherit)
  |             └── App Skill (inherit)
  |
  ├──[fork]── Flow B  ← isolated context window (parallel)
  |             └── Task 2  (inherit)
  |
  └──[fork]── Flow C  ← isolated context window (parallel)
                └── Task 3  (inherit)

Real Example: Email Marketing Campaign

email-op-weekly-review
│
├─[fork]─ email-flow-analyze-open-rates
│            ├── email-task-pull-campaign-stats
│            ├── email-task-compute-open-rate
│            └── email-app-beehiiv
│
├─[fork]─ email-flow-check-list-health
│            ├── email-task-flag-unsubscribes
│            ├── email-task-flag-bounces
│            └── email-app-beehiiv        ← same connector, reused
│
└─[fork]─ email-flow-plan-next-campaign
             ├── email-task-draft-subject-lines
             ├── email-task-schedule-send-time
             └── email-app-google-analytics

email-app-beehiiv is shared across two flows — same app skill called independently by both, demonstrating reuse without duplication.

5. Complex Workflow Examples

Example A: Personal Financial Review

wealth-op-monthly-synthesis
│
├─[fork]─ wealth-flow-build-net-worth-summary
│            ├── wealth-task-extract-account-balance
│            ├── wealth-task-flag-savings-milestone
│            ├── wealth-app-fidelity
│            └── wealth-app-m1-finance
│
├─[fork]─ wealth-flow-build-cash-flow-summary
│            ├── wealth-task-flag-budget-variance
│            └── wealth-app-monarch-money
│
├─[fork]─ wealth-flow-build-debt-summary
│            └── wealth-task-extract-account-balance
│
└─[fork]─ wealth-flow-analyze-investment-performance
             └── wealth-task-extract-account-balance

wealth-task-extract-account-balance appears in three flows.

Because each runs in a forked context, the task executes independently each time — no shared state conflict.

Example B: HR Onboarding Workflow

hr-op-new-hire-onboarding
│
├─[fork]─ hr-flow-create-employee-record
│            ├── hr-task-validate-employee-data
│            ├── hr-task-generate-employee-id
│            └── hr-app-hris
│
├─[fork]─ hr-flow-provision-system-access
│            ├── hr-task-assign-role-permissions
│            ├── hr-task-flag-missing-license
│            └── hr-app-okta
│
├─[fork]─ hr-flow-setup-payroll
│            ├── hr-task-validate-bank-details
│            └── hr-app-adp
│
└─[fork]─ hr-flow-send-welcome-notifications
             ├── hr-task-draft-welcome-message
             └── hr-app-gmail

Supply Chain Manufacturing: A Complete Skill Architecture

Here’s a production-grade skill architecture for manufacturing supply chain — one of the most complex real-world workflow categories.

The supply-chain-op-monthly-review coordinates four parallel flows: procurement, production scheduling, quality inspection, and shipping.

supply-chain-op-monthly-review           (Op — monthly, context: fork)
│
├─[fork]─ sc-flow-scan-suppliers
│            ├── sc-task-compare-supplier-quotes
│            ├── sc-task-flag-sole-source-risk
│            └── supplier-portal-app
│
├─[fork]─ sc-flow-build-production-schedule
│            ├── sc-task-check-capacity
│            ├── sc-task-flag-bottleneck
│            └── erp-app  ← shared across 3 flows
│
├─[fork]─ sc-flow-inspect-quality
│            ├── sc-task-flag-defect-batch
│            ├── sc-task-calculate-yield
│            └── erp-app  ← shared
│
└─[fork]─ sc-flow-build-shipping-manifest
             ├── sc-task-validate-shipping-address
             ├── sc-task-estimate-delivery-window
             └── tms-app

erp-app is called independently by three flows. Because each flow runs in a forked context, they each get their own isolated ERP connection — no state sharing, no conflict, no coupling.

6. Not All Skills Are Created Equal

The difference between a mediocre skill and an excellent one is the difference between 60% reliability and production-grade autonomy.

• Level 1 — Vague: No structure, no output format. AI makes up answers, inconsistent every run.
• Level 2 — Functional: Has a stated goal. Gets the job done — with gaps and inconsistencies.
• Level 3 — Precise: Clear inputs, outputs, vault paths, edge cases handled. Reliable and consistent.
• Level 4 — Expert: Domain knowledge embedded, failure modes handled, QA built in. Fully autonomous.

7. Common Quality Failures — and Their Fixes

❌ “Review the health data”

→ ✅ “Read health_db. Flag any value outside the reference range column.”

❌ “Generate a summary”

→ ✅ “Generate a 3-section summary: Wellness Score (0–10), Flagged Values, Recommended Actions.”

❌ “Flag any issues”

→ ✅ “Flag any value where actual > upper_range. Label severity: mild (5–10% outside), high (>10% outside).”

❌ “Check the portal”

→ ✅ “Open finance_db for portal URL. Use Playwright headless=False. Extract deductible_used and deductible_limit.”

Every ambiguous word in a skill instruction will be interpreted differently each time the skill runs.

Replace “review,” “analyze,” “check,” and “generate” with exact descriptions of what the AI should do and produce.

Specificity is not micromanagement — it is reliability.

8. Managing and Version Controlling Skills

Skills are code. They should be version controlled, reviewed, tested, and shipped like code.

The Ideal Skill Repository Structure

skills/
  INDEX.md               ← Master index of all skills
  1_ops/                 ← Operation skills (orchestrators)
    health-op-monthly-sync/
      SKILL.md
  2_flows/               ← Flow skills (coordinators)
    health-flow-check-refill-dates/
      SKILL.md
  3_tasks/               ← Task skills (executors)
    health-task-flag-upcoming-refill/
      SKILL.md
  4_apps/                ← App skills (connectors)
    oura-ring/
      SKILL.md

Version Control Best Practices

• Semantic versioning — v1.0.0 → v1.1.0 (new trigger) → v2.0.0 (breaking change)
• Changelog in SKILL.md — add a Changelog section at the bottom of each file
• Branch per skill edit — never edit skills on main; always use a feature branch + PR
• Lint front matter — CI validates YAML front matter schema on every PR
• Test atomic skills — call the skill with fixture data and verify output format

9. The Skill Development Lifecycle

1. Define — write the SKILL.md with front matter and instructions
2. Review — PR review: specificity, vault paths, output format
3. Test — run against fixture data in a demo vault
4. QA — verify output format and edge case handling
5. Ship — merge to main, tag version, update INDEX.md
6. Monitor — track success rate and output quality in production
7. Iterate — improve based on real agent runs and observed gaps

A skill that runs monthly for 3 years executes 36 times.

If it’s 80% correct each run, that’s 7 bad outputs per year — compounding errors in your vault.

The investment in a Level 4 skill pays dividends every single run

10. Skill Marketplaces

Just as developers share code on npm or PyPI, the emerging skill ecosystem enables AI builders to share, discover, and sell skills.

Where Skills Are Bought and Sold Today

• skills.sh Open agent skills directory and marketplace
• ClawHub Versioned registry and marketplace for AI agent skills
• prompts.chat Skills Public catalog for reusable agent skills

Skills are the atoms of AI intelligence. Build them well. Share them freely. Sell the premium.

Thank you for being a part of this Tech, Data & AI community!

🧑🏻‍💻 Before you go:

• Loved this article ❤️? Share it on Linkedin and **tag me**!
• Did you know that you can “Clap” up to 50 times in Medium?
• Click the clap icon (👏) and hold it down; give anywhere from 1 to 50 claps.
• Discover more at: **Fru.dev | DEVeloping the FUTURE! **🚀