adding-prompts.mdc•4.69 kB
---
description: Guide for adding new prompts that orchestrate tools and resources.
globs:
alwaysApply: false
---
# Adding New Prompts
Guide for adding new prompts that orchestrate tools and resources.
## Prompt Structure
Prompts are pre-configured workflows that guide LLMs through complex tasks:
1. **Definition** - Schema in `promptDefinitions.ts`
2. **Handler** - Logic in `prompts.ts`
3. **Tests** - Unit tests in `prompts.test.ts`
4. **Evals** - Integration tests (use sparingly)
## Step 1: Define the Prompt
Add to `packages/mcp-server/src/promptDefinitions.ts`:
```typescript
{
name: "your_prompt_name" as const,
description: [
"One-line summary of what this prompt accomplishes.",
"When to use this prompt.",
"What resources it leverages.",
].join("\n"),
paramsSchema: {
organizationSlug: ParamOrganizationSlug,
yourParam: z.string().describe("Parameter purpose"),
includeContext: z.boolean().optional(),
timeRange: z.string().optional().describe("e.g., '24h', '7d'"),
},
}
```
## Step 2: Implement the Handler
Add to `packages/mcp-server/src/prompts.ts`:
```typescript
your_prompt_name: async (context, params) => {
// Validate parameters
if (!params.organizationSlug && !params.yourParam) {
throw new Error("Either organizationSlug or yourParam required");
}
// Build phased instructions
const instructions = [
`I'll ${describe_goal} in ${params.organizationSlug}.`,
"",
"## Phase 1: Gather Context",
"",
"Check available resources:",
];
// Conditionally add resource usage
if (params.includeContext) {
instructions.push(
"1. `user-session-context` for recent activity",
"2. `recent-activity-digest` for trends",
""
);
}
instructions.push(
"## Phase 2: Execute Actions",
"",
"1. Use `tool_name` with parameters:",
` - organizationSlug: "${params.organizationSlug}"`,
params.timeRange ? ` - timeRange: "${params.timeRange}"` : "",
"",
"## Phase 3: Synthesize Results",
"",
"Connect findings to context and suggest next steps.",
);
return instructions.join("\n");
};
```
## Step 3: Add Tests
```typescript
describe("your_prompt_name", () => {
it("generates context-aware instructions", async () => {
const result = await PROMPT_HANDLERS.your_prompt_name(
mockContext,
{
organizationSlug: "my-org",
includeContext: true,
timeRange: "24h",
}
);
expect(result).toContain("Phase 1: Gather Context");
expect(result).toContain("user-session-context");
expect(result).toContain("timeRange: \"24h\"");
});
it("adapts to parameters", async () => {
const minimal = await PROMPT_HANDLERS.your_prompt_name(
mockContext,
{ organizationSlug: "org" }
);
expect(minimal).not.toContain("user-session-context");
});
});
```
## Common Patterns
### Session-Aware Investigation
```typescript
return [
`Investigating ${issueType} with context.`,
"",
"## Context Foundation",
"1. Review `user-session-context` for:",
" - Recent search patterns",
" - Preferred filters",
"",
"## Contextual Analysis",
"2. Use `find_issues` with your typical filters",
"",
"## Pattern Recognition",
"3. Cross-reference with `organization-trends`",
].join("\n");
```
### Multi-Source Analysis
```typescript
return [
`Analyzing ${issueId} with all available data.`,
"",
"## Data Gathering",
"1. `get_issue_details` for structured data",
"2. `issue-attachments` for screenshots/logs",
"3. `project-health-snapshot` for system state",
"",
"## Synthesis",
"Combine all sources for comprehensive diagnosis.",
].join("\n");
```
### Flexible Parameters
```typescript
// Support multiple input patterns
let contextMessage: string;
if (params.issueUrl) {
contextMessage = `Using issue URL: ${params.issueUrl}`;
} else if (params.organizationSlug && params.issueId) {
contextMessage = `Issue ${params.issueId} in ${params.organizationSlug}`;
} else {
throw new Error("Provide issueUrl or org+issueId");
}
```
## Best Practices
1. **Resource-first approach** - Check context before actions
2. **Clear phases** - Structure as Context → Actions → Synthesis
3. **Conditional logic** - Adapt to available parameters
4. **Explicit guidance** - Tell LLM which resources and why
5. **Actionable output** - End with specific next steps
## Testing
```bash
# Unit tests
pnpm test prompts.test
# Minimal evals (expensive!)
pnpm eval your-prompt
```
## References
- Prompt examples: `packages/mcp-server/src/prompts.ts`
- Resource patterns: `adding-resources.mdc`
- Common patterns: `common-patterns.mdc`