Restructure skills: move to .agents/skills/, apply progressive disclosure, merge overlapping skills - #181
Merged
Merged
Conversation
Split the 799-line SKILL.md into a 304-line overview + 3 reference files: - references/genai-config-fields.md: complete field tables for all sections - references/processor-config-fields.md: processor_config.json full reference - references/multimodal-pipeline.md: VLM pipeline architecture and helpers No content removed; all fields, examples, and code snippets preserved. SKILL.md now contains overview, model type registry, minimal valid config, processor overview, troubleshooting, and cross-reference directives. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Justin Chu <justinchu@microsoft.com>
Reduce SKILL.md from 699 to 273 lines by extracting detailed reference material into references/ subdirectory: - references/test-examples.md: Full code examples, YAML format, golden file format, step-by-step coverage instructions - references/tolerance-guidelines.md: Detailed tolerance tables, failure checklist, debugging scripts, dtype-specific guidance - references/test-utilities.md: API reference for OnnxModelSession, OnnxGenerator, comparison functions, feed creation patterns SKILL.md retains: L1-L5 summary table, test commands, file layout, shared config overview, quick patterns, tolerance quick-reference, and gotchas section with clear directives to reference files. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Justin Chu <justinchu@microsoft.com>
Extract detailed reference material from multimodal-models, reusable-components, and phi4mm-component-parity SKILL.md files into per-skill references/ subdirectories. Each SKILL.md is now under 500 lines (177, 221, 146) with 'Read references/X.md when...' directives for progressive disclosure. multimodal-models: - references/projector-variants.md: Detailed projector code, Qwen-VL specifics - references/vision-encoder-details.md: VisionModel construction, model template - references/weight-mappings.md: Full weight mapping tables, shape fixes reusable-components: - references/onnx-op-patterns.md: Scalar constants, CastLike, fp32 upcast, shapes - references/component-examples.md: All component variants, adapter patterns phi4mm-component-parity: - references/common-failures.md: 9 detailed failure modes with code - references/debugging-cookbook.md: Step-by-step procedures, test patterns All description fields updated with imperative phrasing and user intent focus. No content was lost — all material preserved in reference files. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Justin Chu <justinchu@microsoft.com>
… add references - Trim debugging-vl-pipeline SKILL.md from 533 to 222 lines by extracting 10 failure modes to references/failure-modes.md and 3 intermediate value extraction methods to references/extraction-methods.md - Rescope debugging-vl-pipeline for existing pipeline debugging vs phi4mm-component-parity for building new multi-encoder models - Update descriptions for 8 skills to use imperative phrasing with clear trigger keywords - Verify no .github/skills/ references remain (all use .agents/skills/) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Justin Chu <justinchu@microsoft.com>
Merge 1: debugging-vl-pipeline + phi4mm-component-parity → debugging-multimodal - Combined 3-stage VL pipeline and 4-model multi-encoder methodologies - Merged failure modes (deduplicated overlapping content like ClippableLinear, boundary tokens, empty tensors) into references/failure-modes.md - Preserved extraction-methods.md and debugging-cookbook.md as references - Removed old debugging-vl-pipeline and phi4mm-component-parity directories Merge 2: scan-and-multi-image → multimodal-models/references/scan-pattern.md - Moved scan skill content as a reference file under multimodal-models - Added reference directive in multimodal-models SKILL.md - Removed old scan-and-multi-image directory Updated all cross-references in multimodal-models SKILL.md and projector-variants.md to point to new locations. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Justin Chu <justinchu@microsoft.com>
The skills were moved to .agents/skills/ in prior commits but the old directory was not cleaned up. This commit: - Deletes the 14 original .github/skills/ SKILL.md files - Updates path references in copilot-instructions, README, CONTRIBUTING, CHANGELOG, docs, and tests to point to .agents/skills/ Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Justin Chu <justinchu@microsoft.com>
Performance Comparison
|
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
Contributor
There was a problem hiding this comment.
Pull request overview
Moves the repository’s “skills” documentation to the .agents/skills/ layout (per agentskills.io), applying progressive disclosure by splitting oversized skills into shorter SKILL.md files with detailed references/ material, and updates repo docs/tests to point at the new paths.
Changes:
- Relocates skills from
.github/skills/to.agents/skills/and updates in-repo references. - Splits large skills into reference sub-docs and merges overlapping multimodal debugging skills.
- Removes legacy
.github/skills/*skill files that were superseded by the new structure.
Reviewed changes
Copilot reviewed 43 out of 43 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/model_coverage_test.py | Updates skill link path in test docstring to .agents/skills/. |
| docs/getting-started.md | Updates “adding-a-new-model” skill link to new location. |
| docs/ai-model-support-strategy.md | Updates references to skills directory and adding-a-new-model link. |
| README.md | Updates skills directory mention to .agents/skills/. |
| CONTRIBUTING.md | Updates quality-checklist skill link to .agents/skills/. |
| CHANGELOG.md | Updates skills path mention in release notes. |
| .github/copilot-instructions.md | Updates skills path reference to .agents/skills/. |
| .agents/skills/writing-tests/SKILL.md | New, trimmed writing-tests skill with links to extracted references. |
| .agents/skills/writing-tests/references/tolerance-guidelines.md | New detailed tolerance guidance reference. |
| .agents/skills/writing-tests/references/test-utilities.md | New testing utilities reference. |
| .agents/skills/writing-tests/references/test-examples.md | New detailed examples/reference for test patterns and golden workflows. |
| .agents/skills/writing-rewrite-rules/SKILL.md | Refines description for rewrite-rules skill (progressive disclosure wording). |
| .agents/skills/weight-name-alignment/SKILL.md | Refines description for weight-name-alignment skill. |
| .agents/skills/reusable-components/SKILL.md | New, trimmed reusable-components skill with extracted reference links. |
| .agents/skills/reusable-components/references/onnx-op-patterns.md | New detailed ONNX op-building patterns reference. |
| .agents/skills/reusable-components/references/component-examples.md | New detailed component examples reference. |
| .agents/skills/quality-checklist/SKILL.md | Updates skill description wording and keeps protobuf prohibition reminder. |
| .agents/skills/ort-genai-config/SKILL.md | New, trimmed ORT GenAI config skill with extracted references. |
| .agents/skills/ort-genai-config/references/genai-config-fields.md | New exhaustive genai_config.json field reference. |
| .agents/skills/ort-genai-config/references/processor-config-fields.md | New exhaustive processor_config.json field reference. |
| .agents/skills/ort-genai-config/references/multimodal-pipeline.md | New detailed multimodal pipeline architecture reference. |
| .agents/skills/multimodal-models/SKILL.md | New multimodal models skill with extracted references. |
| .agents/skills/multimodal-models/references/projector-variants.md | New detailed projector/encoder variants reference. |
| .agents/skills/multimodal-models/references/vision-encoder-details.md | New vision encoder wiring/config extraction reference. |
| .agents/skills/multimodal-models/references/weight-mappings.md | New weight mapping reference for multimodal models. |
| .agents/skills/multimodal-models/references/scan-pattern.md | Converts former Scan skill content into a reference doc under multimodal-models. |
| .agents/skills/debugging-multimodal/SKILL.md | New merged multimodal debugging skill (VL + multi-encoder parity). |
| .agents/skills/debugging-multimodal/references/failure-modes.md | New consolidated failure modes reference. |
| .agents/skills/debugging-multimodal/references/extraction-methods.md | New intermediate-value extraction reference. |
| .agents/skills/debugging-multimodal/references/debugging-cookbook.md | New step-by-step debugging cookbook reference. |
| .agents/skills/adding-a-new-model/SKILL.md | New, trimmed adding-a-new-model skill with extracted references. |
| .agents/skills/adding-a-new-model/references/architecture-patterns.md | New detailed architecture patterns reference. |
| .agents/skills/adding-a-new-model/references/weight-preprocessing.md | New detailed preprocess_weights reference. |
| .agents/skills/multi-agent-coordination/SKILL.md | Refines description for multi-agent-coordination skill. |
| .agents/skills/moe-models/SKILL.md | Refines description for moe-models skill. |
| .agents/skills/diffusion-models/SKILL.md | Refines description for diffusion-models skill. |
| .github/skills/reusable-components/SKILL.md | Removes legacy skill file superseded by .agents/skills/reusable-components/. |
| .github/skills/phi4mm-component-parity/SKILL.md | Removes legacy skill file superseded by merged debugging-multimodal skill. |
| .github/skills/debugging-vl-pipeline/SKILL.md | Removes legacy VL debugging skill superseded by merged debugging-multimodal skill. |
- Update assert_logits_close to use np.testing.assert_allclose with strict=True, which enforces shape and dtype equality - Remove manual shape assertion (strict=True handles it) - Remove protobuf-based extraction method from debugging skill (violates repo zero-protobuf convention) - Fix CastLike usage in tolerance guidelines (not Cast with x.dtype) - Fix skill count in CHANGELOG (11 → 12) - Update skill docs to accurately describe assert_logits_close behavior Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Justin Chu <justinchu@microsoft.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Justin Chu <justinchu@microsoft.com>
titaiwangms
approved these changes
Apr 21, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Restructures the skills directory following the agentskills.io specification for better agent consumption.
Changes
Location:
.github/skills/→.agents/skills/Progressive disclosure: 6 oversized skills (>500 lines) trimmed to <500 lines with
references/subdirectories for detailed material:Skills merged (14→12):
debugging-vl-pipeline+phi4mm-component-parity→debugging-multimodal(316 lines + 3 ref files)scan-and-multi-imageabsorbed intomultimodal-models/references/scan-pattern.mdDescriptions: All 12 skill descriptions improved with imperative phrasing and specific trigger conditions per agentskills.io best practices.
Path references: Updated in copilot-instructions, README, CONTRIBUTING, CHANGELOG, docs, and tests.
Final skill inventory (all SKILL.md under 500 lines)