diegosouzapw AI Coding Assistant Customization File Specifications
This skill provides the authoritative, up-to-date specifications for all AI coding assistant customization file types. Each file type has its own dedicated reference document with complete attribute tables, validation rules, examples, and best practices.
Standard: These specs align with the Agent Skills open standard and the VS Code Copilot customization documentation.
How to Use This Skill
- Read the Quick Reference below to identify the file type you need.
- Follow the link to the dedicated reference document for full details.
- Use the File Locations reference when you need to know where files go for a specific provider.
- Use the Settings reference for VS Code configuration.
Important: Detailed specifications live in the
references/folder — not in this file. This keeps the main skill file lightweight for efficient context loading per the progressive disclosure model.
Quick Reference
| Type | Extension | Purpose | Reference |
|---|---|---|---|
| Agent | .agent.md / .md |
Custom AI personas with specialized behaviors, tool restrictions, and handoff workflows | AGENTS.md |
| Skill | SKILL.md (directory-based) |
Reusable, portable capabilities with scripts and resources — follows the Agent Skills open standard | SKILLS.md |
| Prompt | .prompt.md |
Reusable prompt templates invoked as slash commands | PROMPTS.md |
| Instruction | .instructions.md |
Contextual guidance applied automatically by file type or description | INSTRUCTIONS.md |
| File Locations | — | Provider folder mapping, directory structure, naming conventions | FILE-LOCATIONS.md |
| VS Code Settings | — | Settings that control customization file discovery and behavior | SETTINGS.md |
Provider Support
These specifications work across multiple AI coding assistant providers. Each provider uses its own base folder but the file formats are consistent:
| Provider | Base Folder |
|---|---|
| GitHub Copilot | .github/ |
| Claude Code | .claude/ |
| Codex | .codex/ |
| OpenCode | .config/opencode/ |
| Gemini | .gemini/ |
See FILE-LOCATIONS.md for the complete directory structure and provider-specific details.
File Type Selection Guide
Use this decision tree to choose the right file type:
"I want coding standards applied everywhere" → Use always-on instructions (
.gemini/copilot-instructions.mdorAGENTS.md). See INSTRUCTIONS.md."I want different rules for different file types" → Use file-based instructions (
.instructions.mdwithapplyTopatterns). See INSTRUCTIONS.md."I have a reusable task I run repeatedly" → Use a prompt file (
.prompt.md) invoked as a slash command. See PROMPTS.md."I need a multi-step workflow with scripts and resources" → Use an Agent Skill (directory with
SKILL.md). Portable across tools. See SKILLS.md."I need a specialized AI persona with tool restrictions" → Use a custom agent (
.agent.md). Supports handoffs for multi-step workflows. See AGENTS.md.