How to Create Agent Skill

Creating an agent skill is not the same as saving a favorite prompt. A useful skill packages a repeatable workflow so an agent can discover it, load only the instructions it needs, use supporting files when they matter, and produce work that can be checked after the run.

The common shape is now fairly stable across agent products. OpenAI Codex skills are directories with a required SKILL.md plus optional scripts/, references/, assets/, and other supporting folders. Anthropic's Agent Skills docs describe the same package pattern: instructions, metadata, and optional resources that Claude can use when relevant. The Agent Skills specification also centers the format on a folder containing SKILL.md with YAML frontmatter and Markdown instructions. VS Code, GitHub Copilot, Cursor, Claude Code, and Codex now all point in the same direction: skills are portable, file-based operating procedures for agents.

That portability raises the bar. If the skill is vague, the agent may load it at the wrong time or turn it into generic advice. If the skill is bloated, it wastes context and hides the decision path. If the skill has no tests or feedback loop, the author cannot tell whether it actually improved agent behavior. For the broader concept, see what an agent skill is in AI; the practical work starts with choosing one job.

Start with a task that already happens more than once. A good first skill is a workflow you currently explain in Slack, paste into a prompt, document in a checklist, or hand to a contractor. It should have recognizable inputs, a preferred sequence, and visible completion evidence.

Avoid category-sized skills:

Too broad	Skill-shaped
"Do frontend work"	Convert a static product screenshot into a responsive React screen using the local design system
"Review code"	Review a pull request for analytics event regressions and missing verification
"Analyze data"	Build a weekly churn-risk table from exported account events and flag accounts needing follow-up
"Test the app"	Run a checkout QA pass across happy path, decline, retry, and receipt states

The difference is operational specificity. "Review code" gives the agent almost no routing information. "Review a pull request for analytics event regressions" tells the agent what files to inspect, what failure modes matter, and what evidence to return.

Use this contract before writing the skill:

For [user or team], use [inputs] to perform [repeatable workflow],
stop when [blocking condition], and return [evidence of completion].

Examples:

• For a product engineer, use a PR diff and analytics taxonomy to find event regressions, stop if the taxonomy is missing, and return severity-ranked findings with file paths.
• For a data analyst, use a CSV export and metric definition to produce a cleaned chart and caveat list, stop if required columns are absent, and return the transformation steps.
• For a design engineer, use a Figma screenshot and component inventory to implement one screen, stop if the design system is unavailable, and return changed files plus viewport checks.

If the workflow cannot fit that sentence without commas doing too much work, split it. A frontend implementation skill, a design QA skill, and an accessibility audit skill can share references, but they should not be one giant skill.

SKILL.md is the entry point. It needs metadata the agent can match against the user's task and body instructions the agent can follow after loading the skill. In Codex, the name and description are part of the initial matching surface before the full file is read; OpenAI notes that the full instructions are read only after Codex selects the skill. GitHub's Copilot docs make the same point from another angle: Copilot decides when to use a skill from the user's prompt and the skill description, then injects SKILL.md into context.

A strong description says when to use the skill and what kind of work it performs. A weak description merely names a domain.

---
name: analytics-pr-review
description: Review pull requests for analytics instrumentation regressions, event taxonomy mismatches, missing tests, and release-blocking tracking risks.
---

# Analytics PR Review

Use this skill when a pull request changes product flows, tracking calls,
event schemas, dashboards, experiments, checkout, signup, onboarding, or
other behavior that may affect analytics.

## Required inputs

- PR diff or changed files
- Event taxonomy or tracking plan
- Product area and expected user flow

## Workflow

1. Read the changed files before inspecting unrelated code.
2. Identify added, removed, renamed, or relocated events.
3. Compare each event name, payload, and trigger condition with the taxonomy.
4. Check tests, storybook states, analytics fixtures, or manual verification.
5. Return findings by severity with file paths and reproduction steps.

## Stop rules

- Stop if the diff is unavailable.
- Ask for the event taxonomy if the task requires taxonomy validation.
- Do not invent approved event names.

