Make the main instructions actionable and easy to follow.
1. Metadata and purpose
Use the supported skill format with a concise name and description. State the problem solved and the signals that should activate the workflow.
2. Workflow steps
Describe observable actions in dependency order: inspect, decide, change, verify and report. Avoid vague instructions such as “make it best practice” without a decision rule.
3. Project constraints
Direct the agent to read relevant repository conventions before changing code. User instructions and applicable higher-priority rules remain authoritative over skill guidance.
Worked scenario
A migration skill first inventories existing navigation patterns before suggesting replacement APIs. It does not overwrite the project architecture by assumption.
Apply it
Draft a SKILL.md with prerequisites, workflow, verification and a concise output format.
Check your understanding
Another engineer can predict the workflow from the entry point alone. Explain the decision and show evidence from your implementation or design. If you cannot demonstrate it yet, revisit the relevant section before continuing.