Skip to content

1901 aligning coding standards skill discovery #2358

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
vdstrizhkova wants to merge 9 commits into
base: main
Choose a base branch
from
Open

1901 aligning coding standards skill discovery #2358

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
ff26b45
1901 aligning coding standards skill discovery
Jul 3, 2026
6addb8e
feat(agents): align standards skill discovery and
Jul 6, 2026
5e18560
Removed reference to the ticket
Jul 6, 2026
6559271
Merge branch 'main' into feat/1901-align-coding-standards-skill-disco…
vdstrizhkova Jul 6, 2026
7184e24
Removed the path-based discovery model,
Jul 6, 2026
ab407f0
Merge branch 'main' into feat/1901-align-coding-standards-skill-disco…
vdstrizhkova Jul 6, 2026
400aa34
Merge branch 'main' into feat/1901-align-coding-standards-skill-disco…
vdstrizhkova Jul 7, 2026
29708ee
Merge branch 'main' into feat/1901-align-coding-standards-skill-disco…
WilliamBerryiii Jul 23, 2026
81bad11
Merge branch 'main' into feat/1901-align-coding-standards-skill-disco…
WilliamBerryiii Jul 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 8 additions & 2 deletions .github/agents/coding-standards/subagents/code-review-standards.agent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,12 +31,18 @@ Do not invent severity levels, categories, or output fields the skill does not d

* **Perspective**: Standards review (apply the Standards review checklist from lens-checklists.md).
* **Skill trace**: Every standards finding must trace to a loaded `coding-standards` skill, referenced by its exact `name` from frontmatter. Never invent categories or standards. A severe issue not covered by any skill belongs in `out_of_scope_observations`, clearly marked "Not backed by project standards."
* **Lane boundary**: Stay within skill-backed standards. Do not flag logic errors, edge cases, concurrency, or contract bugs — the Functional perspective owns those. Security findings are in-lane only when a loaded skill addresses the pattern.
* **Lane boundary**: Stay within skill-backed standards. Do not flag logic errors, edge cases, concurrency, or contract bugs; the Functional perspective owns those. Security findings are in-lane only when a loaded skill addresses the pattern.

## Required Steps

1. **Read input.** Read `diff-state.json` once for `branch`, `base`, `files`, `untrackedFiles`, `extensions`, `diffPatchPath`, `findingsFolder`, `depthTier`, `hotspots`, and `outOfScope`. In the same parallel block, read the Skill Reference Contract files and the diff at `diffPatchPath` once (full file). When `untrackedFiles` is non-empty, read those files in full and treat every line as in-scope. Do not re-read the diff for any reason.
2. **Discover and load skills.** Using the `extensions` and `files` lists, search the available `coding-standards` skills for ones whose `name` or `description` matches the detected languages, frameworks, or literal extensions. Load up to 8 matching skills. When no relevant skills are found, emit no standards findings — produce only `summary`, `verdict`, `severity_counts`, `changed_files`, and `risk_assessment`, leave the finding arrays empty, and note "Review conducted without a matching skill catalog."
2. **Discover and load skills.** Select relevant `coding-standards` skills from the skills already available to the agent.
* **Select matches.** Match skills by exact or obvious language, framework, or literal extension from `extensions` and `files`. Prefer `name` matches over `description` matches.
* **Define file groups.** For coverage decisions, treat each distinct literal extension in `extensions` as a changed file group. Also treat obvious framework or tool signals from `files` as groups when they appear in filenames or path segments. If a language or framework is uncertain, use the literal extension group rather than inferring a broader group.
* **Preserve origin evidence.** Keep each candidate skill's exact `name`, `description`, and any source label or path together throughout selection. Treat workspace paths as Workspace, user-profile paths or labels as User, and extension, plugin, or bundled labels as Bundled. If no source label or path is available, mark the origin as Unknown rather than inferring it from content.
* **Resolve duplicates.** If same-named skills are available and their origin is identifiable, prefer Workspace over User over Bundled. If origin is Unknown, load one same-named skill only, do not merge bodies, and mention the ambiguous duplicate in the one-line return summary.
* **Load stacked skills.** Load distinct-named matches needed to cover every changed language, framework, or literal extension so their checklists stack. Do not drop a skill if it is the only match for any changed file group. When many skills match, include additional skills only when they cover otherwise-uncovered file groups; drop description-only matches first.