## Output

Return findings first. Include severity, path, issue, evidence, and suggested fix.
If no issues are found, say so and list residual verification risk.

This is enough for a first useful version. The skill does not need an essay about why analytics matters. It needs trigger conditions, inputs, order of operations, stop rules, and output shape.

For authoring guidance beyond the file skeleton, how agent skill works covers discovery and execution mechanics, while five agent skill design patterns compares checklist, research, implementation, QA, and orchestration patterns.

Progressive disclosure is the key design constraint. Anthropic's engineering write-up on equipping agents for real-world work with Agent Skills frames skills as layered context: metadata first, core instructions next, detailed supporting files only when needed. Anthropic's product docs show the same loading model: skill metadata is available up front, SKILL.md is read when the skill is triggered, and additional bundled files can be read as needed.

That means SKILL.md should act like a table of contents and operating procedure, not a full binder. Put the invariant workflow in SKILL.md. Put long rubrics, examples, datasets, fixtures, templates, and tool-specific notes in supporting files.

A practical layout:

analytics-pr-review/
  SKILL.md
  references/
    event-taxonomy-rubric.md
    severity-model.md
  examples/
    good-finding.md
    no-issues-review.md
  scripts/
    collect_changed_events.ts
  assets/
    review-template.md

Use references/ for material the agent may need to read. Use examples/ for output shape and edge cases. Use scripts/ for deterministic or repetitive work. Use assets/ for templates, starter files, prompt fragments, or reusable forms.

The tradeoff is maintenance. Every additional file can help the agent, but every additional file can drift. A 15-line severity rubric that authors keep current is better than a 60-page policy dump. When a reference is required for correctness, say so in SKILL.md: "Before rating severity, read references/severity-model.md."

Scripts are best when the operation is mechanical, repeatable, and easy to verify. A model can inspect a diff, but a script is better at extracting event names, checking JSON schemas, counting changed routes, normalizing CSV columns, or comparing generated files against a fixture.

Good script candidates:

• scripts/extract_events.ts scans changed TypeScript files for track(...) calls.
• scripts/check_frontmatter.mjs validates that blog posts preserve required metadata.
• scripts/profile_dataset.py reports missing values, duplicate keys, and column types before data analysis.
• scripts/screenshot_viewports.ts captures desktop and mobile screenshots for a frontend QA skill.

Bad script candidates are the ones that hide judgment. Do not bury severity decisions inside an opaque script if the author expects the agent to reason about product impact. A safer pattern is "script produces evidence; agent decides and reports."

Assets should be similarly narrow. A frontend/design skill can include a component map and viewport checklist. A code-review skill can include a finding template. A data-analysis skill can include a chart-spec template and metric glossary. A QA skill can include a browser matrix and fixture accounts. If an asset is not used in the first three realistic runs, remove it or move it to project docs.

A frontend/design skill needs visual and implementation constraints. It should name the design source, component library, responsive breakpoints, acceptance screenshots, and what counts as done. For example: "Implement a pricing comparison screen from a Figma frame using existing Button, Tabs, and Card components; verify 390px, 768px, and 1440px screenshots; do not introduce a new color scale."

A code-review skill needs severity, evidence, and non-goals. It should say whether the agent is reviewing security, performance, analytics, migrations, or product behavior. It should require file and line references, ask the agent to lead with findings, and explicitly allow "no findings" when appropriate. That keeps the review from becoming a style critique.

A data-analysis skill needs a data contract: required columns, allowed transformations, charting conventions, caveat rules, and privacy limits. If the agent should inspect data quality before analysis, put that early.

A QA skill needs environment setup, user journeys, accounts, pass/fail evidence, and stop rules. A useful checkout QA skill might cover card success, card decline, network retry, tax calculation, receipt email, and webhook reconciliation. It should also say what the agent must not do, such as changing production data or running destructive cleanup without approval.

These examples share a pattern, but they should not share one SKILL.md. Skills work best when each file teaches one job deeply enough that the agent can start without a long clarification exchange.

