Skills & Prompts

Overview

A skill file is a plain Markdown (.md) file that contains natural-language instructions for the AI. Rather than embedding prompt text inside the plugin settings (which is per-developer and not shareable), skill files live inside your project and can be committed to source control.

This means your entire team automatically uses the same prompt rules, coding standards, and review persona — and any change is tracked in your Git history just like any other code change.

File Location

All skill files live under a fixed path inside the project directory:

<project-root>/
└── .idea/
    └── pr-pilot/
        └── skills/
            ├── system_prompt.md
            ├── review_rules.md
            └── coding_standards.md

<project-root>/
└── .vscode/
    └── pr-pilot/
        └── skills/
            ├── system_prompt.md
            ├── review_rules.md
            └── coding_standards.md

This directory is created automatically the first time you open a workspace after installing PR Pilot. The three default files are seeded from templates bundled inside the extension — they are safe starting points that your team can then customise.

# .gitignore — allow PR Pilot skill files
.idea/
!.idea/pr-pilot/
!.idea/pr-pilot/skills/
!.idea/pr-pilot/skills/*.md

# .gitignore — allow PR Pilot skill files
.vscode/
!.vscode/pr-pilot/
!.vscode/pr-pilot/skills/
!.vscode/pr-pilot/skills/*.md

system_prompt.md

Defines the AI reviewer's identity, behaviour, tone, and output format. This is the first block of text injected as a system message — it shapes every response the AI gives.

Example customisation — security-focused persona

# PR Pilot — System Prompt

You are a security-focused code reviewer specialising in
OWASP Top 10 vulnerabilities and secure coding practices.

## Behaviour
- Prioritise security issues above all other feedback
- Always check for: SQL injection, XSS, CSRF, auth bypass,
  insecure deserialization, path traversal
- Flag every hardcoded credential or secret immediately

## Output Format
1. **Security Summary** — critical issues first
2. **File Analysis** — annotated with OWASP references
3. **Risk Score** — Low / Medium / High / Critical

Inline Comment Format in system_prompt.md

PR Pilot uses a delimiter-based JSON block to extract per-line comments from the AI response. The system_prompt.md instructs the AI to append this block at the end of every reply. The plugin parses it and uses it to post inline comments on the pull request.

Required block in system_prompt.md

The following section must appear verbatim in your system_prompt.md, at the end of the file after all other instructions:

# MANDATORY: Inline Comments Block

You MUST end EVERY response with the following block, no exceptions.
It will be machine-parsed — the delimiters and JSON format must be exact.

IMPORTANT:
Do NOT wrap the JSON in a markdown code fence (no ```json).
Output it as raw text between the two HTML comment tags.

<!-- INLINE_COMMENTS_START -->
[
  {
    "file": "relative/path/to/File.kt",
    "line": 42,
    "severity": "warning",
    "comment": "Explain the specific issue on this line and how to fix it."
  }
]
<!-- INLINE_COMMENTS_END -->

Rules for the inline comments JSON:

- Output the two HTML comment delimiters EXACTLY as shown — on their own lines
- The content between the delimiters must be a valid JSON array (even if empty: [])
- Do NOT use markdown code fences around the JSON
- Each entry must contain:
  - "file" (relative file path)
  - "line" (integer line number)
  - "severity" ("critical" | "warning" | "suggestion")
  - "comment" (clear actionable explanation)

Additional requirements:

- Only include lines with a clear actionable issue
- Prefer 3–10 comments when meaningful issues exist
- Avoid duplicate or redundant comments
- If nothing warrants an inline comment, output an empty array: []

Field reference

How the plugin parses it

1. The full AI response is searched for <!-- INLINE_COMMENTS_START -->.
2. Everything before that delimiter is treated as the summary and rendered in the review dialog.
3. The JSON between the two delimiters is extracted and deserialized into line comments.
4. Any accidental ```json fencing is automatically stripped before parse.
5. If deserialization fails or the delimiters are absent, the plugin falls back to summary-only display — no error is thrown to the user.

Example — valid AI output

## Overview
This PR adds a payment gateway integration. Overall the approach is sound, but
there are two issues requiring attention before merging.

## File Analysis
...

<!-- INLINE_COMMENTS_START -->
[
  {"file":"src/payment/PaymentService.kt","line":87,"severity":"critical","comment":"🔴 API key is hardcoded. Move to environment configuration or a secrets manager."},
  {"file":"src/payment/PaymentService.kt","line":112,"severity":"warning","comment":"🟡 Missing null-check on `response.body` — will throw NPE if the gateway returns an empty response."},
  {"file":"src/payment/PaymentRepository.kt","line":34,"severity":"suggestion","comment":"🟢 Consider extracting the query into a named constant for readability."}
]
<!-- INLINE_COMMENTS_END -->

review_rules.md

A checklist of what the AI should look for during the review. Each section can be toggled on/off simply by deleting or commenting it out.

Example customisation — frontend React team

# PR Pilot — Review Rules

## Accessibility
- Check all interactive elements have aria-labels
- Verify images have meaningful alt text
- Ensure keyboard navigation works correctly

## React Best Practices
- Flag unnecessary re-renders (missing useMemo / useCallback)
- Check for direct state mutation
- Verify useEffect cleanup functions are present

## Bundle Size
- Note any large new dependencies
- Flag synchronous imports that should be lazy-loaded

coding_standards.md

Your team's style guide and architecture rules in plain English. The AI will validate submitted code against these standards and flag violations.

Adding Custom Skill Files

You are not limited to the three default files. Any .md file placed in .idea/pr-pilot/skills/.vscode/pr-pilot/skills/ is automatically picked up and included in the AI prompt.

Example additional skill files you could create:

How Skills Are Injected Into the AI Prompt

When you click the AI Summary button, PR Pilot builds the full prompt in four layers:

1. Skills block (system message 1) — all .md files from .idea/pr-pilot/skills/.vscode/pr-pilot/skills/ are concatenated and sent as the first system message. This establishes persona, rules, and standards.
2. PR context (system message 2) — PR ID, title, author, source/target branches, and file count. The AI always knows which PR it is reviewing.
3. Code analysis (user message) — structured data for each changed file: language, total lines, impacted classes/methods with line numbers, and a truncated file snippet.
4. Referenced files — files that are imported by changed files (but not themselves changed) are included as additional context so the AI understands the full call graph.

Sharing Skills With Your Team

The most powerful use of skill files is committing them to source control so every team member automatically gets the same AI configuration when they pull.

Recommended workflow

1. Let PR Pilot seed the default files on first run.
2. Edit them to match your team's standards.
3. Update .gitignore to allow the skills directory (see the note in File Location).
4. Commit and push: git add .idea/pr-pilot/skills/ && git commit -m "chore: add PR Pilot skill files"git add .vscode/pr-pilot/skills/ && git commit -m "chore: add PR Pilot skill files"
5. All team members who pull this change will immediately get the updated AI behaviour — no settings changes required.

Editing Skill Files

You can edit skill files in three ways:

• Settings window: Go to Settings → PR Pilot → Skills & Prompts tab — inline text editors inside the settings window.
• Settings panel: Click the ⚙ gear icon in the PR Pilot panel → Skills & Prompts tab — inline text editors inside the settings panel.
• Any text editor: The files are plain Markdown; open them in IntelliJ's built-in editor or any other editor.
• VS Code editor: Open the .md file directly in VS Code — it supports Markdown preview.
• Any external editor: The files are plain Markdown; edit them however you prefer.

Changes to skill files on disk are reflected immediately the next time you click the AI Summary button — no restart required.