Improve agent skills instructions with quality authoring patterns

[yeelam-gordon]

Pull Request Checklist

• I have read and followed the CONTRIBUTING.md guidelines.
• I have read and followed the Guidance for submissions involving paid services.
• My contribution adds a new instruction, prompt, agent, skill, or workflow file in the correct directory.
• The file follows the required naming convention.
• The content is clearly structured and follows the example format.
• I have tested my instructions, prompt, agent, skill, or workflow with GitHub Copilot.
• I have run npm start and verified that README.md is up to date.
• I am targeting the staged branch for this pull request.

---

Description

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 (not only .copilot or .claude)
• 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

---

Type of Contribution

• Update to existing instruction, prompt, agent, plugin, skill, or workflow.

---

Additional Notes

Here is the reference for improvement:
https://www.linkedin.com/pulse/lessons-from-building-claude-code-how-we-use-skills-thariq-shihipar-iclmc/
https://www.toolmesh.ai/news/anthropic-engineer-details-claude-code-skills-best-practices

---

By submitting this pull request, I confirm that my contribution abides by the Code of Conduct and will be licensed under the MIT License.

[Copilot]

Pull request overview

Updates the repo’s agent-skill authoring instructions to provide more practical guidance and broader applicability across skill folder layouts.

Changes:

• Broadens applyTo to target all **/skills/**/SKILL.md paths.
• Adds detailed recommended SKILL.md body sections (including “Gotchas”) with examples and quality principles.
• Refactors and expands the validation checklist and common workflow execution guidance.

[aaronpowell]

I think there is a level of merit in here with the new additions, but there's a lot of superfluous changes - while, yes, skills are portable this repo is optimised for working with GitHub Copilot so it stands to reason that it uses Copilot as the terminology.

[yeelam-gordon]

I think there is a level of merit in here with the new additions, but there's a lot of superfluous changes - while, yes, skills are portable this repo is optimised for working with GitHub Copilot so it stands to reason that it uses Copilot as the terminology.

Thanks @aaronpowell , I rollback and make the term consistent to use "copilot" now ;-) Please for helping on review.