Bundle d365fo-cli guidance as a first-class Copilot skill

[RollPatrol]

True lazy loaded skills to save on token usage and not be interjected into every prompt.

[dynamics365ninja]

Audit — thanks, right direction, but a few blockers

The intent is good and the skill format is fundamentally valid (frontmatter checks out against the spec — see "What's good" at the bottom). But there are 4 blocking issues, one of which ships factually outdated X++ guidance.

Everything below was verified by checking out e7aab9b and actually running the scripts, not just reading the diff.

---

Blocking

1. Committed references/*.md are out of sync with skills/_source/ — 14 of 19 files

Checked out the PR head, ran python scripts/emit-skills.py, and git status reported 14 modified files (+175/−93). skills/copilot and skills/anthropic stayed clean — only the new target drifts.

This isn't whitespace, it's stale guidance. Example from references/label-translation.md:

-- `--lang` is required when the file does not embed a single language stem
+- `--lang` only affects path resolution when using `--install-to <MODEL>`; it
+  has no effect when `--file` is given directly

Root cause: references were generated in c346fd3, then main was merged in 418c5b2 (which corrected _source as part of the KB audit), but the emitter was never re-run. As it stands this PR would distribute guidance upstream already fixed.

Fix: re-run the emitter and commit the result.

2. The CI drift gate doesn't cover the new target — .github/workflows/ci.yml:55

if [ -n "$(git status --porcelain skills/copilot skills/anthropic)" ]; then

skills/d365fo-cli/references is missing. That's exactly why #1 slipped through — please extend the path list (and the step name, which still says "Copilot + Anthropic") in the same PR, otherwise the drift will come back.

3. emit-skills.ps1 no longer runs on Windows PowerShell 5.1

$copilotSkillOut = Join-Path $OutRoot 'd365fo-cli' 'references'

The three-argument Join-Path (-AdditionalChildPath) only exists in PowerShell 6+. Verified under 5.1:

A positional parameter cannot be found that accepts argument 'references'.

Developer PowerShell for VS 2022 and a typical D365FO dev VM are both 5.1.

Fix: Join-Path (Join-Path $OutRoot 'd365fo-cli') 'references'

4. The installer now hard-depends on pwsh

& pwsh -NoProfile -File $emitScript

This replaces the previous python invocation, which degraded gracefully (Write-Warning + instructions to run it manually). pwsh is not present on a stock Windows box — verified missing on a clean Windows Server 2022 install, where the call raises CommandNotFoundException. Combined with $ErrorActionPreference = 'Stop', the installer aborts instead of warning.

Fix: probe pwsh → powershell → python, or keep the python fallback.

---

Note — 5. Visual Studio 2022 does not support agent skills (retracted)

Corrected after maintainer feedback — this is not a blocker, and the "VS 2022 / 2026" claims in SKILL.md, README and SETUP.md can stay as they are.

I originally raised this from MS Learn's prerequisites ("Visual Studio 2026 version 18.5 or later"), reading it to mean that a VS 2022 user would end up with a skill their IDE cannot read and no fallback, since the installer stopped deploying copilot-instructions.md / instructions/. The maintainer has verified in practice that VS 2022 does load skills from .github/skills/ — it just isn't an officially documented path. So the regression I described doesn't exist.

One thing still worth a thought, purely as your call: undocumented behaviour carries no compatibility guarantee across Copilot extension updates, and skills/copilot/*.instructions.md is already emitted anyway — so a -Legacy switch on the installer would be cheap insurance rather than new work.

---

Medium

6. Inconsistent file writing between emitters. Emit-CopilotSkill uses Set-Content -Encoding utf8, while Emit-Copilot / Emit-Anthropic deliberately use [System.IO.File]::WriteAllText(..., $Utf8NoBom). Under Windows PowerShell 5.1, -Encoding utf8 means with BOM, so the output diverges from emit-skills.py and the CI gate (once #2 and #3 are fixed) will fail depending on who generated the files. Please use the same $Utf8NoBom path.

7. Dangling cross-references after the rename. .github/copilot-instructions.md is deleted, but these still point at it:

• src/D365FO.Cli/Commands/Agent/AgentPromptCommand.cs:37 — the CLI's own output (d365fo agent-prompt) sends users to a file that no longer exists
• docs/CAPABILITIES.md:378 and :452
• docs/TOKEN_ECONOMICS.md:25 — still describes .instructions.md frontmatter, and token economics is the whole premise of this PR
• docs/img/solution-architecture-diagram.svg:137
• the emit-skills.ps1 header comment still says "emits two parallel artifacts"

8. README says SKILL.md is "always loaded". In the skills model only name + description stay in context; the body is loaded on activation. As written it contradicts the PR's own rationale ("not be interjected into every prompt").

---

Low

9. $referenceFiles.Count under Set-StrictMode -Version Latest throws The property 'Count' cannot be found on this object when references/ doesn't exist — i.e. exactly the "first run / clean clone" path the new .DESCRIPTION advertises. (The pattern is inherited from the old script, but it now sits on a newly promoted path.) @(Get-ChildItem ...).Count fixes it.

10. Install-D365FoCopilotSkills.ps1 has no BOM but contains ⚠ and —. Windows PowerShell 5.1 reads BOM-less files as ANSI, so the migration notice prints as mojibake.

11. The installer only copies references, never prunes — renamed or removed topics leave orphans behind in the target repo.

12. Losing the applyTo globs (19 path-scoped instruction files → one skill whose activation is a model decision) isn't a defect, but it's a deliberate trade-off worth stating in the PR description.

---

What's good

• Frontmatter is spec-correct: name: d365fo-cli matches the directory, compatibility is a valid optional property, description is 347/1024 chars, SKILL.md is 165/500 lines.
• Renaming resources/ → references/ in the last commit was the right call — that's the documented convention.
• Both emitters (.ps1 and .py) were extended consistently, and SKILL.md is correctly preserved on regeneration (only references/ is removed).
• The docs rewrite in the files you did touch is thorough and careful.

Sources: Use Agent Skills with GitHub Copilot — Visual Studio · Adding agent skills for GitHub Copilot — GitHub Docs

[dynamics365ninja]

Follow-up: blocking items 1–4 fixed in 060dc8c

I've pushed the four blocking fixes straight to this branch rather than leaving you to redo them — hope that's helpful rather than intrusive. Revert or amend freely if you'd rather do it your own way.

060dc8c — 17 files, +231/−111.

#	Item	What changed
1	Stale references/	Regenerated from skills/_source/ — 14 files. Restores the KB-audit corrections the old snapshot was overwriting (--lang semantics on labels create, EDT label inheritance).
2	CI drift gate	.github/workflows/ci.yml now diffs skills/d365fo-cli/references too, and the step name matches.
3	emit-skills.ps1 on PS 5.1	Nested Join-Path; plus two extra defects found while testing (below).
4	Installer's pwsh dependency	Probes pwsh → powershell → python/python3, warns only when none is found.

Two extra things surfaced while verifying #3

Worth flagging since they weren't in the original audit:

• $PSScriptRoot is empty when param() defaults are evaluated under Windows PowerShell 5.1 (they're evaluated in the caller's scope). Once the Join-Path bug was fixed the script still died on its own default parameters — meaning emit-skills.ps1 with no arguments had never worked on 5.1. Defaults are now resolved in the script body. Without this the installer fix in feat: Implement D365FO.Bridge for JSON-RPC 2.0 communication #4 would have been useless, since it invokes exactly that path.
• Emit-CopilotSkill used Set-Content -Encoding utf8, which writes a BOM under 5.1 — that was item Refactor documentation structure: #6, but it had to come along: with the drift gate from feat: implement custom model matching with glob patterns and update extraction logic #2 now active, BOM'd output would fail CI depending on which emitter the contributor ran. It now uses the same $Utf8NoBom WriteAllText path as the other two emitters.

Also swapped the » and ⚠ in console output for ASCII. These files carry no BOM, so 5.1 reads them as ANSI and mangles non-ASCII — and adding a BOM isn't an option, it would break the #!/usr/bin/env pwsh shebang. (Item #10, partially; the box-drawing characters in comments are untouched since they're never printed.)

Item #9 (@(Get-ChildItem ...) for .Count under Set-StrictMode) came along with the installer rewrite.

Verified on Windows PowerShell 5.1

• Both emitters produce output git diff sees as identical — the drift gate from feat: implement custom model matching with glob patterns and update extraction logic #2 passes either way.
• Install-D365FoCopilotSkills.ps1 deploys SKILL.md + 19 references.
• The clean-clone path works: with references/ absent the installer regenerates and then deploys, and SKILL.md survives regeneration.

Still open, for you

#7 dangling references to the deleted .github/copilot-instructions.md — AgentPromptCommand.cs:37 is the one that matters, since it's the CLI's own output. Then docs/CAPABILITIES.md:378/:452, docs/TOKEN_ECONOMICS.md:25, docs/img/solution-architecture-diagram.svg:137.

#8 the README's "always loaded" note on SKILL.md, #11 the installer never pruning stale references, #12 the applyTo trade-off in the PR description.

And #5 is retracted — see the edit on my earlier comment. VS 2022 does load .github/skills/, it's just undocumented.