agent-customization

Create a .instructions.md file in .github/instructions/ with a YAML frontmatter containing a description and optional applyTo glob pattern. Use a keyword-rich description starting with 'Use when...' so the agent can discover it on demand.

Both appear as slash commands in chat. A prompt file (.prompt.md) handles a single focused task with parameterized inputs, while a skill (SKILL.md) provides a multi-step workflow with bundled scripts, references, and assets.

Silent failures usually come from YAML frontmatter errors like unescaped colons, tabs instead of spaces, or a name that does not match the folder. Quote descriptions containing colons and verify the file sits in the correct .github/ location.

Use a custom agent (.agent.md) when you need context isolation through subagents or different tool restrictions per workflow stage. Use a skill when the same capabilities apply across all steps of the workflow.

The applyTo "**" pattern loads the instruction into the context window on every interaction regardless of relevance, consuming context budget. Prefer specific globs like **/*.py or src/api/** unless the instruction truly applies to all files.