feat: support agent skills for context-aware review guidance

[IsmaelMartinez]

Problem

PR-Agent's review guidance is either global (extra_instructions) or absent. There's no way to load domain-specific review knowledge that activates based on what's in the diff. Teams working across Terraform, CI pipelines, event schemas, and APIs need different guidance — but one flat extra_instructions string wastes context and dilutes relevance.

Issue #2311 asks about skills support. Issue #1766 asks for custom rules. Both point at the same gap.

Proposal: Agent Skills

Follow the agent skills standard used by Claude Code, Copilot CLI, and other AI tools. A skill is a directory containing a SKILL.md with YAML frontmatter and markdown body:

.pr_agent_skills/
├── terraform/
│   └── SKILL.md
├── gitlab-ci/
│   └── SKILL.md
└── event-structure/
    └── SKILL.md

SKILL.md format

---
name: terraform-standards
description: Use when reviewing Terraform code to check for provider configuration, default_tags, layered architecture, and testing patterns
---

# Terraform Review Guidance

When reviewing Terraform, verify:
- Provider blocks have default_tags
- allowed_account_ids is set
- data.aws_iam_policy_document preferred over inline jsonencode
...

The description field is the activation signal — it describes when the skill is relevant, following the same pattern used across agent tooling ("Use when...").

How it works

1. Discovery: PR-Agent finds skills from configured paths (repo-local, globally installed, or both)
2. Activation: Skills are matched against the PR context. The description field is the activation signal. Implementation can use a lightweight pre-filter (keywords in description matched against file types/languages in the diff) or pass all descriptions to the model and let it select relevant guidance — either approach works, and the latter is more aligned with how interactive agents handle skills.
3. Injection: Activated skills' body content is appended to the prompt context, scoped per tool (review, improve, describe, etc.)

Configuration

[skills]
enabled = true
paths = [".pr_agent_skills/"]              # repo-local skills
installed = ["/opt/skills/org-standards/"] # org-wide installed skills
max_skills_tokens = 4000                   # cap total injected content

Repos can also configure skills in their .pr_agent.toml.

Why this design

• Follows the SKILL.md frontmatter + body standard — teams reuse skills across their AI toolchain (Claude Code, Copilot, PR-Agent) without maintaining separate formats
• Description-based activation is the standard pattern; implementation details (pre-filter vs. model-decides) can evolve without changing the skill format
• Skills are plain files in the repo — version-controlled, reviewable, composable
• Org-wide skills can be installed centrally and shared across repos
• Fits naturally into PR-Agent's existing architecture: skills content flows through the same extra_instructions injection point in the Jinja2 templates

Compatibility with existing features

This complements rather than replaces existing mechanisms:

• extra_instructions remains for simple one-line overrides
• best_practices.md (once OSS build silently ignores best_practices.md (currently SaaS-only) #2377 / feat: Implement the documented "add_repo_metadata" functionality #2304 land) provides global guidance
• Skills add structured, conditional, reusable guidance on top

Offer to implement

We're running pr-agent self-hosted (GitLab + AWS Bedrock) with a library of domain-specific skills. Happy to implement this and submit a PR. The implementation touches: skill loader in pr_agent/algo/, config schema in configuration.toml, and injection into the existing vars/template pipeline.

Refs: #2311, #1766