An agent skill is a reusable package built around a SKILL.md file. The file declares what the skill does and when it should be used, then gives the agent a repeatable workflow. You can add reference documents and scripts when they improve a task. A dependable first skill has a narrow purpose, explicit inputs and outputs, realistic trigger tests, and a safety review of every file before it is enabled.
This guide shows how to create that package, keep its instructions maintainable, test activation and runtime behavior, and install or share it across the Claude surfaces that document skills today. Those surfaces use different locations, permissions, and packaging rules; a skill uploaded in one does not automatically appear in the others.
As an Amazon Associate I earn from qualifying purchases.
What an agent skill is and why the package shape matters
A skill turns a recurring instruction set into a named package an agent can discover and reuse. Its required entry point is SKILL.md. That file combines YAML frontmatter for discovery with Markdown instructions for carrying out the task. Supporting files are optional: a reference document can hold material needed only in certain cases, and an executable script can handle deterministic work more reliably than repeated model-generated steps.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchClaude can use the description to decide whether a request matches the skill, load the main instructions when the skill is triggered, and open references or scripts as the workflow requires. This progressive-disclosure pattern keeps discovery metadata short, keeps the main workflow readable, and prevents every supporting detail from being loaded for every request.
A skill is not a performance guarantee or a universal plug-in format. The documented file locations and runtime behavior below are specific to Claude products. Anthropic points readers to an open Agent Skills specification, but the available material does not establish compatibility details for individual non-Claude implementations.
Choose one repeatable workflow before writing files
Start with a task your team performs often enough to justify a shared procedure, but narrow enough that the success criteria are unambiguous. Formatting a document to a team standard, turning meeting notes into decisions and action items, or validating a known data file are better first projects than a broad skill that tries to handle every kind of office or engineering work.
Define the input
Write down what the agent will receive: pasted text, an attached document, a directory of files, or a request with named fields. Say what must be present and what the skill should do when a field is missing. A skill that extracts owners and due dates, for example, should not invent either one when the notes do not state them.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Define the procedure
List the actions in the order they should happen. Separate interpretation from deterministic checks, and identify any reference file that is needed only for a particular branch. Keep the first version in basic Markdown. Anthropic recommends focused skills and starting without scripts or complex machinery until the workflow itself is clear.
Define a successful result
Specify the output shape, required sections, and evidence rules. Include a small example input and output so a future maintainer can tell whether a change preserves the intended behavior. Also write one or two requests that should not activate the skill; a useful description must distinguish its workflow from neighboring tasks.
Create the entry file
Use a small, predictable directory
Create a directory named for the skill and place SKILL.md at its root. A minimal package contains only that file:
meeting-notes/
└── SKILL.mdThe directory name is a human-facing convention; the validated name is the name field in the frontmatter. Keep the package self-contained so a reviewer can inspect it without hunting through unrelated project files.
Write valid frontmatter
The Claude format documented in Anthropic’s overview begins with YAML frontmatter containing name and description. The name may use lowercase letters, numbers, and hyphens, must not contain the reserved words anthropic or claude, and is limited to 64 characters. The description is limited to 1,024 characters. It should state both the capability and the situation in which Claude should use it.
---
name: meeting-notes
description: Turn supplied meeting notes into a concise summary with decisions and action items. Use when asked to organize or summarize meeting notes.
---
# Meeting notes
## Workflow
1. Read the supplied notes.
2. List decisions separately from open questions.
3. Extract action items with an owner and due date only when the notes state them.
4. Mark missing owners or dates as unspecified.
## Example
Input: meeting notes supplied by the user.
Output: summary, decisions, open questions, and action items.Make sure the YAML keys begin at the left margin. In particular, do not add an accidental leading space before description. A malformed frontmatter block can prevent discovery before the Markdown instructions are ever read.
Make instructions operational
After the heading, explain what Claude should do, in what order, and what it must not do. Use concrete verbs, field names, and boundaries. State when to ask a clarification question, when to mark information as unspecified, and which facts must come from the supplied material. Prefer a short numbered workflow over a collection of vague principles.
- Describe the expected input and the output format.
- Separate mandatory steps from optional improvements.
- Tell the agent how to handle missing, contradictory, or out-of-scope information.
- Include an example that demonstrates the edge you care about, not only a perfect case.
- Keep instructions specific to this workflow instead of adding general advice that belongs in every skill.
Expand the package without making SKILL.md unwieldy
Move conditional material into references
When a rule is long or used only for a subset of requests, put it in a second file such as REFERENCE.md. In SKILL.md, name the file and explain exactly when to read it. This preserves progressive disclosure: discovery sees the metadata, a triggered request loads the workflow, and the agent opens the detailed reference only when that branch is relevant.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
meeting-notes/
├── SKILL.md
├── REFERENCE.md
└── scripts/
└── validate_actions.pyReference files should have a clear purpose and stable headings. If a rule is important on every run, keep it in SKILL.md rather than hiding it in a file the agent may not open. If the reference changes independently, record who owns it and how you will test the dependency.
Use scripts for deterministic work
A script is appropriate when the same mechanical operation must be exact every time: checking required fields, validating a file format, or applying a repeatable transformation. Document what the script reads, what it changes, what it returns, and what errors mean. Review the source as carefully as the Markdown.
Runtime support is surface-dependent. The Help Center describes scripts as attachable to skills, while the documented constraints for Claude Code and API Skills differ in package availability. Do not assume that a library installed in one environment exists in another, and do not design a workflow that requires downloading a dependency at runtime when the target surface does not permit it.
Keep the entry file as the map
A growing skill remains understandable when SKILL.md acts as a map: identify the decision points, link each one to the relevant file, and keep the execution order visible. Avoid copying the same rule into several files. Duplicated instructions drift and can cause conflicting behavior.
Test activation, loading, and the actual result
Testing is part of authoring, not a final polish step. Anthropic’s Help Center recommends incremental tests after meaningful changes, and the Claude Academy course covers triggering, loading, conflicts, and runtime issues. Use a small test set that exercises both the positive and negative boundaries of the description.
- Check the package before invoking Claude. Confirm that
SKILL.mdexists at the package root, the frontmatter parses, the name follows the character and length rules, and every referenced file exists at the stated path. - Run a clear positive prompt. Use a realistic request that plainly matches the description. Confirm that Claude selects the skill and follows the workflow rather than merely producing a generic answer.
- Run a near miss. Ask for a neighboring task that should not use the skill. If it activates, make the description narrower or add an explicit boundary to the instructions.
- Use realistic, imperfect input. Include missing owners, conflicting dates, long notes, or an empty optional field when those cases matter. Verify that the output follows your stated handling rules instead of filling gaps by guesswork.
- Exercise references and scripts. Trigger every branch that should open a reference file and run each script with valid and invalid inputs. Check returned values, changed files, and error messages.
- Repeat after each meaningful edit. A change to frontmatter tests discovery; a change to workflow text tests behavior; a script or dependency change tests runtime and permissions. Keep example prompts and expected output with the package or in its project documentation.
If the skill does not trigger
- Make the description say what the skill does and when to use it in ordinary language, using the terms a developer is likely to put in a prompt.
- Check frontmatter spelling, indentation, delimiters, and the 64-character name limit.
- Confirm the skill is installed in the surface and scope you are testing; a project skill and a personal skill are not interchangeable locations.
- Test with a direct request before testing a nuanced one. This separates discovery problems from workflow problems.
If the wrong skill triggers or two skills conflict
Compare the descriptions for overlapping wording and narrow each one to a distinct workflow. Add an explicit non-use boundary where confusion is predictable. Then rerun both positive and near-miss prompts. Do not solve a discovery conflict by adding contradictory instructions inside the skill; fix the scope at the metadata and workflow level.
If a reference or script fails
Verify the relative path and filename, then test the file independently with the same permissions and runtime available to Claude. For a script, inspect dependency assumptions, input encoding, write locations, and error handling. A successful local run does not prove that the same package can run in an API sandbox or another Claude surface.
Install and share skills on the documented Claude surfaces
Claude’s products use different packaging and ownership models. Choose the target surface before deciding where a file belongs, and verify current availability, plan requirements, administrator settings, and environment limits because product behavior can change.
Recommended Free Tools
| Claude surface | Where the skill lives | Access and sharing | Documented runtime or packaging notes |
|---|---|---|---|
| Claude Code | ~/.claude/skills/ for personal skills; .claude/skills/ for project skills |
Personal skills are available to the user; project skills can travel with the project. The overview also describes sharing through version control or plugins. | Skills are filesystem-based. The host environment’s tools and permissions determine what attached scripts can do. |
| Claude API | Custom skills are uploaded for use with the code execution tool in a sandboxed container. | Uploaded custom skills are workspace-wide rather than tied to one local checkout. | The documented API constraints include no network access and no runtime package installation. Check dependency availability before relying on a script. |
| claude.ai | Upload a skill as a ZIP file through Settings > Features. | Uploaded custom skills are user-specific. | The upload is packaged as a ZIP. A skill uploaded here is not automatically available in the API or Claude Code. |
These are separate distribution paths, not three views of one synchronized folder. If a team maintains the same workflow across surfaces, keep an authoritative package in version control, adapt packaging to each target, and test each deployment independently. A project copy in Claude Code does not make the skill available to a user’s claude.ai account, and an API upload does not populate a local filesystem directory.
Review every skill as executable, permissioned content
Anthropic’s official overview states: “Use Skills only from trusted sources: those you created yourself or obtained from Anthropic.” The warning matters even when the entry file looks like ordinary Markdown. A package can contain instructions or code that misuse tools, expose data, or fetch untrusted content.
Before enabling a downloaded or shared package, inspect the complete directory:
- Read
SKILL.md, including instructions that are easy to overlook near the bottom of the file. - Open every reference document and compare its rules with the advertised purpose.
- Read every script and note file reads, writes, subprocesses, network calls, environment-variable access, and generated output.
- Look for hardcoded credentials, tokens, private endpoints, or instructions to copy sensitive data into a prompt or log.
- Identify the tools and permissions available on the target host, then test with data of the same sensitivity expected in production.
- Remove or isolate anything you cannot explain. Do not enable a package merely because its description sounds useful.
The risk depends on the host agent’s tools and permissions. A text-only review reduces surprises but cannot prove that a package is harmless in every runtime. Use least-privilege data, accounts, and directories during testing, and have a second person review packages that will process confidential material.
Choose a setup that matches the deployment
The right arrangement depends on who needs the skill and what the workflow must execute. Use this decision sequence before adding files:
- One developer, local work: begin with a personal Claude Code skill in
~/.claude/skills/. Keep the package small and test it with the data and tools you actually use. - A repository-owned workflow: place the project skill in
.claude/skills/, review it like source code, and share it through the team’s version-control process or an appropriate plugin. - Service or automation use: target an API workspace, confirm the code-execution sandbox’s network and dependency constraints, and remove any script assumption that requires runtime installation or internet access.
- Personal browser use: package the skill as a ZIP for claude.ai through Settings > Features, then test the uploaded copy. Do not assume that local or API changes will appear there.
- More than one surface: keep one reviewed source package, create the surface-specific package form, and maintain separate activation and runtime tests for each destination.
Maintain the skill after the first successful run
Version the behavior, not just the files
Record meaningful changes to the workflow, description, references, and scripts. A description change can alter discovery even when the procedure is untouched; a reference change can alter outputs without changing SKILL.md. Keep a short changelog or commit history so users know what changed and which prompts were rerun.
Keep examples current
Examples are executable documentation. Update them when the output schema, required fields, or edge-case policy changes. Include at least one case with missing information and one request that should not trigger the skill. Remove examples that rely on files, dependencies, or permissions no longer available on the target surface.
Re-audit on every distribution change
When moving a package from Claude Code to the API or claude.ai, repeat the permission and runtime review. The same script can have different capabilities, and the same reference path can be valid in one package form and broken in another. Verify access scope, dependency availability, network behavior, and handling of sensitive data before publishing the new copy.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteWorked first example: a meeting-notes skill
The meeting-notes example is intentionally narrow. Its input is supplied notes; its output has four named parts; and it never invents an owner or due date. A complete first version can fit in one file:
---
name: meeting-notes
description: Turn supplied meeting notes into a concise summary with decisions and action items. Use when asked to organize or summarize meeting notes.
---
# Meeting notes
## Workflow
1. Read the supplied notes once for context.
2. Extract the main subject and produce a concise summary.
3. List decisions in a separate section.
4. List open questions separately from decisions.
5. Extract action items only when the notes state the task, owner, or due date.
6. Mark an owner or due date as unspecified when the notes do not provide it.
7. Do not infer commitments, owners, or dates from context.
## Output
Return these headings in order:
- Summary
- Decisions
- Open questions
- Action items
For each action item, include the task and any stated owner and due date.Test it with notes containing a decision, an unresolved question, one assigned task, and one task with no owner. Then test a request to draft a project plan from scratch; that is a near miss and should not be silently treated as meeting-note extraction. If the skill later needs a long house style or a deterministic action-item validator, move those parts into REFERENCE.md and scripts/validate_actions.py, add explicit read or execution conditions to SKILL.md, and rerun the same tests.
What the documented material does not establish
No independently measured statistics about skill effectiveness, adoption, or productivity are established in the cited official materials, so a skill should be judged by its own tests rather than a promised percentage improvement. Anthropic Academy lists an Introduction to agent skills course as six lessons lasting one hour in 2026; it is an optional learning resource, not evidence of a particular outcome.
The open Agent Skills specification is a useful reference point, but the available Claude documentation does not establish that a given non-Claude agent will recognize the same directories, frontmatter, progressive-disclosure behavior, scripts, or permissions. Treat another platform as a separate implementation until its documentation confirms compatibility.
Quick Recap
Release checklist
- The skill has one focused workflow and a clear success definition.
SKILL.mdis at the package root with valid frontmatter.- The name uses permitted characters, stays within 64 characters, and avoids the reserved words
anthropicandclaude. - The description stays within 1,024 characters and says both what the skill does and when to use it.
- Instructions identify inputs, ordered steps, output headings, and missing-data behavior.
- References and scripts are included only when needed, with their read or execution conditions documented.
- Positive, near-miss, imperfect-input, reference, and script tests have been run on the target surface.
- Every file has been inspected for unsafe instructions, secrets, unexpected data access, and network behavior.
- Packaging, ownership, permissions, and dependency limits match the selected Claude surface.
- The deployed copy is versioned and has a plan for retesting after changes.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
