Separate discovery, reading, and use

Understanding loading stages helps you isolate why a Skill is not working.

Suggested learning time: 45 minutes.

1. 1Visible name and description
2. 2Selected SKILL.md
3. 3Required resources
4. 4Activation evidence

Original learning map: arrows show the reading or decision sequence, not a measured execution trace.

Prerequisites

• Understand Skills by separating them from other mechanisms

Evidence and exercise status

This chapter is an editorial learning guide. Reading sources is distinct from executing a Skill and measuring its effect. Exercise status: not-run. No experiment logs or model outputs exist.

Learning goals

• Explain progressive loading.
• Distinguish format compatibility from execution compatibility.

Roles in the work

• Learner: define hypotheses and grading criteria.
• AI: assist with reading and deliverable creation within the authorized scope.
• Reviewer: inspect outcomes and logs separately.

Inputs

• The input examples specified in this chapter.
• The official material and versions to verify.

Three stages of loading

In a typical progressive disclosure design, the system first discovers candidates from names and descriptions, reads the selected Skill body, and then opens additional resources as needed. This is less likely to introduce irrelevant instructions than keeping every Skill's complete text in the context at all times. The description is both an introduction and a selection cue, so explain what the Skill does and what requests should trigger it. A trigger condition written only in the body cannot help selection before the body is read.

Agent Skills specification

Selection failures and execution failures

If the right Skill exists but is not read, investigate its description, location, disabled settings, name collisions, and available reading mechanisms. If it is read but the result is poor, investigate ambiguous procedures, missing material, conflicting instructions, and unavailable tools. A final answer saying “I used the Skill” is not evidence that it was loaded. Check retrieval logs, invocation events, and the version actually loaded. If this cannot be verified, label activation as unknown and separate it from measured activation.

A portable format and runtime-specific features

Clients may read the same folder format while differing in support for script execution, networking, subagents, hooks, and approval interfaces. Do not assume optional specification fields or client-specific metadata have identical force everywhere. In particular, entries such as allowed-tools do not by themselves increase operating-system or organizational permissions. The execution environment's restrictions and confirmation policy take precedence.

Agent Skills client implementation

A compatibility checklist

When porting a Skill, record more than the model name: include the host application and version, Skill location, explicit invocation method, automatic activation support, available tools, dependency packages, and reference paths. Check whether instructions survive context summarization in a long conversation and whether they pass to subagents. If you evaluate a version with unsupported features removed, that modification is another Skill version. Do not report its results as those of the original Skill.

Workflow

1. Write three requests that should use the Skill and three similar requests that should not.
2. Separate conditions with explicit manual invocation from those relying on automatic selection.
3. Record no activation, failure after activation, and missing environment capabilities with distinct labels.

Outputs

• A trigger-evaluation table with six cases.

Quality checklist

• You inspected the description visible before the body is read.
• You checked execution-environment capabilities.
• You do not claim success without activation logs.

Failure diagnosis

• Symptom: Recording success without observing the effect.
• Cause: Confusing expected judgments with actual outputs.
• Fix: Keep unexecuted work as not-run, clear measurement fields, and obtain raw outputs and logs before scoring.

Exercise: Design activation tests first

Follow the workflow above in order and create the stated deliverable.

Completion criteria: Include boundary cases sharing the same keywords, and evaluate activation separately from deliverable quality.

Status: not-run.

Source scope

Sources support feature descriptions and distributor statements in the text and catalog. They are not evidence of measured effects or popularity ranks. Verification dates record reading public sources, rather than publication or update dates. Rolling references such as main are not pinned experimental versions.

Offline experiment worksheet