Skill Design Reference

Skill Design Reference

Purpose

Use this reference when designing a new Skill. A Skill is a reusable workflow package for the main Agent. It explains when the capability applies, which tools it may use, how steps depend on one another, where user confirmation is required, and what structured result returns to the main Agent.

A Skill is not a database, not a replacement for a deterministic service, and not a replacement for a stateful workflow engine.

Required package shape

Every Skill package must contain a root SKILL.md:

skills/<skill-name>/
├── SKILL.md                 # required entry point
├── scripts/                 # optional deterministic executable helpers
├── references/              # optional detailed documentation
└── assets/                  # optional templates and static resources

Keep the root package small. Load detailed material from references/ only when the workflow needs it.

SKILL.md frontmatter

The frontmatter must contain:

---
name: skill-name
description: One sentence explaining what the Skill does and when to use it.
---

Rules:

• Use lowercase kebab-case for name.
• Make description specific enough for the Agent to decide whether to load the Skill.
• Mention the user request or capability that triggers the Skill.
• Do not put implementation details, credentials, or long workflow text in frontmatter.

Recommended body sections

Use only sections that improve execution. Complex Skills normally include:

# Purpose
# When to use
# When not to use
# Required context
# Workflow
# Tool usage
# User confirmation points
# Failure and recovery
# Output contract
# Security boundaries
# Examples

The body is progressively disclosed: the Agent reads the frontmatter first, loads the Skill when relevant, and reads referenced documents only when required.

Workflow design

Describe steps in execution order. For every step specify:

• input and output;
• dependency on earlier steps;
• how success is verified;
• what happens on failure;
• whether the user must make a decision;
• whether the step can be retried safely.

Example:

1. Read the task-relevant CareerProfile projection.
2. Build the explicit keyword and optional city.
3. Call `open_job_search` once.
4. Deliver the browser navigation action and end the turn.
5. Let the user browse normally and explicitly save a JD with the browser extension.
6. Use saved-job tools only after that separate save succeeds.

Do not describe a workflow without stating its stop conditions. A Skill must say when it is complete, when it waits for the user, and when it returns a failure.

Tools and MCP coordination

A Tool is one structured action. A Skill may coordinate multiple tools or MCP servers.

Skill
├── profile.get_projection
├── open_job_search
├── find_saved_jobs
├── get_saved_job
├── resume.match
└── resume.save_after_confirmation

Pass data between tools through explicit schemas. Prefer identifiers and compact summaries over raw responses:

research → run_id + candidate summaries
user selection → run_id + result_ref
select → JDAnalysis summary + selected job reference
resume.match → resume_id + JDAnalysis

For multi-tool workflows document:

• which steps are sequential;
• which independent steps may run in parallel;
• how errors from one server affect later steps;
• what data may cross each boundary;
• the final stop/confirmation point.

Do not let a Skill invent opaque external IDs. The receiving Gateway or Tool must validate ownership and resource membership.

Scripts

Use scripts/ for deterministic, bounded helpers such as:

• schema validation;
• file type and size checks;
• normalization;
• format conversion;
• report rendering;
• quality checks.

Scripts must be non-interactive by default, accept structured flags or stdin, write machine-readable results when requested, and return non-zero exit codes on failure. Do not hide the primary state machine in a script when the project already has a Gateway or workflow implementation.

References

Use references/ for long material that should not be loaded on every Skill invocation:

• tool contracts;
• domain rules;
• error code tables;
• quality criteria;
• provider-specific notes;
• extended examples.

The root SKILL.md should link to the reference file and state when to read it.

Assets

Use assets/ for static resources:

• output templates;
• JSON schema examples;
• report layouts;
• prompt fragments that are intentionally versioned with the Skill.

Never store secrets, user credentials, cookies, or unredacted private user data in a Skill package.

Main Agent, Skill, Tool, workflow, and subagent

Use these boundaries:

Main Agent
├── reads CareerProfile and conversation state
├── selects a Skill or a simple Tool
├── handles ambiguity and user confirmation
└── stores a compact cross-step task cursor

Skill
├── describes a reusable multi-step capability
├── coordinates tools and optional subagents
├── defines stop conditions and recovery
└── returns a compact structured result

Tool / Gateway
├── performs one bounded action
├── validates schema and authorization
└── owns deterministic side effects and external boundaries

Workflow engine (for example LangGraph)
├── enforces state transitions
├── pauses and resumes
├── bounds retries and timeouts
└── preserves execution trace

Subagent
├── handles an isolated, potentially long analysis
├── receives a minimal task package
└── returns a structured result, not hidden global state

A Skill does not automatically require a subagent. Opening a recruitment search page remains an atomic client-navigation Tool. A long JD analysis, resume tailoring, OCR pass, or independent review may use a subagent.