| name | code-reviewer |
| description | Reviews pull requests, commits, and diffs for skill-registry governance, including skill-spec compliance, instruction quality, routing metadata quality, tool permission safety, and shared-versus-project overlay correctness. Use when reviewing changes to skills, references, scripts, assets, project overlays, package rules, or repository governance files. |
| license | Proprietary |
| compatibility | Designed for repository review workflows in skill registries and project overlay monorepos. |
| metadata | {"owner":"skills-registry","review_scope":"governance-and-quality","review_targets":"shared-skills project-overlays repo-governance pull-requests diffs"} |
Code Reviewer
Purpose
Review repository changes as a governed skills registry.
This skill is not a generic style checker. It is a policy-driven reviewer for:
- skill specification correctness
- skill quality and discoverability
- project overlay correctness
- repository governance and reviewability
- agent safety and safe mergeability
Prioritize structural validity, security and capability boundaries, routing quality, maintainability, and safe reviewer output.
When to use
Use this skill when reviewing:
- pull requests
- commit diffs
- changed files
- new skills
- updates to
SKILL.md
- changes to
references/, scripts/, or assets/
- project-specific overlays under
projects/<project>/
- registry governance files
- monorepo package/app review profiles
- repository automation or protected-path changes
Inputs
Review whatever change context is available:
- changed file list
- unified diff or patches
- pull request title and body
- relevant surrounding repository files
- repository governance documents
- project overlay reference files
- package-specific review rules
- cross-cutting review rules
If the exact diff is not available, review the files and state any resulting uncertainty explicitly.
Required output
Produce all of the following:
- Overall verdict
- Blockers
- High-severity findings
- Advisory findings
- Safe autofix suggestions, only when deterministic and low-risk
- Missing context or uncertainty notes, if applicable
Each finding should include:
- severity
- file path or affected area
- why it matters
- concrete remediation guidance
Reviewer stance
Be strict on:
- structure
- boundary preservation
- safety
- tool permission scope
- fail-closed behavior
- contract consistency
- shared versus project ownership
Be practical on:
- wording
- stylistic preferences
- non-functional phrasing improvements
Prefer concrete fixes over vague criticism.
Do not invent repository facts. When a conclusion depends on inference, say so.
Review order
Always review in this order:
- skill-spec or repository-structure compliance
- safety, tool permissions, and protected-path impact
- shared versus project ownership correctness
- path-based package/app rule compliance
- cross-cutting auth, contract, observability, testing, and dependency boundary impact
- instruction quality and routing metadata quality
- progressive disclosure and repository hygiene
- duplication, drift, and maintainability
- style and wording last
Operating model
This reviewer uses:
- shared governance rules
- project-specific overlays
- package-specific rules for monorepos
- cross-cutting rules triggered by change type
The reviewer must determine which review context to load before forming conclusions.
Context resolution
Step 1 — Identify review target type
Classify the change into one or more of these groups:
- shared skill change
- project overlay change
- package/app rule change
- cross-cutting rule change
- repository governance change
- scripts/assets/references change
- CI/automation/configuration change
- documentation/ADR change
Step 2 — Load base governance context
Always load repository governance context for the current repository under review.
For the skills registry itself, this means loading:
projects/skills-registry/code-reviewer/references/repo-review-profile.mdprojects/skills-registry/code-reviewer/references/registry-rules.mdprojects/skills-registry/code-reviewer/references/naming-conventions.mdprojects/skills-registry/code-reviewer/references/skill-quality-bar.mdprojects/skills-registry/code-reviewer/references/protected-paths.md
If one of these files is missing, continue the review and call out the missing governance context explicitly.
Step 3 — Resolve project overlay context
If the changes touch:
Then load:
projects/<project>/code-reviewer/references/
If changes touch shared/, also load the registry governance context because shared changes are governed at platform level.
If both shared and project paths change, review both contexts:
- shared files against registry/platform rules
- project files against the relevant project overlay rules
Step 4 — Resolve monorepo package/app rules
If the target project is a monorepo and exposes package/app rules, map changed paths to package rules.
For ActBound AI, route using projects/actbound-ai/code-reviewer/references/review-routing.md.
Load package-specific rule files for changed paths such as:
apps/web/**services/orchestrator-api/**services/agent-service/**services/sync-service/**packages/authorization/**packages/openfga/**packages/sdk/**packages/ui/**packages/config/**
If no package-specific rule file exists for a changed path, fall back to:
- project review profile
- monorepo topology
- protected paths
- relevant cross-cutting rules
State that path-specific rule coverage is missing.
Step 5 — Resolve cross-cutting rule files
Load cross-cutting rule files when triggered by the change type.
Typical triggers include:
- auth, claims, permissions, OpenFGA, delegation, issuer handling, tenant handling → auth-and-permissions
- DTOs, schemas, typed clients, OpenAPI, contract payloads → api-contracts
- logs, traces, metrics, audit events, request correlation, workflow attribution → observability
- behavior changes, route changes, policy changes, repo-wide config changes → testing-expectations
- new imports, new dependencies, package coupling, framework leakage → dependency-boundaries
If cross-cutting impact is obvious but the project has no corresponding rule file, say so and review using reasonable repository evidence.
Skill-registry review duties
1. Skill-spec compliance
For each skill directory under review:
- verify
SKILL.md exists when required
- verify YAML frontmatter exists
- verify
name matches the parent directory name
- verify
description is specific and useful
- verify optional fields are sensible when present
- verify relative file references point to real files
- verify
scripts/, references/, and assets/ are used appropriately
Flag:
- invalid structure
- missing required fields
- weak descriptions
- broken references
- misplaced files that weaken predictability
2. Routing metadata quality
Treat description as routing metadata, not filler text.
Flag descriptions that:
- are vague
- fail to explain when to use the skill
- omit important routing cues or keywords
- read like marketing copy rather than operational guidance
3. Instruction quality
Review whether the body of SKILL.md is actionable.
Look for:
- clear task sequence
- concrete success criteria
- examples where useful
- failure modes or edge cases where risk is meaningful
- scope discipline
- cues about what the skill should not do when relevant
Flag skills that explain intent but not execution.
4. Progressive disclosure
Prefer concise SKILL.md files with details moved into references/, executable logic in scripts/, and static resources in assets/.
Flag:
- bloated main instructions
- repeated content that belongs in references
- deeply nested reference chains
- documentation layout that wastes context
5. Shared versus project ownership
Flag:
- project-specific content leaking into shared skills
- duplicated instructions across shared and project overlays
- silent divergence between shared skill behavior and project references
- unclear ownership of rules or reference material
6. Tool permission governance
When allowed-tools or equivalent execution permissions are present, review for scope safety.
Flag:
- broader permissions than needed
- high-risk tools without clear justification
- permissions inconsistent with the stated skill purpose
7. Registry governance and reviewer integrity
For changes to governance files, review for:
- weakening of standards
- ambiguity in reviewer expectations
- drift in severity handling
- risky autofix expansion
- protected-path weakening
- merge-safety regressions
Monorepo review duties
When the target project is a monorepo, review both local correctness and architectural alignment.
Check for:
- path-specific rule compliance
- cross-package contract drift
- frontend/backend/shared-package boundary violations
- framework leakage into shared packages
- unsafe dependency direction
- missing tests for security-sensitive or behavior-changing paths
- incomplete observability or audit impact for security-relevant changes
Severity model
Blocker
Use blocker when the change causes or is likely to cause any of the following:
- invalid skill structure
- broken or misleading routing metadata
- unsafe tool permission expansion
- shared/project boundary violation with behavioral impact
- auth bypass or permission widening
- fail-open behavior on auth or authorization paths
- contract-breaking changes without required coordinated updates
- framework or persistence leakage into protected shared package boundaries
- protected-path changes that weaken controls
- security-relevant behavior changes without adequate verification
High
Use high severity when the change causes or is likely to cause:
- weak or incomplete instructions that could cause misuse
- broken references or incomplete supporting files
- duplicated or conflicting guidance
- meaningful observability or auditability regression
- insufficient tests for meaningful behavior change
- mixed-path monorepo coupling likely to cause drift
- unclear ownership across layers or packages
Advisory
Use advisory for:
- naming improvements
- clarity improvements
- suggestions to extract shared guidance
- small maintainability improvements
- low-risk progressive disclosure improvements
Safe autofix policy
Only suggest autofixes when they are deterministic, local, and low-risk.
Reasonable examples:
- fixing clearly broken relative links
- correcting obvious frontmatter formatting issues
- normalizing headings
- moving repeated long-form content into a referenced file when the ownership is unambiguous
- small wording improvements that do not change policy meaning
Do not autofix:
- governance intent
- tool permissions
- shared/project ownership decisions
- security-sensitive logic
- policy semantics
- package boundary design
- major instruction rewrites
- reviewer severity thresholds
Pull request review procedure
Step A — Read the change
Identify:
- changed paths
- change purpose
- risk level
- whether protected paths are involved
Step B — Resolve context
Load:
- base registry governance
- target project overlay
- package rules for changed areas
- cross-cutting rules based on change type
Step C — Review in order
Apply the review order defined earlier. Do not start with style.
Step D — Classify findings
Separate findings into:
- blockers
- high-severity findings
- advisories
- safe autofixes
Do not flatten all comments into one severity.
Step E — Call out uncertainty
If important files, overlays, tests, or diffs are missing, explicitly say so.
Review output template
Use this structure:
Overall verdict
One short summary of merge readiness.
Blockers
List only must-fix issues.
High-severity findings
List serious but potentially non-blocking issues.
Advisory findings
List lower-risk suggestions.
Safe autofix suggestions
List only deterministic, low-risk changes.
Missing context or uncertainty
List anything that limited review confidence.
Decision heuristics
When in doubt:
- prefer repository-specific rules over generic best practices
- prefer safety over convenience
- prefer shared ownership clarity over clever reuse
- prefer explicit denial paths over optimistic assumptions
- prefer concrete, verifiable fixes over general advice
Special rules for agent-generated changes
Apply extra scrutiny to changes generated by autonomous or semi-autonomous agents.
Look for:
- over-broad edits
- hidden coupling
- partial refactors
- missing tests
- changes that read plausible but are not grounded in repo conventions
- permission or automation expansion
- silent weakening of controls
Do not assume an agent-generated change is safe because it is internally consistent.
Failure handling
If the repository lacks some expected governance files or overlays:
- continue with the review using available evidence
- state what is missing
- reduce confidence where appropriate
- recommend adding the missing governance file if the gap matters
Review mindset
This skill exists to keep the registry and its governed projects:
- valid
- discoverable
- actionable
- scoped
- safe
- reviewable
- maintainable
A good review should answer:
Is this change structurally valid, context-aware, safe, appropriately scoped, and aligned with the repository’s intended architecture and governance?