@rezatnoMsirhC rezatnoMsirhC Jul 9, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The previous step 2 had an explicit ceiling of "up to 8 matching skills." That cap appears to have been removed in this revision. Was that intentional?

The new stacking heuristic (cover every changed file group, drop description-only matches first) is a quality improvement, but on a diff that genuinely touches many distinct languages or frameworks, there is no longer a hard upper bound on how many skills the agent loads. On smaller models, an unbounded load could exhaust the context window.

If the removal was unintentional, consider appending "Load at most 8 skills total." to this sub-bullet to restore the guard.

* **Handle conflicts and empty matches.** If distinct skills conflict, surface each backed finding and cite its skill `name`. If no skill matches, write the normal output schema with empty finding arrays and note "Review conducted without a matching skill catalog."
3. **Apply skills at depth.** Apply each loaded skill's checklist plus the Standards checklist to the diff. Apply the `depthTier` rigor dial from depth-tiers.md. Give deeper scrutiny to `hotspots`; skip `outOfScope`. When a story definition is provided in the prompt, produce an `acceptance_criteria_coverage` entry per AC (Implemented, Partial, or Not found).
4. **Grade and record findings.** Assign severity per severity-taxonomy.md. For each finding capture file, line range, category, the originating skill `name`, problem, the exact `current_code`, and a concrete `suggested_fix`.
5. **Write structured findings.** Write `<findingsFolder>/standards-findings.json` using the Output contract schema from output-formats.md, setting each finding's `skill` to the originating skill name. Do not write a markdown report. Return a one-line summary of severity counts, loaded skills, and the findings file path.
Expand Down
6 changes: 3 additions & 3 deletions docs/agents/code-review/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ tags:
- code-review
- coding-standards
author: Microsoft
ms.date: 2026-06-26
ms.date: 2026-07-02
ms.topic: concept
estimated_reading_time: 10
---
Expand Down Expand Up @@ -124,7 +124,7 @@ The review workflow lives in the `code-review` skill, not in the agent. The orch
| Severity Taxonomy | Severity levels, verdict normalization, and risk classification |
| Output Formats | Reporting structure, merged report skeleton, and persisted artifact schema |

The Standards perspective is language-agnostic: it scans the workspace for `**/SKILL.md` files, matches them against the languages in the diff, and loads the relevant `coding-standards` skills. See [Language Skills](language-skills.md) for details on the built-in skills and how to create your own.
The Standards perspective is language-agnostic: it discovers `coding-standards` skills from the built-in hve-core baseline and supported repository skill roots, de-duplicates same-named skills with repository precedence, matches the remaining candidates against the languages in the diff, and loads the relevant skills. See [Language Skills](language-skills.md) for details on built-in skills, supported discovery roots, skill stacking, and conflict behavior.

## How the Review Works

Expand Down Expand Up @@ -281,7 +281,7 @@ The agent works with any programming language. Standards and accessibility enfor

## Extending with Custom Skills

The Standards and Accessibility perspectives discover skills dynamically at review time. You extend coverage by adding `SKILL.md` files to your repository without modifying the agent itself. See [Language Skills](language-skills.md) for the full guide on built-in skills, skill stacking, and authoring enterprise-specific standards.
The Standards perspective discovers coding-standards skills dynamically at review time. You extend coverage by adding `SKILL.md` files under a supported repository skill root without modifying the agent itself. See [Language Skills](language-skills.md) for the full guide on built-in skills, skill stacking, same-name precedence, and authoring enterprise-specific standards.

@rezatnoMsirhC rezatnoMsirhC Jul 9, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The previous sentence also covered the Accessibility perspective: "The Standards and Accessibility perspectives discover skills dynamically at review time." That reference has been removed here.

Was this intentional scoping for this PR? If the Accessibility perspective still supports custom skill authoring, consider keeping a mention rather than dropping it entirely. For example:

The Standards perspective discovers coding-standards skills dynamically at review time; the Accessibility perspective uses the same extension mechanism for accessibility skills. You extend either by adding SKILL.md files under a supported repository skill root without modifying the agent itself.


