Problems

• some skills do not auto load (need front matter)
• no references in squad.agent.md to the new location
• .copilot is not a default oob location
• some skills got left over in .squad/skills/* during the original move to .copilot/skills, consolidate?
• unable to prompt /nap now

no pop up

PRD Request: Prompt

create me a prd.md file that i can copy into the squad repo that explains what is wrong with the front matter in
each skill listed in .copilot/skills/*/skill.md? i feel like those are bugs

PRD Response: Normalize .copilot/skills/*/SKILL.md Front Matter

Summary

All 29 skills under .copilot/skills/*/SKILL.md currently fail the repo's own skill front matter contract. The failures are not random: most skills carry unsupported top-level metadata, several use an unsupported tools field, and four have no YAML front matter at all. On top of that, the current validator crashes on Windows for 16 skills because it reads UTF-8 files with the platform default encoding instead of explicit UTF-8.

This should be treated as a real product bug, not cleanup. Right now the front matter surface is inconsistent, validation is unreliable, and future contributors cannot tell which metadata shape is actually supported.

External Skill Influence

• https://github.com/anthropics/skills/tree/main/skills/skill-creator

Why this matters

• Skill discovery and trigger behavior depend on SKILL.md front matter, especially name and description.
• The current validator in .github/skills/skill-creator/scripts/quick_validate.py is the clearest in-repo contract for valid skill metadata.
• Invalid front matter means contributors can keep shipping skills that look valid in Markdown but fail the repo's own rules.
• The Windows UTF-8 crash hides the real failures and makes the validation story nondeterministic.

Current contract in the repo

Based on .github/skills/skill-creator/scripts/quick_validate.py, the allowed top-level front matter keys are:

• name
• description
• license
• allowed-tools
• metadata
• compatibility

Based on .github/agents/AGENTS.md, description: must remain a single line and should be double-quoted when it contains YAML-special punctuation.

Problem statement

The current .copilot skill set violates the contract in four distinct ways:

1. 18 skills use unsupported top-level keys: domain, confidence, source
2. 6 skills use unsupported top-level keys: domain, confidence, source, tools
3. 1 skill uses unsupported top-level keys: author, confidence, source
4. 4 skills have no YAML front matter

Separately, the current validator crashes on 16 skills with UnicodeDecodeError on Windows because it calls read_text() without an explicit UTF-8 encoding.

Goals

1. Make all .copilot/skills/*/SKILL.md files validate against a single, explicit front matter contract.
2. Preserve current skill intent and trigger semantics while fixing metadata shape.
3. Keep useful repo-specific metadata without leaving it in unsupported top-level keys.
4. Make validation deterministic across platforms, especially Windows.

Non-goals

• Rewriting full skill bodies unless needed to relocate metadata
• Retuning descriptions for trigger quality unless a specific description is invalid
• Renaming skill folders that already match their name
• Changing .github/skills/*/SKILL.md as part of this fix unless intentionally done in a separate follow-up

Proposed approach

1. Normalize top-level front matter

Every .copilot skill should use only supported top-level fields.

Recommended shape:

---
name: "skill-name"
description: "Single-line description used for routing and trigger selection."
metadata:
  domain: "team-workflow"
  confidence: "high"
  source: "earned from repeated production usage"
  author: "optional"
---

2. Decide how to handle tools

The current top-level tools: field is invalid under the validator.

One of these decisions should be made and applied consistently:

1. If tool restrictions are meant to be machine-readable, migrate tools to a supported field such as allowed-tools using the schema the repo wants to enforce.
2. If the current tools block is explanatory rather than enforceable, move it out of front matter into a body section such as ## Tooling or ## Tool Notes.

3. Add missing front matter to body-only skills

The following files need a valid YAML block added at the top:

• cli-wiring
• model-selection
• nap
• personal-squad

At minimum they need:

• name
• description

Optional repo-specific metadata should go under metadata, not top-level custom keys.

4. Fix the validator

quick_validate.py should read files with explicit UTF-8, not the platform default.

Expected change:

content = skill_md.read_text(encoding="utf-8")

That change is needed even if all front matter is normalized, because the current validator can crash before it reports the real metadata problem.

Expected outcome

After the fix:

• 29/29 .copilot skills pass validation
• Front matter shape is consistent and documented
• Repo-specific metadata is preserved in a supported location
• Windows validation no longer fails with encoding tracebacks

Acceptance criteria

1. Every file under .copilot/skills/*/SKILL.md begins with valid YAML front matter.
2. No skill uses unsupported top-level keys.
3. Any retained repo-specific metadata lives under metadata.
4. No skill uses top-level tools unless the validator and schema explicitly support it.
5. quick_validate.py reads UTF-8 explicitly and returns normal validation messages instead of UnicodeDecodeError.
6. Running validation across all 29 .copilot skills reports zero failures.

Skill-by-skill defect matrix

Companion validator bug

This is separate from the front matter schema bug, but it should be fixed in the same effort because it blocks trustworthy diagnosis.

• Current behavior: quick_validate.py reads SKILL.md with read_text() and uses the platform default encoding.
• Windows impact: 16 skills currently crash validation with UnicodeDecodeError before the validator can report the actual front matter issue.
• Required fix: read with explicit UTF-8 and keep the validator focused on front matter errors, not file decoding failures.

Implementation notes

• This work should be done as a normalization pass across all .copilot skills, not one file at a time with ad hoc rules.
• If the team wants to preserve domain, confidence, source, author, or tool annotations, metadata is the safest currently supported home.
• If allowed-tools is intended to replace tools, the repo should document the expected structure and validate it explicitly.

Definition of done

This PRD is complete when the repo has:

1. A single documented front matter shape for .copilot skills
2. A UTF-8-safe validator
3. Zero invalid .copilot/skills/*/SKILL.md files
4. No ambiguity about which metadata is product-facing versus repo-local