Agent Skills

Agent skills are reusable harness extensions that package task-specific instructions, trigger logic, optional tools, and supporting references so an agent can specialize without changing the base model.

Why this matters

Skills are one of the cleanest ways to turn a general-purpose model into a useful working system. They let builders encode repeatable behaviors, workflows, and tool patterns without relying on the model to rediscover those conventions from scratch on every run.

The important distinction is that a skill is not just a prompt snippet. It is a small operating bundle with:

• a trigger surface that tells the agent when to use it
• instructions that shape behavior once loaded
• optional scripts, references, and assets that extend what the agent can do

A newer Cursor runtime source adds a useful systems boundary: skills are not the same thing as runtime control planes. A skill defines procedural memory and task behavior, while the surrounding SDK or agent platform decides execution location, model configuration, cancellation, event streaming, artifact exposure, and conversation-state persistence.

A newer Codex tutorial adds a practical bridge between raw prompting and full skills: repeated planning prompts, build prompts, and refinement prompts often act like proto-skills before they are formalized. That matters because many good skills are discovered by noticing which prompt shapes keep producing clean plans, predictable first builds, and legible refinement loops.

A newer Claude-skills source sharpens the context-efficiency argument. Skills work because they use progressive disclosure: the agent usually sees only the name and trigger description, then loads the full instructions and references only when the task calls for them. That makes skills a better home for repeatable workflow behavior than stuffing every convention into an always-loaded AGENTS.md or CLAUDE.md file.

A newer agent-building course adds the practical creation loop: skills should usually be extracted from a successful run, not invented cold. The operator teaches the agent the workflow step by step, observes where it fails, corrects the run, then packages the working sequence as a skill. Later failures become inputs to revise the skill instead of one more ad hoc prompt.

A newer AI super-app update source adds a distribution angle: reusable workflow components are moving from private local files toward shareable team assets inside agent platforms. The durable point is not the current state of any one product's plugin UI. It is that skills and plugins are becoming organizational infrastructure, so trigger quality, ownership, review, and portability matter more as more people can invoke the same behavior.

A newer Garry Tan / gstack source adds a clean architecture rule for this page: skills should be fat with process and judgment, while the harness stays thin and general. Skill files are most valuable when they encode how to investigate, compare, review, or decide, not when they merely store static content. Resolvers then become the routing layer that decides which skill or reference should be loaded for a task.

Core thesis

The strongest ideas in this source are:

• skills are durable harness-level specialization mechanisms
• the trigger description is often more important than the body instructions
• good skills constrain outcomes and boundaries rather than micromanaging every step
• reference material, scripts, and assets should be loaded in layers rather than dumped into one giant instruction file
• skills need evals, including negative trigger cases, because bad triggering can be as harmful as bad task execution
• productizable systems often work best when capabilities are packaged as reusable skills while user-specific preferences stay outside those shared capability bundles
• skill quality in production depends as much on finding the right skill as on executing it once found
• mature skill systems often expose command-like entry points that map common user intents onto the right underlying skills automatically
• skills can call plugins, CLIs, or other tools, but they still need a separate runtime layer to manage run lifecycle, state, and artifacts
• a strong agent product often pairs stable skill bundles with programmable runtime controls rather than trying to encode runtime behavior inside the skill itself
• planning-first prompts are often the earliest reusable form of procedural memory, especially in coding workflows where assumptions need review before mutation
• a good proto-skill usually captures both the sequence and the constraint, for example: clarify scope, stay read-only first, check assumptions, implement only after approval, then preview and refine
• progressive disclosure makes skills a context-management tool, not only a workflow convenience
• the best personal or business skills usually come from observed successful runs, because that gives the skill concrete examples of what "done right" looks like
• skill improvement should be recursive: failure -> diagnosis -> corrected run -> skill update, with the operator approving durable changes
• global skills should be reserved for broadly reusable behavior, while project-level skills should hold narrow customer, department, or workflow-specific procedure
• shared skills and plugins need stronger review discipline because one bad trigger or stale workflow can now affect a whole team
• fat skills should carry reusable judgment and process, while deterministic exactness belongs in tools and runtime policy belongs in the harness

Framework / model

1. A skill has layered structure

The source defines a simple but important layout:

my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/

This yields three distinct layers:

• frontmatter: the skill name and description, which shape activation
• instruction body: the task guidance that loads after triggering
• supporting files: scripts, references, and assets loaded only when needed

2. Trigger design is the real control surface

The description field is not metadata. It is the activation mechanism.

A good description must answer both:

• what the skill does
• when it should be used

3. Lean loading beats giant monoliths

The practical loading stack is:

1. always-loaded trigger metadata
2. instruction body loaded on activation
3. references, scripts, and assets loaded only on demand

4. Skills and runtimes solve different problems

The Cursor cookbook adds a durable design distinction:

Skill layer

