name: agent-patch description: Applies semantic patches to agent prompts. Use when you need to update prompts based on .agent.patch files, migrate prompts to new tool versions, or enforce consistent behaviors across agent skills.

Agent Patch

Apply semantic patches to agent prompts by matching intent and behavior rather than literal text.

When to Use

• Migrating agent prompts to work with updated tools or APIs
• Applying security guardrails or compliance requirements
• Propagating best practices across multiple agent skills
• Updating prompts based on shared patch files

Workflow

1. Gather inputs

   • Ask for the target prompt (file path or pasted content)
   • Ask for the patch file(s) to apply (file path or glob pattern like patches/*.agent.patch)

2. Check scope

   • Read the patch's front matter description field to determine scope
   • Semantic descriptions (e.g., "agents that handle file operations") require analyzing the prompt's purpose
   • Glob patterns (e.g., **/skills/*.md) match against the file path

3. Match GIVEN clauses

   • For each GIVEN in the patch, determine if the target prompt contains that behavior or intent
   • Match semantically: look for what the prompt does, not literal text
   • Use examples in blockquotes (if provided) to understand what should match

4. Evaluate WHEN conditions

   • If a GIVEN has a WHEN clause, check if the additional condition applies
   • WHEN narrows the match—the GIVEN must match AND the WHEN must be true
   • Negative conditions ("no mention of...", "missing...") check for absence

5. Apply THEN changes

   • For each matched GIVEN (with passing WHEN), apply the THEN instruction
   • Apply changes semantically: modify the behavior/intent as described
   • Use examples in blockquotes (if provided) to guide the transformation
   • Preserve the prompt's style, tone, and structure where possible

6. Output the result

   • Show which patches were applied and which were skipped (with reasons)
   • Write the modified prompt to a file (same location or user-specified)

Matching Strategy

Semantic Matching

GIVEN clauses describe intent, not literal text. When matching:

• Analyze behavior: What does this section of the prompt instruct the agent to do?
• Consider purpose: Why is this instruction included?
• Look for equivalents: Different wording can express the same intent

Example: A GIVEN of "the agent retries failed API calls" matches prompts that say:

• "If the API returns an error, try again up to 3 times"
• "Implement exponential backoff for failed requests"
• "On failure, wait and retry the operation"

Scope Matching

The front matter description field determines if a patch applies:

Handling Multiple Patches

When applying multiple patches:

1. Apply patches in order (first to last)
2. Each patch sees the result of previous patches
3. Report conflicts if two patches modify the same behavior differently
4. Skip patches whose scope doesn't match the target

Output Format

After applying patches, provide a summary:

## Patch Application Summary

**Target**: path/to/prompt.md

### Applied
- cli-migration.agent.patch
  - GIVEN: uses --verbose flag → replaced with --log-level=debug
  - GIVEN: parses output as text → now parses as JSON

### Skipped
- security-patch.agent.patch
  - Reason: description "agents that access databases" does not match

### Conflicts
- (none)

Then write the modified prompt to a file.

Example

Patch file (cli-v2.agent.patch):

---
description: agents that execute shell commands
---

GIVEN the agent uses the --verbose flag
THEN replace --verbose with --log-level=debug

Before (target prompt):

When debugging, run the command with --verbose to see detailed output.

After (patched prompt):

When debugging, run the command with --log-level=debug to see detailed output.

The change is semantic—the exact wording may differ as long as the behavior matches the THEN instruction.