Test whether the skill is selected for the right prompt and ignored for adjacent prompts. The GitHub Copilot docs emphasize that skill choice depends on the prompt and description; Claude Code also supports explicit invocation, but automatic selection still depends on relevance. "Use for frontend work" may trigger for too many tasks. "Implement responsive product screens from Figma screenshots using the local design system" has sharper boundaries.

Run at least five probes:

Probe	Example	Pass signal
Direct match	"Review this PR for analytics regressions"	Skill loads and follows its workflow
Adjacent task	"Refactor this analytics helper"	Skill does not hijack implementation work
Missing input	"Check tracking, but no taxonomy is available"	Agent asks or stops instead of inventing
Blocker case	Repo cannot run tests	Agent reports the blocker and residual risk
End-to-end task	Real PR, real dataset, or real screenshot	Output includes evidence a reviewer can inspect

Then test execution with realistic artifacts. Do not test a data-analysis skill on a perfect three-row CSV unless users analyze perfect three-row CSVs. Do not test a frontend skill on an empty app if real tasks involve an existing design system and brittle CSS. Skills fail in the handoffs: missing files, outdated references, ambiguous ownership, half-configured tools, and user requests that conflict with the workflow.

Record failures as skill defects. "The agent forgot mobile screenshots" is not merely an agent mistake if the skill never made viewport evidence mandatory. "The agent invented event names" is a skill defect if the stop rule did not require a taxonomy. Skillfully's guide to measuring agent skill quality goes deeper on tracking selection accuracy, task completion, correction rate, and user feedback after real runs.

Version the skill like a small software package. Keep release notes when behavior changes. A typo fix is not the same as changing stop rules, adding a script dependency, or broadening the trigger description.

Distribution depends on where the skill will run:

• For Codex, package the folder with SKILL.md and supporting directories as described in the Codex skills docs.
• For Claude Code, place or install the skill where Claude Code can discover it, then use the documented skill invocation behavior from Claude Code skills.
• For GitHub Copilot, follow the repository or organization placement rules in GitHub's agent skills documentation.
• For VS Code and Cursor, follow their Agent Skills docs and keep the folder layout portable unless a platform-specific feature is worth the lock-in.

The install path should be dull: copy a folder, verify SKILL.md, run any setup script, run a smoke task, and confirm the agent can discover the skill. If a skill requires credentials, state the environment variables and least-privilege permissions. If it runs scripts, state the runtime assumptions: Node version, Python version, package manager, browser dependencies, or shell commands.

The first version of a skill is a hypothesis. The evidence comes from runs.

Track a small set of measures:

Measure	What it reveals
Selection accuracy	Whether the description triggers on the right tasks
Clarification rate	Whether required inputs and blockers are clear
Completion evidence	Whether outputs include files, commands, screenshots, citations, or checks
Correction rate	Whether users have to fix the same omission repeatedly
Reference usage	Whether the agent reads the intended supporting files
Maintenance drift	Whether scripts and references still match the current workflow

Feedback should be close to the run. A simple rating plus a text note can be enough if it captures what happened: wrong skill, missing source, poor stop behavior, weak output, outdated script, or strong completion. If three users correct the same output shape, patch the skill. If the agent loads the skill for adjacent tasks, tighten the description. If the agent skips a critical reference, move that reference into the required workflow or shorten it.

Before publishing, check the skill against this list:

• One repeatable workflow, not a domain.
• Specific description that says when to use the skill.
• Required inputs and blockers named early.
• Workflow steps ordered by the way the job should actually happen.
• Stop rules for missing access, missing files, unsafe actions, and uncertain facts.
• Output shape with evidence requirements.
• Supporting files split by progressive disclosure.
• Scripts limited to mechanical work with inspectable output.
• At least one realistic happy-path test.
• At least one missing-input or blocker test.
• Version notes for behavior changes.
• A feedback path for measuring run quality.

The practical standard is simple: a skilled teammate should be able to read the package and say, "Yes, this is how we do that job here." If the skill reaches that level, the agent has more than a prompt. It has a maintained workflow it can reuse, inspect, and improve.