What SKILL.md does
A one-off prompt asks a model to complete a task now. A SKILL.md file documents how an agent should complete the same kind of task repeatedly. It turns personal prompting knowledge into an inspectable procedure that another user, model, or team can apply.
The file name is a convention rather than a universal protocol. Different agent products discover and load skills differently, but Markdown remains useful because people can review it, version it in Git, and improve it without specialized tooling.
A practical SKILL.md format
Strong files normally contain:
- Name and purpose. Define one job and the outcome that counts as done.
- Trigger guidance. Explain when the agent should and should not use the skill.
- Required inputs. List facts, files, permissions, and decisions needed before work begins.
- Workflow. Give ordered steps, decision points, and checks.
- Output contract. Provide headings, a schema, template, or worked example.
- Safety rules. Identify prohibited actions, approval gates, privacy limits, and source-of-truth requirements.
- Limitations. State where the method becomes unreliable or needs an expert.
Start with the smallest procedure that produces a useful result. A skill that claims to handle research, strategy, writing, publishing, analytics, and optimization is difficult to trigger and test. Separate jobs when they require different inputs, permissions, or definitions of success.
Minimal example
# Meeting Notes to Action Plan
## Use when
The user provides meeting notes and needs confirmed decisions, actions, owners, and deadlines.
## Inputs
- Meeting notes or transcript
- Optional project context
## Workflow
1. Extract explicit decisions.
2. Extract actions without inventing owners or dates.
3. Mark missing information as Not specified.
4. Separate open questions and risks.
5. Check every action against the source.
## Output
Return Summary, Decisions, Action Items, Open Questions, and Risks.
## Safety
Never infer a commitment that was not made in the source.
The example is intentionally plain. Reliability comes from unambiguous rules and checks, not ceremonial language.
How to write your first file
Collect three realistic inputs before writing. Describe the output you would accept for each. Identify mistakes a generic assistant usually makes. Convert that knowledge into an ordered method and explicit guardrails. Run the file against all three inputs, compare outputs, and revise instructions that produced inconsistent behavior.
Use imperative language: “extract,” “verify,” “ask,” and “stop.” Distinguish requirements from suggestions. If a step needs external access, name the tool and permission instead of assuming it exists. Require confirmation immediately before irreversible or external actions.
Browse the data-cleaning insight report skill for a source-fidelity example, the code-review assistant skill for a structured technical review, and the API integration architect skill for permission-aware planning.
Testing and maintenance
Test normal, incomplete, adversarial, and high-risk inputs. Confirm the skill asks for missing information, treats untrusted content as data, and stops at approval gates. Keep supporting references close to the skill, but do not load large folders without need. Version behavior changes and review the file when models, APIs, policies, or business processes change.
A good SKILL.md is concise enough to inspect, specific enough to test, and honest about its boundaries.