feat: support Copilot CLI frontmatter fields (user-invocable, disable-model-invocation)

[charris-msft]

Add support for new Copilot CLI skill frontmatter fields:

• user-invocable (boolean): whether users can invoke via /skill-name
• disable-model-invocation (boolean): prevent model from invoking skill
• allowed-tools: validate format when present

New checks in score.ts:

• spec-user-invocable: validates boolean value when present
• spec-disable-model-invocation: validates boolean value when present
• spec-allowed-tools: validates non-empty when present
• reference-only-pattern: detects user-invocable=false + disable-model-invocation=true (creates a reference file loaded from disk but never invoked)

Updated ALLOWED_FIELDS to prevent false positive warnings on valid fields. Updated scoring.md and SKILL.md documentation with new field patterns.

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

[spboyer]

@charris-msft These are not in the official skills spec. How would a user know when or what these options or guidance to use or not. Can you supply reference link for these fields spec?

[charris-msft]

Good call — these fields are not in the agentskills.io spec; they're Copilot CLI extensions documented here:

📎 Custom agents configuration — YAML frontmatter properties

I've pushed a commit (9af511d) that adds this reference link in two places:

• references/scoring.md — the 'Copilot CLI Extension Fields' section now links to the GitHub docs and clarifies these are not part of the agentskills.io spec
• scripts/src/tokens/commands/score.ts — added the docs URL alongside the existing spec reference in the header comment

All 109 tests pass and token limits are within budget. ✅

[charris-msft]

@charris-msft These are not in the official skills spec. How would a user know when or what these options or guidance to use or not. Can you supply reference link for these fields spec?

This looks like the right location:
https://docs.github.com/copilot/reference/custom-agents-configuration#yaml-frontmatter-properties

It only has one of the properties right now, but the other should show up here once the GH team adds it.

[spboyer]

Two items from review:

1. Bug: ALLOWED_FIELDS may not include the new fields

The PR description says "Updated ALLOWED_FIELDS to prevent false positive warnings" -- but please verify user-invocable and disable-model-invocation are actually in the ALLOWED_FIELDS Set. If they're missing, any skill using these valid Copilot CLI fields will trigger a false spec-allowed-fields warning ("Unknown frontmatter fields"), even though the PR adds dedicated check functions for them.

2. Scoring posture: these are Copilot-specific, not global spec

user-invocable, disable-model-invocation, and allowed-tools are Copilot CLI extensions -- not part of the agentskills.io specification. Their absence should not negatively affect scoring. The checks should be purely informational:

• Present and valid -> note it (optimal or ok)
• Not present -> silent pass (not a warning)
• Present but invalid value -> warn (e.g. non-boolean for user-invocable)

The current implementation looks like it returns ok when absent, which is correct -- but the spec- prefix on the check names implies these are spec requirements. Consider either:

• Renaming to copilot-user-invocable / copilot-disable-model-invocation / copilot-allowed-tools to make it clear these are platform extensions
• Or adding a note in the output/docs that these checks enhance Copilot experience but are not required for spec compliance

Nice work overall -- the reference-only pattern detection is a useful addition.

[charris-msft]

Correction: The link I added earlier was wrong — it pointed to the custom agents configuration docs (.agent.md), not skills.

After checking the Copilot agent runtime source, these fields are valid for SKILL.md — they're defined in the skillFrontmatterSchema:

Field	SKILL.md	Commands (.md)	Custom Agents (.yaml)
user-invocable	✅ Skills only	❌	❌
disable-model-invocation	✅	✅	❌
allowed-tools	✅	✅	❌

scoring.md: These fields are part of the Copilot skill frontmatter schema (not yet documented publicly; not part of the agentskills.io spec)

score.ts: Copilot CLI fields: not yet documented publicly (see skillFrontmatterSchema in copilot-agent-runtime)

[charris-msft]

Addressed both review items:

1. ALLOWED_FIELDS

Confirmed -- user-invocable and disable-model-invocation were already in the ALLOWED_FIELDS Set. No false positives.

2. Renamed spec- to copilot- prefix

Renamed all Copilot-specific checks to make the distinction self-documenting:

Before	After
spec-user-invocable	copilot-user-invocable
spec-disable-model-invocation	copilot-disable-model-invocation
spec-allowed-tools	copilot-allowed-tools
reference-only-pattern	copilot-reference-only-pattern

Updated in score.ts, score.test.ts, and scoring.md. All 109 tests pass. (cb2c53f)

[spboyer]

@charris-msft some merge conflicts to check

[charris-msft]

@spboyer - conflicts resolved. Thanks for the heads up.