Expand references/ in large skill files for progressive disclosure (#766 Phase 2) by Copilot · Pull Request #773 · ptr727/ProjectTemplate

Copilot · 2026-08-16T21:29:34Z

Reduces conditional-load token cost of the three largest un-converted skills by extracting detail content into references/ subdirectories, keeping common-path rules in SKILL.md.

Changes

`python-codestyle` — 17.3 KB → 8.7 KB (−50%)

references/profiles.md — full build/lint-only profile spec, per-repo adaptation axes (type checker, dep declaration, versioning, VS Code config)
references/code-style.md — comments, docstrings, type hints, naming, imports, patterns to avoid
references/testing.md — pytest conventions
SKILL.md retains: profile decision table (condensed), toolchain table, dev loop, layout, key lint rules, linter checklist

`dotnet-codestyle` — 16.0 KB → 11.5 KB (−28%)

references/conventions.md — C# language features, naming, code structure, XML doc examples
references/testing.md — xUnit v3 + AwesomeAssertions template
references/project-config.md — target framework, AOT, SourceLink, InternalsVisibleTo
SKILL.md retains: zero-warnings policy, build tasks, central config rules, suppression hierarchy, logging/library split, code patterns

`git-commit-conventions` — 12.8 KB → 11.9 KB (−7%)

references/history-rewrite.md — two-gate re-identification rule for git filter-repo rewrites
SKILL.md retains: all core rules — staging, signing probe (both shells), identity check, no force-push, destructive-command ban

`.claude-plugin` dist

Regenerated via build_dist.py; reference files included in the generated tree.

Metrics

Skill	Before	After	Reduction
`python-codestyle`	17,312 B	8,696 B	−50%
`dotnet-codestyle`	15,959 B	11,523 B	−28%
`git-commit-conventions`	12,784 B	11,869 B	−7%
All skills total	156,243 B	142,276 B	−9%

No rules removed. All behavioral constraints, safety gates, and verification requirements are preserved — content is moved, not deleted.

Out of scope

AGENTS.md reduction (Phase 4) — deferred pending a hub-vs-local scope decision
Skill description compression (Phase 5) — deferred until body compression is complete
comment-and-doc-style — already has three references; no additional split warranted

Copilot

Pull request overview

This PR reduces conditional-load token cost for large fleet Skills by moving detailed guidance out of SKILL.md into topic-focused references/*.md files (progressive disclosure), then regenerates the .claude-plugin distribution to include the new reference trees.

Changes:

Split python-codestyle into a condensed SKILL.md plus new references/ docs for profiles, code style, and testing.
Split dotnet-codestyle and git-commit-conventions similarly by extracting longer sections into references/.
Regenerate the .claude-plugin marketplace tree and update the source digest.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
.claude-plugin/fleet-skills/skills/python-codestyle/SKILL.md	Condenses python codestyle guidance and points to new reference docs.
.claude-plugin/fleet-skills/skills/python-codestyle/references/testing.md	Adds pytest conventions reference.
.claude-plugin/fleet-skills/skills/python-codestyle/references/profiles.md	Adds full profile specification and adaptation axes reference.
.claude-plugin/fleet-skills/skills/python-codestyle/references/code-style.md	Adds full code-style reference (comments/docstrings/types/imports/patterns).
.claude-plugin/fleet-skills/skills/git-commit-conventions/SKILL.md	Condenses history-rewrite guidance and links to extracted reference.
.claude-plugin/fleet-skills/skills/git-commit-conventions/references/history-rewrite.md	Adds the full two-gate re-identification rule for rewrites.
.claude-plugin/fleet-skills/skills/dotnet-codestyle/SKILL.md	Condenses conventions/testing/project-config guidance and links to extracted references.
.claude-plugin/fleet-skills/skills/dotnet-codestyle/references/testing.md	Adds detailed xUnit v3 + AwesomeAssertions testing reference.
.claude-plugin/fleet-skills/skills/dotnet-codestyle/references/project-config.md	Adds full .NET project configuration reference (TFM/AOT/SourceLink/IVT).
.claude-plugin/fleet-skills/skills/dotnet-codestyle/references/conventions.md	Adds full C# conventions reference (features/naming/structure/XML docs).
.claude-plugin/fleet-skills/.source-digest	Updates the generated marketplace source digest.
.agents/skills/python-codestyle/SKILL.md	Condenses python codestyle guidance and points to new reference docs.
.agents/skills/python-codestyle/references/testing.md	Adds pytest conventions reference.
.agents/skills/python-codestyle/references/profiles.md	Adds full profile specification and adaptation axes reference.
.agents/skills/python-codestyle/references/code-style.md	Adds full code-style reference (comments/docstrings/types/imports/patterns).
.agents/skills/git-commit-conventions/SKILL.md	Condenses history-rewrite guidance and links to extracted reference.
.agents/skills/git-commit-conventions/references/history-rewrite.md	Adds the full two-gate re-identification rule for rewrites.
.agents/skills/dotnet-codestyle/SKILL.md	Condenses conventions/testing/project-config guidance and links to extracted references.
.agents/skills/dotnet-codestyle/references/testing.md	Adds detailed xUnit v3 + AwesomeAssertions testing reference.
.agents/skills/dotnet-codestyle/references/project-config.md	Adds full .NET project configuration reference (TFM/AOT/SourceLink/IVT).
.agents/skills/dotnet-codestyle/references/conventions.md	Adds full C# conventions reference (features/naming/structure/XML docs).

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Copilot

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated no new comments.

Suppressed comments (4)

.agents/skills/python-codestyle/SKILL.md:140

This paragraph uses a mid-sentence semicolon, which the repo's prose rules forbid in agent-authored text (see .agents/skills/comment-and-doc-style/SKILL.md:171-173). Recast as two sentences to avoid failing the prose semicolon gate.

Published packages use `_version.py` with `__version__ = "0.0.0"` as a placeholder; wire
`hatch-vcs` or equivalent to increment, publish with `skip-existing: true`. Source-only repos use
a static `version` in `[project]` with no `_version.py`. See `references/profiles.md` for details.

.agents/skills/dotnet-codestyle/SKILL.md:206

The Project configuration summary has a malformed XML snippet (<IsAotCompatible>true) and also omits VerifyReferenceAotCompatibility, which is part of the referenced configuration list. This reads like a copy/paste truncation and could mislead consumers of the skill.

.NET 10.0 target, AOT-compatible (`IsAotCompatible=true`, `VerifyReferenceAotCompatibility=true`),
SourceLink, embedded untracked sources, `InternalsVisibleTo` for test/benchmark access. See
`references/project-config.md` for the full property list.

.agents/skills/python-codestyle/SKILL.md:125

These bullets use mid-sentence semicolons, which the repo's prose rules forbid in agent-authored text (see .agents/skills/comment-and-doc-style/SKILL.md:171-173). Recast them as a comma or two sentences to satisfy the prose gate.

This issue also appears on line 138 of the same file.

- **Don't add backward-compat shims.** Just delete unused code; git history is the audit trail.
- **Don't add error handling for impossible cases.** Trust internal code; validate only at boundaries.

.agents/skills/git-commit-conventions/SKILL.md:161

This line uses a mid-sentence semicolon, which the repo's prose rules forbid in agent-authored text (see .agents/skills/comment-and-doc-style/SKILL.md:171-173). Recast as two sentences so the prose semicolon gate does not flag the skill.

rewrite to only the commits that must change; set `committer` (and `author`) to the rewriter's

Copilot

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated no new comments.

Suppressed comments (3)

.agents/skills/python-codestyle/SKILL.md:140

Mid-sentence semicolon violates the repo's prose style rule (see .agents/skills/comment-and-doc-style/SKILL.md:171-173). Recast as a comma or split into two sentences (and re-run the dist generator so the .claude-plugin copy stays in sync).

Published packages use `_version.py` with `__version__ = "0.0.0"` as a placeholder; wire
`hatch-vcs` or equivalent to increment, publish with `skip-existing: true`. Source-only repos use
a static `version` in `[project]` with no `_version.py`. See `references/profiles.md` for details.

.agents/skills/python-codestyle/SKILL.md:125

Mid-sentence semicolons violate the repo's prose style rule (see .agents/skills/comment-and-doc-style/SKILL.md:171-173). Please recast these as a comma or two sentences (and re-run the dist generator so the .claude-plugin copy stays in sync).

This issue also appears on line 138 of the same file.

- **Don't add backward-compat shims.** Just delete unused code; git history is the audit trail.
- **Don't add error handling for impossible cases.** Trust internal code; validate only at boundaries.

.agents/skills/git-commit-conventions/SKILL.md:162

Mid-sentence semicolon violates the repo's prose style rule (see .agents/skills/comment-and-doc-style/SKILL.md:171-173). Recast this as a comma or two sentences (and re-run the dist generator so the .claude-plugin copy stays in sync).

signature will not match the committer and the require-signed-commits rule rejects it. Scope the
rewrite to only the commits that must change; set `committer` (and `author`) to the rewriter's
identity on any non-own commit that must be modified. Verify with `git log --show-signature` after

Copilot

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated no new comments.

Copilot

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated no new comments.

Copilot

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated no new comments.

…conventions per #766 python-codestyle: -50% (17.3 KB -> 8.7 KB). Extract profiles, code-style, testing to references/. dotnet-codestyle: -28% (16.0 KB -> 11.5 KB). Extract conventions, testing, project-config to references/. git-commit-conventions: -7% (12.8 KB -> 11.9 KB). Extract history-rewrite to references/. Regenerate .claude-plugin dist tree. Co-authored-by: ptr727 <2061579+ptr727@users.noreply.github.com>

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Co-authored-by: ptr727 <2061579+ptr727@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated no new comments.

… Fix (#786) Promote `develop` to `main`, carrying: - #783 Drop IGNORE_GITHUB_REF From the Hosted Get-Version Task (the hosted task follows WORKFLOW.md D3.1 like the inline get-version job already does) - #778 Name the Executable Asset for Its Project and Record the PhotoCleaner Pilot (the executable default names its archive for the project file, the publish-release snippet and doc stub carry explicit permissions, PhotoCleaner ticked as the stage 2 and 4 pilot) - #775 Record 2.0.352 in the Reusable-Workflow Rollout and Add Its Catalog Snippets - #773 Expand references/ in large skill files for progressive disclosure - #776 Make the linux host-setup scripts refuse more than one action - #782 Add PowerShell as an Optional Tool From the Microsoft Feed The release that follows is the pin PhotoCleaner's Dependabot bumps to, and PhotoCleaner's next release through it is the proof that the executable asset is named `PhotoCleaner.7z` again. Closes #769.

## Summary Adds `docs/token-efficiency-plan.md`, the hub-only rollout plan for #766. The delivery is the doc, the work is the analysis, architecture, and design. - **Objectives**: lower recurring context, improve accuracy, progressive disclosure as the default shape, empirical decisions for locked content, preserve invariants, agent-executable delivery. - **Gap analysis**: 10 measured gaps at `5b8e008`, the largest being the Copilot Review Runbook at 47.6 KB of the 53.2 KB always-loaded Copilot file, and 12 of 18 skills without `references/`. - **Rollout plan**: one checkbox = one worktree = one PR, benchmark veto for behavior-affecting edits, per-fidelity-class propagation, Findings Register for defects. - **Phased delivery**: Phase 0 records #773, Phase 1 builds the measuring sticks (inventory script + benchmark), Phases 2-3 execute the proven reductions, Phase 4 measures downstream per-provider context, Phases 5-7 are gated on that evidence. Closes #766 (the plan is the delivery, the phases self-track progress).

Copilot AI assigned Copilot and ptr727 Aug 16, 2026

Copilot AI lite review requested due to automatic review settings August 16, 2026 21:29

Copilot started reviewing on behalf of ptr727 August 16, 2026 21:30 View session

Copilot AI requested a review from ptr727 August 16, 2026 21:30

Copilot finished work on behalf of ptr727 August 16, 2026 21:30

Copilot created this pull request from a session on behalf of ptr727 August 16, 2026 21:30 View session

Copilot AI reviewed Aug 16, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings August 16, 2026 21:35

Copilot started reviewing on behalf of ptr727 August 16, 2026 21:35 View session

Copilot AI reviewed Aug 16, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings August 16, 2026 21:39

Copilot started reviewing on behalf of ptr727 August 16, 2026 21:39 View session

Copilot AI reviewed Aug 16, 2026

View reviewed changes

Copilot started work on behalf of ptr727 August 16, 2026 21:46 View session

Copilot AI review requested due to automatic review settings August 16, 2026 21:47

Copilot started reviewing on behalf of ptr727 August 16, 2026 21:47 View session

Copilot finished work on behalf of ptr727 August 16, 2026 21:50

Copilot AI reviewed Aug 16, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings August 16, 2026 21:50

Copilot started reviewing on behalf of ptr727 August 16, 2026 21:50 View session

Copilot AI reviewed Aug 16, 2026

View reviewed changes

Copilot started work on behalf of ptr727 August 16, 2026 21:56 View session

Copilot AI review requested due to automatic review settings August 16, 2026 21:57

Copilot started reviewing on behalf of ptr727 August 16, 2026 21:57 View session

Copilot finished work on behalf of ptr727 August 16, 2026 21:57

Copilot AI reviewed Aug 16, 2026

View reviewed changes

ptr727 marked this pull request as ready for review August 16, 2026 22:00

ptr727 mentioned this pull request Aug 16, 2026

Optimize Agent Instructions and Skills for Token Efficiency #766

Closed

13 tasks

ptr727 and others added 5 commits August 16, 2026 15:31

Potential fix for pull request finding

6ec50c7

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding

6d0f814

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding

c334f0a

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding

4768d10

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Fix suppressed semicolon findings in skill summaries

9f743e3

Co-authored-by: ptr727 <2061579+ptr727@users.noreply.github.com>

ptr727 force-pushed the copilot/issue-766-comment-proposal branch from 8b75610 to 9f743e3 Compare August 16, 2026 22:36

Copilot AI review requested due to automatic review settings August 16, 2026 22:36

ptr727 changed the base branch from main to develop August 16, 2026 22:36

Copilot started reviewing on behalf of ptr727 August 16, 2026 22:37 View session

Copilot AI reviewed Aug 16, 2026

View reviewed changes

ptr727 merged commit 5b8e008 into develop Aug 17, 2026
8 checks passed

ptr727 deleted the copilot/issue-766-comment-proposal branch August 17, 2026 02:02

This was referenced Aug 17, 2026

Add the token efficiency plan for issue 766 #785

Merged

Promote develop to main With the Pilot Follow-Ups and the Get-Version Fix #786

Merged

ptr727 mentioned this pull request Aug 17, 2026

Refactor copilot-instructions.md to reuse repo agent instructions and skills #793

Closed

Navigation Menu

Expand references/ in large skill files for progressive disclosure (#766 Phase 2) - #773

Expand references/ in large skill files for progressive disclosure (#766 Phase 2)#773
ptr727 merged 6 commits into
developfrom
copilot/issue-766-comment-proposal

Copilot AI commented Aug 16, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Copilot AI commented Aug 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

python-codestyle — 17.3 KB → 8.7 KB (−50%)

dotnet-codestyle — 16.0 KB → 11.5 KB (−28%)

git-commit-conventions — 12.8 KB → 11.9 KB (−7%)

.claude-plugin dist

Metrics

Out of scope

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Aug 16, 2026 •

edited

Loading

`python-codestyle` — 17.3 KB → 8.7 KB (−50%)

`dotnet-codestyle` — 16.0 KB → 11.5 KB (−28%)

`git-commit-conventions` — 12.8 KB → 11.9 KB (−7%)

`.claude-plugin` dist