How Skill Packages Turn AI Agents into Scenario Experts

Overview

Previous five posts established the Agent runtime skeleton: Loop (iteration), Harness (capability), Context (information start point), Tool Use (action), and MCP (external system integration). A gap remains because a generic Agent does not inherently understand team-specific conventions such as commit message formats or review checklists, leading to token‑inefficient, non‑reusable prompts.

Skill solves this by packaging domain expertise—what to know, when to use it, how to act, and what to output—into a reusable module that can be injected into the Agent's Context, turning a "knows a little about everything" model into a "expert for this scenario".

What a Skill Is

A Skill consists of structured domain knowledge + executable workflow , typically stored in a SKILL.md Markdown file with optional reference.md, examples.md, and scripts/ for validation or transformation. Example directory layout:

code-review/
├── SKILL.md          # main trigger, workflow, output template
├── STANDARDS.md      # optional detailed coding standards
├── examples.md       # optional positive/negative examples
└── scripts/
    └── lint-check.sh # optional deterministic validation script

Skills are persistent, versionable, and shareable across projects, allowing team standards to travel with the code repository.

Progressive Disclosure

Because Skills may contain extensive details, they should not be loaded wholesale. The main SKILL.md holds only the information required for the current task, while deeper content resides in layered files that the Agent reads on demand.

Layer      | What to Put                               | When to Load
-----------|-------------------------------------------|----------------------------
SKILL.md   | Trigger description, core flow, output   | Default when scenario matches
reference.md| Full specs, API details, standards       | When a workflow step explicitly references it
examples.md| Good/bad output examples                | When format alignment is needed
scripts/   | Validation, conversion, analysis scripts | When a step requires deterministic operation

Design Guidelines

Main file should be short – keep SKILL.md under 500 lines; clarity outweighs completeness.

Single‑level references – link directly from SKILL.md to reference.md to avoid nested reads.

Separate summary and details – provide a concise knowledge summary in the main file; full details live in reference.md.

Prefer scripts over inline code – place repeatable commands in scripts/ to save tokens and reduce randomness.

Match loading strategy – multiple Skills load only when matched; each Skill loads its internal layers only when needed.

Skill vs Prompt, Rule, MCP Prompts

The following table clarifies the dimensions where these mechanisms differ:

Dimension   | Prompt                | Rule                | MCP Prompts          | Skill
------------|----------------------|---------------------|----------------------|--------------------------
Granularity | Single task          | Global constraints  | Server‑side templates| Scenario‑level full workflow
Lifecycle   | Disappears with session| Auto‑injected each turn| Available when server connects| Loaded on demand per scenario
Content Focus| "Do X now"           | "Never/Always Y"   | "Which server tasks are available"| "Professional way to do X" (may include multi‑step flow, checklist, output template, tool ordering)
Typical Example| "Fix login.ts null pointer"| "Never commit directly"| "Review MR security checklist"| "Perform code review following team standards"
Location    | User message         | Host static Context| MCP Server           | Host‑side capability module

Rules answer boundary and taboo questions, Prompts answer immediate task requests, MCP Prompts expose server‑side task templates, and Skills provide a deep, scenario‑specific professional approach.

Four Core Elements of a Skill

1. Trigger

The trigger defines when the Skill should be loaded. It lives in the Skill metadata description and must answer WHAT (the task) and WHEN (the conditions), including relevant keywords. Design principles:

Be specific rather than generic (e.g., "extract tables from PDF and fill a form" instead of "process PDF").

Use third‑person phrasing to avoid "I can help..." in the Context.

Avoid over‑triggering; overlapping keywords across Skills can cause the wrong SOP to load.

2. Domain Knowledge

This is the core differentiator from a plain Prompt. It supplies information the model lacks, such as team coding conventions, internal API usage, business terminology, and implicit project consensus. Example snippets:

# Domain Knowledge
- Authentication module must use `src/auth/` and never access DB directly from controllers.
- User status enum: `active` | `suspended` | `deleted` (no `inactive`).
- External payment callbacks must go through `PaymentWebhookHandler`; do not create new endpoints.

Benefits: maintainability (change rules in one place), trimability (load only when needed), and token control (avoid scattering knowledge across multiple steps).

3. Workflow

The workflow breaks a task into executable steps, branches, and checkpoints that map to Loop's Plan → Act cycle. Common patterns include linear lists, conditional branches, tool‑chain orchestration, and feedback loops. Example code‑review workflow:

## Review workflow
1. Read diff and identify change scope
2. Check security items (SQL injection, XSS, key leakage) against STANDARDS.md
3. Verify test coverage for new logic
4. Produce graded feedback (Critical, Suggestion, etc.)
5. If any 🔴 Critical items exist, list mandatory fixes and block merge.

The freedom of a workflow should match task fragility: open‑ended reviews allow higher freedom, while database migrations require strict step‑by‑step execution.

4. Output Format

Specifying the exact shape of the deliverable reduces style drift. Typical formats include markdown report templates, commit‑message conventions, graded annotations, and structured JSON/YAML schemas. Example output template:

# Code Review: [MR Title]
## Summary
[Brief risk overview]
## Findings
- 🔴 **Critical**: ...
- 🟡 **Suggestion**: ...
## Conclusion
[ ] Can merge  [ ] Needs changes

A concrete format enables Harness to automatically verify results during the Reflect stage (e.g., checking for test command output or presence of all Critical items).

Integration with Context and Harness

Skill acts as an on‑demand module within Context; it should not be loaded en masse, mirroring the "few but precise" principle used for Tool Use. Internally, progressive disclosure controls depth, preventing a single load of an entire specification.

Harness discovers, loads, and audits Skills. If a Skill contains script calls or sensitive actions, Harness enforces policy checks. Harness decides what can be run and how many times, while Skill tells the Agent what should be run.

Practical Recommendations

One Skill per scenario (e.g., code-review vs write-commit-msg).

Write a clear description that serves as the trigger (WHAT + WHEN + keywords).

Maintain domain knowledge separately from workflow steps.

Make each workflow step executable with a concrete tool or readable file; avoid vague instructions.

Define verifiable output formats with templates and grading markers.

Use progressive disclosure: keep the main file concise, place details in reference, examples, or scripts.

Version Skills in the repository so new team members inherit the same Agent capabilities.

Separate responsibilities with Rule (global constraints) and Skill (vertical, scenario‑specific process).

Skills transform human expertise into loadable, versioned modules for Agents. The next article will explore Prompt design for ad‑hoc high‑quality interactions when no pre‑existing Skill matches.