Instruction file imported from pazdedav/my-infraops-project (.github/instructions/agent-skills.instructions.md). Copyright stays with the author.

Agent Skills File Guidelines

Required SKILL.md Frontmatter

---
name: webapp-testing
description: "Toolkit for testing local web applications using Playwright. Use when asked to verify frontend functionality, debug UI behavior, or capture screenshots."
license: Complete terms in LICENSE.txt
---

CRITICAL: The description is the PRIMARY mechanism for automatic skill discovery. Copilot reads ONLY name + description to decide whether to load a skill. A vague description means the skill never activates.

NEVER use YAML block scalars (>, >-, |, |-) for description. Use a single-line description: "..." inline string. Block scalars break VS Code prompts-diagnostics-provider.

Body Sections

Directory Structure

.github/skills/<skill-name>/
├── SKILL.md              # Required: Main instructions (≤500 lines)
├── LICENSE.txt            # Recommended: License terms
├── scripts/              # Executable automation (loaded when executed)
├── references/           # Documentation (loaded when referenced by SKILL.md)
├── assets/               # Static files used AS-IS in output (not loaded into context)
└── templates/            # Starter code the AI agent MODIFIES and builds upon

Assets vs Templates: If the AI reads and builds upon it → templates/. If the file is used as-is in output → assets/.

Progressive Loading

Writing Rules

• Imperative mood: "Run", "Create", "Configure"
• Include exact commands with parameters
• Keep SKILL.md body ≤500 lines; split large workflows into references/
• Use relative paths for all resource references
• Include --help documentation and error handling in scripts
• No hardcoded credentials or secrets

Validation Checklist

• Valid frontmatter with name and description
• name is lowercase with hyphens, ≤64 characters
• description states WHAT, WHEN, and KEYWORDS
• Body ≤500 lines; large content in references/
• Scripts include help docs and error handling
• No hardcoded credentials

Resources

• Agent Skills Specification
• VS Code Agent Skills Docs