* Improve agent skills instructions with quality authoring patterns
Add practical, platform-agnostic authoring guidance to
agent-skills.instructions.md based on community best practices:
- Expand applyTo to cover all skills/**/SKILL.md paths
- Add writing guidance for every recommended body section with examples
(When to Use, Prerequisites, Step-by-Step Workflows, Gotchas,
Troubleshooting, References)
- Add 'Writing High-Impact Skills' section with 5 principles:
- Focus on what the agent doesn't know
- Context budget awareness for descriptions
- Gotchas as highest-signal content
- Flexible guidelines over rigid steps
- Progressive disclosure for large skills
- Fix description constraints: add 10-char minimum, single-quote wrapping
- Reconcile Step-by-Step Workflows with Flexible Guidelines advice
- Consolidate Workflow Execution Pattern under Common Patterns
- Standardize terminology (agent vs AI agent)
- Align line thresholds (200 soft / 500 hard)
- Update validation checklist with new quality criteria
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Update instructions/agent-skills.instructions.md
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
* Address PR review: make instructions platform-agnostic
- Replace 'GitHub Copilot'-specific language with generic 'the agent'
- Add skills/<skill-name>/ to Directory Structure table for repo layouts
- Fix relative path in flexible guidelines example (./references/)
- Update description and intro to be platform-neutral
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Revert terminology changes per reviewer feedback
Restore 'Copilot' and 'AI agent' terminology to match
the original doc's conventions. Keep new substantive content
(Writing High-Impact Skills, Gotchas, expanded examples).
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Aaron Powell <me@aaron-powell.com>
8eed96741f