<!-- markdownlint-disable MD036 -->
*🤖 Crafted with precision by ✨Copilot following brilliant human instruction,
Expand Down
88 changes: 59 additions & 29 deletions docs/agents/code-review/language-skills.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ tags:
- skills
- coding-standards
author: Microsoft
ms.date: 2026-06-19
ms.date: 2026-07-06
ms.topic: how-to
estimated_reading_time: 8
---
Expand All @@ -30,16 +30,19 @@ The orchestrator dispatches the Standards perspective with a `diff-state.json` c
```mermaid
flowchart LR
A["Orchestrator:<br/>write diff-state.json"] --> B["Standards perspective:<br/>read extensions"]
B --> C["Match skills via catalog<br/>and semantic filtering"]
C --> D["Load matched skills"]
B --> C["Classify candidates<br/>by origin"]
C --> G["De-duplicate by name<br/>with origin precedence"]
G --> H["Match name + description<br/>to diff languages"]
H --> D["Load matched skills"]
D --> E["Apply checklists"]
E --> F["Write JSON findings"]
```

1. The orchestrator extracts file extensions from the diff during the context bootstrap step and writes them to the `extensions` array in `diff-state.json`.
2. The Standards perspective reads `diff-state.json`, extracts the extensions, and evaluates available skills by matching their name and description against the detected languages or file types.
3. It selects up to 8 relevant skills and applies each skill's checklist to the diff.
4. It writes structured JSON findings for the orchestrator to merge.
2. The Standards perspective reads `diff-state.json`, extracts the extensions, and gathers candidate skills, keeping each candidate's origin (Workspace, User, or Bundled) from its source label.
3. It de-duplicates same-named skills by origin precedence, then evaluates each remaining skill by matching its name and description against the detected languages or file types.
4. It stacks the matched skills needed to cover every changed language or file type and applies each skill's checklist to the diff.
5. It writes structured JSON findings for the orchestrator to merge.

Skill discovery is owned entirely by the Standards perspective. The orchestrator supplies the extensions; the Standards perspective decides which skills to load.

Expand All @@ -51,32 +54,59 @@ The Standards perspective selects skills as follows:

2. It normalizes each extension to language tokens (for example, `.py` to `python`, `.cs` to `csharp`, `.sh` to `bash`).

3. It evaluates built-in skills using a catalog and selects the first skill whose name and description match the detected languages or file types.
3. It gathers candidate `coding-standards` skills, classifying each by origin (Workspace, User, or Bundled) from its source label or path.

4. If no cataloged skill matches, it evaluates additional available skills whose name or description matches the languages, frameworks, or file types in the diff.
4. It de-duplicates candidates that share the same frontmatter `name`, preferring Workspace over User over Bundled origin.

5. It selects up to 8 relevant skills total, prioritizing those most closely aligned with the changed files.
5. It semantically matches each remaining candidate's `name` and `description` against the detected languages, frameworks, or file types.

6. It loads the full `SKILL.md` body for each selected skill and applies its checklist to the diff.
6. It stacks the matched skills needed to cover every changed language, framework, or file type, prioritizing those most closely aligned with the changed files.

7. Every finding traces back to the skill that surfaced it, cited by the skill's exact `name` from frontmatter.
7. It loads the full `SKILL.md` body for each selected skill and applies its checklist to the diff.

8. Every finding traces back to the skill that surfaced it, cited by the skill's exact `name` from frontmatter.

> [!NOTE]
>
> Skills are selected through semantic matching of their name and description against detected languages, frameworks, or file types. Built-in skills are evaluated first via a catalog, and additional skills are considered only if no catalog match is found. No path-based resolution or directory scanning is required.
> Candidates are gathered and classified by origin, then selected through semantic matching of their name and description against detected languages, frameworks, or file types. Semantic matching is the selection step, applied after origin-based de-duplication.

### Skill Origins

The Standards perspective keeps each candidate skill's origin with it through selection:

| Origin | What it represents |
|-----------|---------------------------------------------------------------------------------------|
| Workspace | Skills authored in the repository or workspace under review |
| User | Skills from the user's profile, when the platform exposes them as candidates |
| Bundled | Skills packaged with an installed extension, plugin, or the hve-core baseline |
| Unknown | A candidate with no identifiable source label, used only when origin cannot be ranked |

Origin is inferred from each candidate's source label, never from its content. Author repository skills so they present as Workspace origin; that origin takes precedence over User and Bundled copies of the same skill.

