An agent skill is a small, versionable package that teaches an AI agent how to perform a particular kind of work. It usually begins with a SKILL.md file and may include scripts, reference material, examples, or templates. The agent sees a short name and description first. It loads the full instructions only when the current request calls for them.

The problem a skill solves

A normal prompt helps once. A permanent instruction file affects almost every turn. A skill sits between those two. It keeps a repeatable procedure available without making the agent carry that procedure through unrelated work. This matters when the procedure is longer than a reminder, when several people need the same approach, or when a task depends on files that should travel with the instructions.

Good candidates include release-note writing, accessibility review, customer-research synthesis, incident diagnosis, or a company-specific deployment sequence. “Be helpful” is not a skill. “Turn merged pull requests into customer-facing release notes, grouped by product area and checked against the public changelog” is.

What belongs in the package

  • Name and description: the routing layer that tells the agent what the skill does and when it should load.
  • Instructions: the procedure, boundaries, inputs, expected output, and finish conditions.
  • References: longer policies, schemas, examples, or domain notes that are useful only during the task.
  • Scripts: deterministic helpers for work that should not depend on prose interpretation.
  • Assets: templates or starter files the agent should reuse rather than recreate.

How activation works

Modern skill runtimes use progressive disclosure. The host advertises the skill metadata, compares the user’s request with the description, and loads the full body when there is a match. Most hosts also support explicit invocation. Claude Code exposes skills as slash commands. Codex can select a skill explicitly with $ or through its skills menu. Gemini CLI and Grok expose their own skill commands and discovery paths.

The description is therefore operational, not promotional. Name the job, the inputs, and the trigger language a user would actually use. Avoid descriptions broad enough to collide with every task. If the skill should never activate automatically, use the host’s documented opt-out field rather than vague prose.

Skill, prompt, rule, or tool?

Use a prompt for a one-off request. Use AGENTS.md or the host’s permanent instruction file for rules that always apply. Use a skill for an occasional procedure. Add a tool or MCP server when the agent needs typed access to an external system. A skill can explain when and how to use a tool, but instructions alone do not create new permissions or capabilities.

A useful first build

  1. Choose one repeated job with a visible result.
  2. Write three realistic requests that should activate it and three nearby requests that should not.
  3. State the required inputs and what to do when one is missing.
  4. Describe the smallest sequence that produces the result.
  5. Add a finish check someone other than the author can understand.
  6. Run the same scenarios without the skill and compare the outputs.

SkillForge turns that work into a visual editing loop. You can describe the job in ordinary language, compare the draft with a protected example, explain why a passage works, and download the result as an ordinary SKILL.md. The file remains portable; the host still decides how and when to load it.