AI Academy · Advanced concepts · Educational pilot
Agent Skills: Reusable AI Workflows
When a task comes up repeatedly, a reusable skill can provide consistent steps and examples. Learn what a skill contains, what it cannot do by itself, and how to evaluate one safely.
Supplementary advanced reading, under educational review. The examples are fictional, do not contact an AI service, and do not install or execute skills.
What is an Agent Skill?
In a common Agent Skills format, a skill is a folder containing a SKILL.md entrypoint. The Markdown file begins with YAML frontmatter, including a name and a description, followed by instructions. A skill may also include reference files, examples, templates or scripts.
The description helps the host determine when a skill might be useful. A host may load the full instructions only when relevant and inspect other files when needed. This is often called progressive disclosure. Exact support and behavior depend on the AI platform.
weekly-learning-summary/
- SKILL.md : required instructions and metadata
- references/ : optional examples and source notes
- scripts/ : optional code, reviewed before execution
- assets/ : optional templates and output resources
Different clients support different tools, paths and features. The general format improves portability, but does not promise identical behavior everywhere.
A skill is not a tool or an agent
These terms describe different responsibilities. A reusable skill can guide an agent, but it cannot grant itself access to systems or perform actions without an authorized runtime.
| Concept | Meaning | Illustrative example |
|---|---|---|
| Prompt | A request made during a conversation | Write an outline for this fictional school event. |
| Skill | A reusable instruction bundle with a defined use case | Turn fictional notes into a concise, checked weekly learning summary. |
| Tool | An operation exposed by the host system | Read an authorized file or calculate a total. |
| Agent | A system that can coordinate steps and sometimes use tools | Read sample notes, draft a summary, check it and ask a person to approve. |
| Plugin or connector | A host-specific integration to another service | Access a permitted document source. The host decides what is available. |
How a host may use a skill
- Read metadata: identify the relevant name and description.
- Match the task: decide whether a skill fits the user's request.
- Load instructions: read
SKILL.mdand any necessary references. - Perform permitted work: follow the workflow using only tools and data authorized by the host.
- Check the result: validate facts, note uncertainty, and request approval before consequential actions.
This is a common pattern, not a universal promise about the internals of every AI platform.
Read a small example
This fictional classroom skill is plain text for study. It does not contain executable code and is not installed on this site.
---
name: weekly-learning-summary
description: Summarize fictional weekly learning notes into a short, factual recap with next steps. Use for classroom practice notes that contain no personal information.
---
# Weekly learning summary
1. Read the supplied fictional notes only.
2. Identify activities, observations, questions and next steps.
3. Do not invent outcomes or missing details.
4. Write a recap of at most 120 words.
5. Mark uncertain statements for teacher review.
6. Return a draft, not an automatically sent message.Why this is safer: the expected input is limited to fictional notes, the output is a draft, missing facts are identified, and no messages are sent automatically.
How to design and review one
Design
Choose one repeatable task. Specify exactly when it should apply, the required input, the output format and an example of acceptable quality.
Test
Try representative and incomplete inputs. Check whether instructions actually improve accuracy and consistency compared with a simple prompt.
Secure
Read the full instructions and any scripts before installation. Avoid untrusted downloads, secret keys in files, excessive permissions and unreviewed external actions.
Improve
Correct unclear steps, split long reference material when useful and test again in each supported host.
Knowledge checks
Predict the answer, then open the explanation.
1. Does a skill give its agent permission to read private files?
No. A skill describes a workflow. The host application enforces access rights to files and tools.
2. Can a single skill run without external scripts?
Yes. Many useful skills consist only of instructions, examples, and optional reference material.
3. If a skill is written once, will every agent behave identically?
No. Discovery, tools, execution permissions and platform support differ. Test on each host.
4. Can a retrieved file or downloaded skill change who authorizes an action?
No. External content is untrusted until reviewed. Host permissions and user approval remain authoritative.
5. When should an educator save a workflow as a skill?
When the task is repeated, its inputs and outputs are clear, and examples or checks improve consistency.
6. What should happen if required information is missing?
Stop, report what is missing and ask for the needed information. Do not invent facts.
Design challenge: a study-summary skill
Write a paper version of a skill for a fictional library volunteer who summarizes a weekly inventory. Include a name, a description saying when to use it, five steps, the input it requires, a draft output and three checks for missing data.
Ask a classmate or teacher to test the instructions with two invented examples. Note where the instructions were unclear. Do not use real children's records, private library-account data or passwords.
Reference and further study
For an implementation-oriented definition, see Agent Skills specification and Codex Skills documentation. Platform-specific behavior must be checked in the documentation of the particular agent or application.
Never treat a downloaded skill as automatically trusted. Inspect every instruction and executable file, grant only necessary permissions, and keep human review for high-impact actions.