Awesome/awesome-copilot
1
0
Fork 0
mirror of https://github.com/github/awesome-copilot.git synced 2026-02-20 02:15:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update agent instruction file

Browse Source
This commit is contained in:
bmaucote
2026-01-16 17:53:14 +01:00
parent 204b6b0453
commit 3ffc10e4dd
1 changed files with 160 additions and 130 deletions
Download Patch File Download Diff File Expand all files Collapse all files

290
instructions/agents.instructions.md
View File

@@ -312,86 +312,91 @@ tools: ['playwright/navigate', 'playwright/screenshot'] # Specific tools
## Sub-Agent Invocation (Agent Orchestration) ## Sub-Agent Invocation (Agent Orchestration)
Agents can invoke other agents using `runSubagent` to orchestrate multi-step workflows. Agents can invoke other agents using the **agent invocation tool** (the `agent` tool) to orchestrate multi-step workflows.
The recommended approach is **prompt-based orchestration**:
- The orchestrator defines a step-by-step workflow in natural language.
- Each step is delegated to a specialized agent.
- The orchestrator passes only the essential context (e.g., base path, identifiers) and requires each sub-agent to read its own `.agent.md` spec for tools/constraints.
### How It Works ### How It Works
Include `agent` in tools list to enable sub-agent invocation: 1) Enable agent invocation by including `agent` in the orchestrator's tools list:
```yaml ```yaml
tools: ['read', 'edit', 'search', 'agent'] tools: ['read', 'edit', 'search', 'agent']
``` ```
Then invoke other agents with `runSubagent`: 2) For each step, invoke a sub-agent by providing:
- **Agent name** (the identifier users select/invoke)
- **Agent spec path** (the `.agent.md` file to read and follow)
- **Minimal shared context** (e.g., `basePath`, `projectName`, `logFile`)
```javascript ### Prompt Pattern (Recommended)
const result = await runSubagent({
description: 'What this step does',
prompt: `You are the [Specialist] specialist.
Context: Use a consistent “wrapper prompt” for every step so sub-agents behave predictably:
- Parameter: ${parameterValue}
- Input: ${inputPath}
- Output: ${outputPath}
Task: ```text
1. Do the specific work This phase must be performed as the agent "<AGENT_NAME>" defined in "<AGENT_SPEC_PATH>".
2. Write results to output location
3. Return summary of completion` IMPORTANT:
}); - Read and apply the entire .agent.md spec (tools, constraints, quality standards).
- Work on "<WORK_UNIT_NAME>" with base path: "<BASE_PATH>".
- Perform the necessary reads/writes under this base path.
- Return a clear summary (actions taken + files produced/modified + issues).
``` ```
Optional: if you need a lightweight, structured wrapper for traceability, embed a small JSON block in the prompt (still human-readable and tool-agnostic):
```text
{
"step": "<STEP_ID>",
"agent": "<AGENT_NAME>",
"spec": "<AGENT_SPEC_PATH>",
"basePath": "<BASE_PATH>"
}
```
### Orchestrator Structure (Keep It Generic)
For maintainable orchestrators, document these structural elements:
- **Dynamic parameters**: what values are extracted from the user (e.g., `projectName`, `fileName`, `basePath`).
- **Sub-agent registry**: a list/table mapping each step to `agentName` + `agentSpecPath`.
- **Step ordering**: explicit sequence (Step 1 → Step N).
- **Trigger conditions** (optional but recommended): define when a step runs vs is skipped.
- **Logging strategy** (optional but recommended): a single log/report file updated after each step.
Avoid embedding orchestration “code” (JavaScript, Python, etc.) inside the orchestrator prompt; prefer deterministic, tool-driven coordination.
### Basic Pattern ### Basic Pattern
Structure each sub-agent call with: Structure each step invocation with:
1. **description**: Clear one-line purpose of the sub-agent invocation 1. **Step description**: Clear one-line purpose (used for logs and traceability)
2. **prompt**: Detailed instructions with substituted variables 2. **Agent identity**: `agentName` + `agentSpecPath`
3. **Context**: A small, explicit set of variables (paths, IDs, environment name)
The prompt should include: 4. **Expected outputs**: Files to create/update and where they should be written
- Who the sub-agent is (specialist role) 5. **Return summary**: Ask the sub-agent to return a short, structured summary
- What context it needs (parameters, paths)
- What to do (concrete tasks)
- Where to write output
- What to return (summary)
### Example: Multi-Step Processing ### Example: Multi-Step Processing
```javascript ```text
// Step 1: Process data Step 1: Transform raw input data
const processing = await runSubagent({ Agent: data-processor
description: 'Transform raw input data', Spec: .github/agents/data-processor.agent.md
prompt: `You are the Data Processor specialist. Context: projectName=${projectName}, basePath=${basePath}
Project: ${projectName}
Input: ${basePath}/raw/ Input: ${basePath}/raw/
Output: ${basePath}/processed/ Output: ${basePath}/processed/
Expected: write ${basePath}/processed/summary.md
Task: Step 2: Analyze processed data (depends on Step 1 output)
1. Read all files from input directory Agent: data-analyst
2. Apply transformations Spec: .github/agents/data-analyst.agent.md
3. Write processed files to output Context: projectName=${projectName}, basePath=${basePath}
4. Create summary: ${basePath}/processed/summary.md
Return: Number of files processed and any issues found`
});
// Step 2: Analyze (depends on Step 1)
const analysis = await runSubagent({
description: 'Analyze processed data',
prompt: `You are the Data Analyst specialist.
Project: ${projectName}
Input: ${basePath}/processed/ Input: ${basePath}/processed/
Output: ${basePath}/analysis/ Output: ${basePath}/analysis/
Expected: write ${basePath}/analysis/report.md
Task:
1. Read processed files from input
2. Generate analysis report
3. Write to: ${basePath}/analysis/report.md
Return: Key findings and identified patterns`
});
``` ```
### Key Points ### Key Points
@@ -399,7 +404,7 @@ Return: Key findings and identified patterns`
- **Pass variables in prompts**: Use `${variableName}` for all dynamic values - **Pass variables in prompts**: Use `${variableName}` for all dynamic values
- **Keep prompts focused**: Clear, specific tasks for each sub-agent - **Keep prompts focused**: Clear, specific tasks for each sub-agent
- **Return summaries**: Each sub-agent should report what it accomplished - **Return summaries**: Each sub-agent should report what it accomplished
- **Sequential execution**: Use `await` to maintain order when steps depend on each other - **Sequential execution**: Run steps in order when dependencies exist between outputs/inputs
- **Error handling**: Check results before proceeding to dependent steps - **Error handling**: Check results before proceeding to dependent steps
### ⚠️ Tool Availability Requirement ### ⚠️ Tool Availability Requirement
@@ -416,13 +421,13 @@ The orchestrator's tool permissions act as a ceiling for all invoked sub-agents.
### ⚠️ Important Limitation ### ⚠️ Important Limitation
**Sub-agent orchestration is NOT suitable for large-scale data processing.** Avoid using `runSubagent` when: **Sub-agent orchestration is NOT suitable for large-scale data processing.** Avoid using multi-step sub-agent pipelines when:
- Processing hundreds or thousands of files - Processing hundreds or thousands of files
- Handling large datasets - Handling large datasets
- Performing bulk transformations on big codebases - Performing bulk transformations on big codebases
- Orchestrating more than 5-10 sequential steps - Orchestrating more than 5-10 sequential steps
Each sub-agent call adds latency and context overhead. For high-volume processing, implement logic directly in a single agent instead. Use orchestration only for coordinating specialized tasks on focused, manageable datasets. Each sub-agent invocation adds latency and context overhead. For high-volume processing, implement logic directly in a single agent instead. Use orchestration only for coordinating specialized tasks on focused, manageable datasets.
## Agent Prompt Structure ## Agent Prompt Structure
@@ -559,31 +564,25 @@ Process the **${projectName}** project located at `${basePath}`.
#### Passing Variables to Sub-Agents #### Passing Variables to Sub-Agents
When invoking a sub-agent, pass all context through template variables in the prompt: When invoking a sub-agent, pass all context through substituted variables in the prompt. Prefer passing **paths and identifiers**, not entire file contents.
```javascript Example (prompt template):
// Extract and prepare variables
const basePath = `projects/${projectName}`;
const inputPath = `${basePath}/src/`;
const outputPath = `${basePath}/docs/`;
// Pass to sub-agent with all variables substituted ```text
const result = await runSubagent({ This phase must be performed as the agent "documentation-writer" defined in ".github/agents/documentation-writer.agent.md".
description: 'Generate project documentation',
prompt: `You are the Documentation specialist.
Project: ${projectName} IMPORTANT:
Input: ${inputPath} - Read and apply the entire .agent.md spec.
Output: ${outputPath} - Project: "${projectName}"
- Base path: "projects/${projectName}"
- Input: "projects/${projectName}/src/"
- Output: "projects/${projectName}/docs/"
Task: Task:
1. Read source files from ${inputPath} 1. Read source files under the input path.
2. Generate comprehensive documentation 2. Generate documentation.
3. Write to ${outputPath}/index.md 3. Write outputs under the output path.
4. Include code examples and usage guides 4. Return a concise summary (files created/updated, key decisions, issues).
Return: Summary of documentation generated (file count, word count)`
});
``` ```
The sub-agent receives all necessary context embedded in the prompt. Variables are resolved before sending the prompt, so the sub-agent works with concrete paths and values, not variable placeholders. The sub-agent receives all necessary context embedded in the prompt. Variables are resolved before sending the prompt, so the sub-agent works with concrete paths and values, not variable placeholders.
@@ -592,63 +591,94 @@ The sub-agent receives all necessary context embedded in the prompt. Variables a
Example of a simple orchestrator that validates code through multiple specialized agents: Example of a simple orchestrator that validates code through multiple specialized agents:
```javascript 1) Determine shared context:
async function reviewCodePipeline(repositoryName, prNumber) { - `repositoryName`, `prNumber`
const basePath = `projects/${repositoryName}/pr-${prNumber}`; - `basePath` (e.g., `projects/${repositoryName}/pr-${prNumber}`)
// Step 1: Security Review 2) Invoke specialized agents sequentially (each agent reads its own `.agent.md` spec):
const security = await runSubagent({
description: 'Scan for security vulnerabilities',
prompt: `You are the Security Reviewer specialist.
Repository: ${repositoryName} ```text
PR: ${prNumber} Step 1: Security Review
Code: ${basePath}/changes/ Agent: security-reviewer
Spec: .github/agents/security-reviewer.agent.md
Context: repositoryName=${repositoryName}, prNumber=${prNumber}, basePath=projects/${repositoryName}/pr-${prNumber}
Output: projects/${repositoryName}/pr-${prNumber}/security-review.md
Step 2: Test Coverage
Agent: test-coverage
Spec: .github/agents/test-coverage.agent.md
Context: repositoryName=${repositoryName}, prNumber=${prNumber}, basePath=projects/${repositoryName}/pr-${prNumber}
Output: projects/${repositoryName}/pr-${prNumber}/coverage-report.md
Step 3: Aggregate
Agent: review-aggregator
Spec: .github/agents/review-aggregator.agent.md
Context: repositoryName=${repositoryName}, prNumber=${prNumber}, basePath=projects/${repositoryName}/pr-${prNumber}
Output: projects/${repositoryName}/pr-${prNumber}/final-review.md
```
#### Example: Conditional Step Orchestration (Code Review)
This example shows a more complete orchestration with **pre-flight checks**, **conditional steps**, and **required vs optional** behavior.
**Dynamic parameters (inputs):**
- `repositoryName`, `prNumber`
- `basePath` (e.g., `projects/${repositoryName}/pr-${prNumber}`)
- `logFile` (e.g., `${basePath}/.review-log.md`)
**Pre-flight checks (recommended):**
- Verify expected folders/files exist (e.g., `${basePath}/changes/`, `${basePath}/reports/`).
- Detect high-level characteristics that influence step triggers (e.g., repo language, presence of `package.json`, `pom.xml`, `requirements.txt`, test folders).
- Log the findings once at the start.
**Step trigger conditions:**
| Step | Status | Trigger Condition | On Failure |
|------|--------|-------------------|-----------|
| 1: Security Review | **Required** | Always run | Stop pipeline |
| 2: Dependency Audit | Optional | If a dependency manifest exists (`package.json`, `pom.xml`, etc.) | Continue |
| 3: Test Coverage Check | Optional | If test projects/files are present | Continue |
| 4: Performance Checks | Optional | If perf-sensitive code changed OR a perf config exists | Continue |
| 5: Aggregate & Verdict | **Required** | Always run if Step 1 completed | Stop pipeline |
**Execution flow (natural language):**
1. Initialize `basePath` and create/update `logFile`.
2. Run pre-flight checks and record them.
3. Execute Step 1 → N sequentially.
4. For each step:
- If trigger condition is false: mark as **SKIPPED** and continue.
- Otherwise: invoke the sub-agent using the wrapper prompt and capture its summary.
- Mark as **SUCCESS** or **FAILED**.
- If the step is **Required** and failed: stop the pipeline and write a failure summary.
5. End with a final summary section (overall status, artifacts, next actions).
**Sub-agent invocation prompt (example):**
```text
This phase must be performed as the agent "security-reviewer" defined in ".github/agents/security-reviewer.agent.md".
IMPORTANT:
- Read and apply the entire .agent.md spec.
- Work on repository "${repositoryName}" PR "${prNumber}".
- Base path: "${basePath}".
Task: Task:
1. Scan code for OWASP Top 10 vulnerabilities 1. Review the changes under "${basePath}/changes/".
2. Check for injection attacks, auth flaws 2. Write findings to "${basePath}/reports/security-review.md".
3. Write findings to ${basePath}/security-review.md 3. Return a short summary with: critical findings, recommended fixes, files created/modified.
```
Return: List of critical, high, and medium issues found` **Logging format (example):**
});
// Step 2: Test Coverage Check ```markdown
const coverage = await runSubagent({ ## Step 2: Dependency Audit
description: 'Verify test coverage for changes', **Status:** ✅ SUCCESS / ⚠️ SKIPPED / ❌ FAILED
prompt: `You are the Test Coverage specialist. **Trigger:** package.json present
**Started:** 2026-01-16T10:30:15Z
Repository: ${repositoryName} **Completed:** 2026-01-16T10:31:05Z
PR: ${prNumber} **Duration:** 00:00:50
Changes: ${basePath}/changes/ **Artifacts:** reports/dependency-audit.md
**Summary:** [brief agent summary]
Task:
1. Analyze code coverage for modified files
2. Identify untested critical paths
3. Write report to ${basePath}/coverage-report.md
Return: Current coverage percentage and gaps`
});
// Step 3: Aggregate Results
const finalReport = await runSubagent({
description: 'Compile all review findings',
prompt: `You are the Review Aggregator specialist.
Repository: ${repositoryName}
Reports: ${basePath}/*.md
Task:
1. Read all review reports from ${basePath}/
2. Synthesize findings into single report
3. Determine overall verdict (APPROVE/NEEDS_FIXES/BLOCK)
4. Write to ${basePath}/final-review.md
Return: Final verdict and executive summary`
});
return finalReport;
}
``` ```
This pattern applies to any orchestration scenario: extract variables, call sub-agents with clear context, await results. This pattern applies to any orchestration scenario: extract variables, call sub-agents with clear context, await results.