Organize workspace: Frontend, Backend, and Tests in one repo
This commit is contained in:
@@ -0,0 +1,70 @@
|
||||
---
|
||||
name: agent-customization
|
||||
description: 'Create, update, review, fix, or debug VS Code agent customization files (.instructions.md, .prompt.md, .agent.md, SKILL.md, copilot-instructions.md, AGENTS.md). Use for: saving coding preferences; troubleshooting why instructions/skills/agents are ignored or not invoked; configuring applyTo patterns; defining tool restrictions; creating custom agent modes or specialized workflows; packaging domain knowledge; fixing YAML frontmatter syntax.'
|
||||
---
|
||||
|
||||
# Agent Customization
|
||||
|
||||
## Decision Flow
|
||||
|
||||
| Primitive | When to Use |
|
||||
|-----------|-------------|
|
||||
| Workspace Instructions | Always-on, applies everywhere in the project |
|
||||
| File Instructions | Explicit via `applyTo` patterns, or on-demand via `description` |
|
||||
| MCP | Integrates external systems, APIs, or data |
|
||||
| Custom Agents | Subagents for context isolation, or multi-stage workflows with tool restrictions |
|
||||
| Prompts | Single focused task with parameterized inputs |
|
||||
| Skills | On-demand workflow with bundled assets (scripts/templates) |
|
||||
|
||||
## Quick Reference
|
||||
|
||||
Consult the reference docs for templates, domain examples, advanced frontmatter options, asset organization, anti-patterns, and creation checklists.
|
||||
|
||||
| Type | File | Location | Reference |
|
||||
|------|------|----------|-----------|
|
||||
| Workspace Instructions | `copilot-instructions.md`, `AGENTS.md` | `.github/` or root | [Link](./primitives/workspace-instructions.md) |
|
||||
| File Instructions | `*.instructions.md` | `.github/instructions/` | [Link](./primitives/instructions.md) |
|
||||
| Prompts | `*.prompt.md` | `.github/prompts/` | [Link](./primitives/prompts.md) |
|
||||
| Custom Agents | `*.agent.md` | `.github/agents/` | [Link](./primitives/agents.md) |
|
||||
| Skills | `SKILL.md` | `.github/skills/<name>/`, `.agents/skills/<name>/`, `.claude/skills/<name>/` | [Link](./primitives/skills.md) |
|
||||
|
||||
**User-level**: `{{USER_PROMPTS_FOLDER}}/` (*.prompt.md, *.instructions.md, *.agent.md; not skills)
|
||||
Customizations roam with user's settings sync
|
||||
|
||||
## Creation Process
|
||||
|
||||
If you need to explore or validate patterns in the codebase, use a read-only subagent. If the ask-questions tool is available, use it to interview the user and clarify requirements.
|
||||
|
||||
Follow these steps when creating any customization file.
|
||||
|
||||
### 1. Determine Scope
|
||||
|
||||
Ask the user where they want the customization:
|
||||
- **Workspace**: For project-specific, team-shared customizations → `.github/` folder
|
||||
- **User profile**: For personal, cross-workspace customizations → `{{USER_PROMPTS_FOLDER}}/`
|
||||
|
||||
### 2. Choose the Right Primitive
|
||||
|
||||
Use the Decision Flow above to select the appropriate file type based on the user's need.
|
||||
|
||||
### 3. Create the File
|
||||
|
||||
Create the file directly at the appropriate path:
|
||||
- Use the location tables in each reference file
|
||||
- Include required frontmatter as needed
|
||||
- Add the body content following the templates
|
||||
|
||||
### 4. Validate
|
||||
|
||||
After creating:
|
||||
- Confirm the file is in the correct location
|
||||
- Verify frontmatter syntax (YAML between `---` markers)
|
||||
- Check that `description` is present and meaningful
|
||||
|
||||
## Edge Cases
|
||||
|
||||
**Instructions vs Skill?** Does this apply to *most* work, or *specific* tasks? Most → Instructions. Specific → Skill.
|
||||
|
||||
**Skill vs Prompt?** Multi-step workflow with bundled assets → Skill. Single focused task with inputs → Prompt.
|
||||
|
||||
**Skill vs Custom Agent?** Same capabilities for all steps → Skill. Need context isolation (subagent returns single output) or different tool restrictions per stage → Custom Agent.
|
||||
@@ -0,0 +1,111 @@
|
||||
# [Custom Agents (.agent.md)](https://code.visualstudio.com/docs/copilot/customization/custom-agents)
|
||||
|
||||
Custom personas with specific tools, instructions, and behaviors. Use for orchestrated workflows with role-based tool restrictions.
|
||||
|
||||
## Locations
|
||||
|
||||
| Path | Scope |
|
||||
|------|-------|
|
||||
| `.github/agents/*.agent.md` | Workspace |
|
||||
| `<profile>/agents/*.agent.md` | User profile |
|
||||
|
||||
## Frontmatter
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: "<required>" # For agent picker and subagent discovery
|
||||
name: "Agent Name" # Optional, defaults to filename
|
||||
tools: ["search", "web"] # Optional: aliases, MCP (<server>/*), extension tools
|
||||
model: "Claude Sonnet 4" # Optional, uses picker default; supports array for fallback
|
||||
argument-hint: "Task..." # Optional, input guidance
|
||||
agents: ["Agent1", "Agent2"] # Optional, restrict allowed subagents by name (omit = all, [] = none)
|
||||
user-invokable: true # Optional, show in agent picker (default: true)
|
||||
disable-model-invocation: false # Optional, prevent subagent invocation (default: false)
|
||||
handoffs: [...] # Optional, transitions to other agents
|
||||
---
|
||||
```
|
||||
|
||||
### Invocation Control
|
||||
|
||||
| Attribute | Default | Effect |
|
||||
|-----------|---------|--------|
|
||||
| `user-invokable: false` | `true` | Hide from agent picker, only accessible as subagent |
|
||||
| `disable-model-invocation: true` | `false` | Prevent other agents from invoking as subagent |
|
||||
|
||||
### Model Fallback
|
||||
|
||||
```yaml
|
||||
model: ['Claude Sonnet 4.5 (copilot)', 'GPT-5 (copilot)'] # First available model is used
|
||||
```
|
||||
|
||||
## Tools
|
||||
|
||||
Sources: built-in aliases, specific tools, MCP servers (`<server>/*`), extension tools.
|
||||
|
||||
**Special**: `[]` = no tools, omit = defaults. Body reference: `#tool:<name>`
|
||||
|
||||
### Tool Aliases
|
||||
|
||||
| Alias | Purpose |
|
||||
|-------|---------|
|
||||
| `execute` | Run shell commands |
|
||||
| `read` | Read file contents |
|
||||
| `edit` | Edit files |
|
||||
| `search` | Search files or text |
|
||||
| `agent` | Invoke custom agents as subagents |
|
||||
| `web` | Fetch URLs and web search |
|
||||
| `todo` | Manage task lists |
|
||||
|
||||
### Common Patterns
|
||||
|
||||
```yaml
|
||||
tools: ["read", "search"] # Read-only research
|
||||
tools: ["myserver/*"] # MCP server only
|
||||
tools: ["read", "edit", "search"] # No terminal access
|
||||
tools: [] # Conversational only
|
||||
```
|
||||
|
||||
To discover available tools, check your current tool list or use `#tool:` syntax in the body to reference specific tools.
|
||||
|
||||
## Template
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: "{Use when... trigger phrases for subagent discovery}"
|
||||
tools: ["{minimal set of tool aliases}"]
|
||||
user-invokable: false
|
||||
---
|
||||
You are a specialist at {specific task}. Your job is to {clear purpose}.
|
||||
|
||||
## Constraints
|
||||
- DO NOT {thing this agent should never do}
|
||||
- DO NOT {another restriction}
|
||||
- ONLY {the one thing this agent does}
|
||||
|
||||
## Approach
|
||||
1. {Step one of how this agent works}
|
||||
2. {Step two}
|
||||
3. {Step three}
|
||||
|
||||
## Output Format
|
||||
{Exactly what this agent should return}
|
||||
```
|
||||
|
||||
## Invocation
|
||||
|
||||
- **Manual**: Agent selector in chat
|
||||
- **Subagent**: Parent agent delegates based on `description` match (when `infer` allows)
|
||||
|
||||
## Core Principles
|
||||
|
||||
1. **Single role**: One persona with focused responsibilities per agent
|
||||
2. **Minimal tools**: Only include what the role needs—excess tools dilute focus
|
||||
3. **Clear boundaries**: Define what the agent should NOT do
|
||||
4. **Keyword-rich description**: Include trigger words so parent agents know when to delegate
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
- **Swiss-army agents**: Too many tools, tries to do everything
|
||||
- **Vague descriptions**: "A helpful agent" doesn't guide delegation—be specific
|
||||
- **Role confusion**: Description doesn't match body persona
|
||||
- **Circular handoffs**: A → B → A without progress criteria
|
||||
@@ -0,0 +1,69 @@
|
||||
# [File-Specific Instructions (.instructions.md)](https://code.visualstudio.com/docs/copilot/customization/custom-instructions)
|
||||
|
||||
Guidelines loaded on-demand when relevant to the current task, or explicitly when files match a pattern.
|
||||
|
||||
## Locations
|
||||
|
||||
| Path | Scope |
|
||||
|------|-------|
|
||||
| `.github/instructions/*.instructions.md` | Workspace |
|
||||
| `<profile>/instructions/*.instructions.md` | User profile |
|
||||
|
||||
## Frontmatter
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: "<required>" # For on-demand discovery—keyword-rich
|
||||
name: "Instruction Name" # Optional, defaults to filename
|
||||
applyTo: "**/*.ts" # Optional, auto-attach for matching files
|
||||
---
|
||||
```
|
||||
|
||||
## Discovery Modes
|
||||
|
||||
| Mode | Trigger | Use Case |
|
||||
|------|---------|----------|
|
||||
| **On-demand** (`description`) | Agent detects task relevance | Task-based: migrations, refactoring, API work |
|
||||
| **Explicit** (`applyTo`) | Files matching glob in context | File-based: language standards, framework rules |
|
||||
| **Manual** | `Add Context` → `Instructions` | Ad-hoc attachment |
|
||||
|
||||
## Template
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: "Use when writing database migrations, schema changes, or data transformations. Covers safety checks and rollback patterns."
|
||||
---
|
||||
# Migration Guidelines
|
||||
|
||||
- Always create reversible migrations
|
||||
- Test rollback before merging
|
||||
- Never drop columns in the same release as code removal
|
||||
```
|
||||
|
||||
Note the "Use when..." pattern in the description—this helps on-demand discovery.
|
||||
|
||||
## Explicit File Matching (optional)
|
||||
|
||||
Use `applyTo` when the instruction applies to specific file types or folders:
|
||||
|
||||
```yaml
|
||||
applyTo: "**/*.py" # All Python files
|
||||
applyTo: ["src/**", "lib/**"] # Multiple patterns (OR)
|
||||
applyTo: "src/api/**/*.ts" # Specific folder + extension
|
||||
```
|
||||
|
||||
Applied when creating or modifying matching files, not for read-only operations.
|
||||
|
||||
## Core Principles
|
||||
|
||||
1. **Keyword-rich descriptions**: Include trigger words for on-demand discovery
|
||||
2. **One concern per file**: Separate files for testing, styling, documentation
|
||||
3. **Concise and actionable**: Share context window—keep focused
|
||||
4. **Show, don't tell**: Brief code examples over lengthy explanations
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
- **Vague descriptions**: "Helpful coding tips" doesn't enable discovery
|
||||
- **Overly broad applyTo**: `"**"` with content only relevant to specific files
|
||||
- **Duplicating docs**: Copy README instead of linking
|
||||
- **Mixing concerns**: Testing + API design + styling in one file
|
||||
@@ -0,0 +1,64 @@
|
||||
# [Prompts (.prompt.md)](https://code.visualstudio.com/docs/copilot/customization/prompt-files)
|
||||
|
||||
Reusable task templates triggered on-demand in chat. Single focused task with parameterized inputs.
|
||||
|
||||
## Locations
|
||||
|
||||
| Path | Scope |
|
||||
|------|-------|
|
||||
| `.github/prompts/*.prompt.md` | Workspace |
|
||||
| `<profile>/prompts/*.prompt.md` | User profile |
|
||||
|
||||
## Frontmatter
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: "<required>" # Prompt description for discovery
|
||||
name: "Prompt Name" # Optional, defaults to filename
|
||||
agent: "agent" # Optional: ask, edit, agent, or custom agent
|
||||
tools: ["search", "web"] # Optional: built-in, MCP (<server>/*), extension
|
||||
model: "Claude Sonnet 4" # Optional, uses picker default
|
||||
---
|
||||
```
|
||||
|
||||
## Template
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: "Generate test cases for selected code"
|
||||
agent: "agent"
|
||||
---
|
||||
Generate comprehensive test cases for the provided code:
|
||||
- Include edge cases and error scenarios
|
||||
- Follow existing test patterns in the codebase
|
||||
- Use descriptive test names
|
||||
```
|
||||
|
||||
**Context references**: Use Markdown links for files (`[config](./config.json)`) and `#tool:<name>` for tools.
|
||||
|
||||
## Invocation
|
||||
|
||||
- **Chat**: Type `/` → select prompt
|
||||
- **Command**: `Chat: Run Prompt...`
|
||||
- **Editor**: Open prompt file → play button
|
||||
|
||||
**Tip**: Use `chat.promptFilesRecommendations` to show prompts as actions when starting a new chat.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Generate test cases for specific code
|
||||
- Create READMEs from specs
|
||||
- Summarize metrics with custom parameters
|
||||
- One-off generation tasks
|
||||
|
||||
## Core Principles
|
||||
|
||||
1. **Single task focus**: One prompt = one well-defined task
|
||||
2. **Output examples**: Show expected format when quality depends on structure
|
||||
3. **Reuse over duplication**: Reference instruction files instead of copying
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
- **Multi-task prompts**: "create and test and deploy" in one prompt
|
||||
- **Vague descriptions**: Descriptions that don't help users understand when to use
|
||||
- **Over-tooling**: Many tools when the task only needs search or file access
|
||||
@@ -0,0 +1,85 @@
|
||||
# [Agent Skills (SKILL.md)](https://code.visualstudio.com/docs/copilot/customization/agent-skills)
|
||||
|
||||
Folders of instructions, scripts, and resources that agents load on-demand for specialized tasks.
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
.github/skills/<skill-name>/
|
||||
├── SKILL.md # Required (name must match folder)
|
||||
├── scripts/ # Executable code
|
||||
├── references/ # Docs loaded as needed
|
||||
└── assets/ # Templates, boilerplate
|
||||
```
|
||||
|
||||
## Locations
|
||||
|
||||
| Path | Scope |
|
||||
|------|-------|
|
||||
| `.github/skills/<name>/` | Project |
|
||||
| `.agents/skills/<name>/` | Project |
|
||||
| `.claude/skills/<name>/` | Project |
|
||||
| `~/.copilot/skills/<name>/` | Personal |
|
||||
| `~/.claude/skills/<name>/` | Personal |
|
||||
|
||||
## SKILL.md Format
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: skill-name # Required: 1-64 chars, lowercase alphanumeric + hyphens, must match folder
|
||||
description: 'What and when to use. Max 1024 chars.'
|
||||
---
|
||||
```
|
||||
|
||||
### Body
|
||||
|
||||
- What the skill accomplishes
|
||||
- When to use (triggers and use cases)
|
||||
- Step-by-step procedures
|
||||
- References to resources: `[script](./scripts/test.js)`
|
||||
|
||||
## Template
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: webapp-testing
|
||||
description: 'Test web applications using Playwright. Use for verifying frontend, debugging UI, capturing screenshots.'
|
||||
---
|
||||
|
||||
# Web Application Testing
|
||||
|
||||
## When to Use
|
||||
- Verify frontend functionality
|
||||
- Debug UI behavior
|
||||
|
||||
## Procedure
|
||||
1. Start the web server
|
||||
2. Run [test script](./scripts/test.js)
|
||||
3. Review screenshots in `./screenshots/`
|
||||
```
|
||||
|
||||
## Progressive Loading
|
||||
|
||||
1. **Discovery** (~100 tokens): Agent reads `name` and `description`
|
||||
2. **Instructions** (<5000 tokens): Loads `SKILL.md` body when relevant
|
||||
3. **Resources**: Additional files load only when referenced
|
||||
|
||||
Keep file references one level deep from `SKILL.md`.
|
||||
|
||||
## When to Use
|
||||
|
||||
Repeatable, on-demand workflows with bundled assets (scripts, templates, reference docs).
|
||||
|
||||
## Core Principles
|
||||
|
||||
1. **Keyword-rich descriptions**: Include trigger words for discovery
|
||||
2. **Progressive loading**: Keep SKILL.md under 500 lines; use reference files
|
||||
3. **Relative paths**: Always use `./` for skill resources
|
||||
4. **Self-contained**: Include all procedural knowledge to complete the task
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
- **Vague descriptions**: "A helpful skill" doesn't enable discovery
|
||||
- **Monolithic SKILL.md**: Everything in one file instead of references
|
||||
- **Name mismatch**: Folder name doesn't match `name` field
|
||||
- **Missing procedures**: Descriptions without step-by-step guidance
|
||||
@@ -0,0 +1,64 @@
|
||||
# [Workspace Instructions](https://code.visualstudio.com/docs/copilot/customization/custom-instructions)
|
||||
|
||||
Guidelines that automatically apply to all chat requests across your entire workspace.
|
||||
|
||||
## File Types (Choose One)
|
||||
|
||||
| File | Location | Purpose |
|
||||
|------|----------|---------|
|
||||
| `copilot-instructions.md` | `.github/` | Project-wide standards (recommended, cross-editor) |
|
||||
| `AGENTS.md` | Root or subfolders | Open standard, monorepo hierarchy support |
|
||||
|
||||
Use **only one**—not both.
|
||||
|
||||
## AGENTS.md Hierarchy
|
||||
|
||||
For monorepos, the closest file in the directory tree takes precedence:
|
||||
|
||||
```
|
||||
/AGENTS.md # Root defaults
|
||||
/frontend/AGENTS.md # Frontend-specific (overrides root)
|
||||
/backend/AGENTS.md # Backend-specific (overrides root)
|
||||
```
|
||||
|
||||
## Template
|
||||
|
||||
Only include sections the workspace benefits from:
|
||||
|
||||
```markdown
|
||||
# Project Guidelines
|
||||
|
||||
## Code Style
|
||||
{Language and formatting preferences—reference key files that exemplify patterns}
|
||||
|
||||
## Architecture
|
||||
{Major components, service boundaries, the "why" behind structural decisions}
|
||||
|
||||
## Build and Test
|
||||
{Commands to install, build, test—agents will attempt to run these}
|
||||
|
||||
## Conventions
|
||||
{Patterns that differ from common practices—include specific examples}
|
||||
```
|
||||
|
||||
For large repos, link to detailed docs instead of embedding: `See docs/TESTING.md for test conventions.`
|
||||
|
||||
## When to Use
|
||||
|
||||
- General coding standards that apply everywhere
|
||||
- Team preferences shared through version control
|
||||
- Project-wide requirements (testing, documentation)
|
||||
|
||||
## Core Principles
|
||||
|
||||
1. **Minimal by default**: Only what's relevant to *every* task
|
||||
2. **Concise and actionable**: Every line should guide behavior
|
||||
3. **Link, don't embed**: Reference docs instead of copying
|
||||
4. **Keep current**: Update when practices change
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
- **Using both file types**: Having both `copilot-instructions.md` and `AGENTS.md`
|
||||
- **Kitchen sink**: Everything instead of what matters most
|
||||
- **Duplicating docs**: Copying README instead of linking
|
||||
- **Obvious instructions**: Conventions already enforced by linters
|
||||
Reference in New Issue
Block a user