### Skill Merge Behavior

The Standards perspective merges discovered candidates before selection:

| Case | Behavior |
|---------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Distinct skill names | Skills stack additively when they match the diff. Findings keep the exact originating skill `name`. |
| Same skill name | The higher-origin skill shadows the lower one; precedence is Workspace, then User, then Bundled. When origin cannot be ranked, one copy loads and the ambiguous duplicate is noted. |
| Contradictory checks across distinct skills | The perspective surfaces findings from each skill and cites both names. It does not silently choose one standard or combine skill bodies. |

Same-named skill bodies are never concatenated. A shadowed skill does not load.

## Built-in Skills

The `coding-standards` collection ships with one language skill. Additional language skills follow the same pattern and can be contributed to the repository or authored independently.

### python-foundational

| Field | Value |
|--------------|------------------------------------------------|
| Skill path | `skills/coding-standards/python-foundational/` |
| Activates on | `.py` files in the diff |
| Sections | 9 checklist sections, 30+ individual checks |
| Maturity | Experimental |
| Field | Value |
|--------------|---------------------------------------------------------------------------------------------------------------|
| Origin | Bundled hve-core baseline; a repository copy named `python-foundational` takes precedence as Workspace origin |
| Activates on | `.py` files in the diff |
| Sections | 9 checklist sections, 30+ individual checks |
| Maturity | Experimental |

The python-foundational skill covers:

Expand Down Expand Up @@ -115,7 +145,7 @@ Instructions and skills serve different activation contexts. Instructions guide

## Authoring a Custom Skill

You extend the Standards perspective by creating a SKILL.md file under .github/skills/coding-standards/ in your repository. The perspective activates it by matching the skill's name or description against the languages, frameworks, or file types present in the diff.
You extend the Standards perspective by creating a `SKILL.md` file under `.github/skills/coding-standards/` in your repository. The perspective activates it as a Workspace-origin candidate and matches the skill's name or description against the languages, frameworks, or file types present in the diff.

### Skill Stacking

Expand Down Expand Up @@ -200,7 +230,7 @@ Organize checks into numbered sections with bullet points. Each bullet should be
2. Make a change to a file that matches the skill's target language.
3. Invoke the **code-review** agent and select the `standards` perspective (or `full`).
4. Verify that findings cite your skill's `name` in their Skill field.
5. If the skill does not activate, verify that the `description` clearly mentions the language, framework, or file extension present in the diff. Placement under `.github/skills/coding-standards/` is recommended for organization but does not control activation.
5. If the skill does not activate, verify that it is authored under `.github/skills/coding-standards/` (Workspace origin) and that the `description` clearly mentions the language, framework, or file extension present in the diff.

## Enterprise Scenarios

Expand All @@ -218,15 +248,15 @@ A frontend team authors `.github/skills/coding-standards/northwind/react-standar

## Reference

| Resource | Path |
|-----------------------------|----------------------------------------------------------|
| python-foundational skill | `skills/coding-standards/python-foundational/SKILL.md` |
| Standards output format | `docs/templates/standards-review-output-format.md` |
| Full review output format | `docs/templates/full-review-output-format.md` |
| Engineering fundamentals | `docs/templates/engineering-fundamentals.md` |
| Skill authoring guide | [Authoring Custom Skills](../../customization/skills.md) |
| Contributing skills | [Contributing: Skills](../../contributing/skills.md) |
| coding-standards collection | `collections/coding-standards.collection.yml` |
| Resource | Path |
|-----------------------------|----------------------------------------------------------------|
| python-foundational skill | `.github/skills/coding-standards/python-foundational/SKILL.md` |
| Standards output format | `docs/templates/standards-review-output-format.md` |
| Full review output format | `docs/templates/full-review-output-format.md` |
| Engineering fundamentals | `docs/templates/engineering-fundamentals.md` |
| Skill authoring guide | [Authoring Custom Skills](../../customization/skills.md) |
| Contributing skills | [Contributing: Skills](../../contributing/skills.md) |
| coding-standards collection | `collections/coding-standards.collection.yml` |

<!-- markdownlint-disable MD036 -->
*🤖 Crafted with precision by ✨Copilot following brilliant human instruction,
Expand Down
Loading
Loading