Defines:

• task framing
• workflow rules
• output conventions
• reusable examples
• procedural guidance

Runtime layer

Defines:

• local versus cloud execution
• model selection
• cancellation behavior
• streamed event visibility
• artifact access
• conversation-state persistence
• CLI or dashboard entry surfaces

This is useful because many agent systems become hard to reason about when skill logic and lifecycle control are blended together.

5. Skills should define goals and constraints, not full runtime policy

A skill should usually specify:

• what outcome is desired
• what boundaries matter
• what artifacts should be produced
• what references or tools are likely useful

It should not usually be responsible for:

• which host the run executes on
• whether the run is cloud or local
• how cancellation works
• how streamed telemetry is surfaced
• how many parallel runs are grouped on an operations board

Those are runtime concerns.

6. Repeated planning prompts are often proto-skills

The beginner Codex tutorial adds a useful operator pattern that belongs here.

Before a workflow becomes a formal skill, it often appears as a repeated prompt family such as:

1. turn idea into a V1 product spec
2. stay in plan mode and surface assumptions
3. build the first version from the approved spec
4. get the first working result on screen
5. recommend the next small improvements without increasing scope too much

This matters because the jump from prompting to skill creation is usually not conceptual. It is editorial. The operator notices that the same prompt scaffold keeps producing good work and packages it.

7. Good coding skills often preserve phase boundaries

Another durable lesson from the tutorial is that skill quality often depends on preserving phase boundaries explicitly.

A strong coding skill or proto-skill may specify:

• start read-only when product shape is unclear
• ask clarifying questions before coding when assumptions are unstable
• produce a concise implementation plan
• prefer visible first results over abstract overengineering
• refine from previewed behavior rather than speculative redesign
• keep scope bounded during early passes

This is useful because many bad coding runs fail not for lack of capability, but because the workflow collapsed planning, implementation, and refinement into one muddy request.

8. Build skills from successful runs

The newer skill sources add a useful operating rule: do not write a large skill before the workflow has proven itself in practice.

A stronger sequence is:

1. identify a repeated workflow
2. run it manually with the agent while narrating the steps
3. correct the agent when it misses criteria, tool calls, or handoff details
4. repeat until the run succeeds
5. ask the agent to package that successful run into a skill
6. update the skill only after later failures reveal a real reusable correction

This matters because a cold-written skill often encodes the operator's theory of the workflow. A skill extracted from a working run encodes the workflow's actual tool calls, checks, and failure cases.

9. Skill scope should match reuse scope

The same sources add a useful scoping distinction:

The practical rule is: promote behavior upward only when it repeats. Keep narrow context close to the project so the broader agent environment stays clean.

Important examples / reference points

• Shared team-facing skills are useful because they standardize artifact shape and workflow quality.
• Planning-first coding prompts are useful because they show how proto-skills emerge from repeated successful threads.
• Cursor-style programmatic runtimes are useful because they show where skill boundaries end and control-plane boundaries begin.
• The Codex beginner tutorial is useful because it demonstrates how a repeatable prompt family can evolve into a reusable build-and-refine skill for small application work.
• The Claude-skills source is useful because it explains progressive disclosure, context-token savings, and why workflow behavior usually belongs in skills rather than always-loaded project files.
• The agent-building course is useful because it shows skill creation as an employee-onboarding loop: teach the process, run it, correct it, then package it.

Failure modes / limitations

Putting too much runtime policy into the skill

A skill becomes brittle when it tries to encode operational details that belong in the surrounding platform.

Assuming a runtime API removes the need for skills

Programmatic agent execution still needs reusable procedural memory, trigger quality, output standards, and task-specific constraints.

Over-triggering broad skills in tool-rich environments

As runtime capability expands, bad skill activation can become more expensive because the agent can do more once the wrong instructions are loaded.

Treating one good prompt as a finished skill too early

A repeated prompt may still depend on hidden operator judgment. Formalize it too quickly and you can freeze a brittle workflow.

Collapsing plan, build, and refine into one skill with no phase control

Some workflows improve when those phases stay explicit, even if they live in one reusable bundle.

Sharing skills before they have an owner

Team-shared skills can spread useful workflow standards, but they can also spread stale assumptions. A shared skill should have a clear owner, review path, and evidence that it still improves the target workflow.

Practical implications

• write skills for behavior and workflow memory
• use runtime APIs for lifecycle control and visibility
• test skill triggers separately from runtime reliability
• keep the boundary between reusable task logic and execution control explicit
• watch for repeated prompt families that are functioning as proto-skills already
• preserve phase boundaries in coding skills when read-only planning and visible refinement improve outcomes
• create skills after a workflow has produced at least one good run
• improve skills from real failures rather than speculative preference
• keep project-specific skills out of global scope unless the behavior is genuinely reusable
• treat shareability as a governance requirement, not just a convenience feature