Document skills: frontmatter with pinned refs, per-skill auth, and Matt Pocock example

[Copilot]

This PR adds first-class reference documentation for the skills: frontmatter field so users can configure skill installation correctly in workflows. It also adds a concrete, complex example covering mixed authentication patterns and links to the Matt Pocock workflow as a real-world reference.

• What was added

  • New Frontmatter Skills (skills:) section in docs/src/content/docs/reference/frontmatter.md.
  • Documents supported entry shapes:
    • string entries (owner/repo@SHA, owner/repo/path@SHA)
    • object entries with skill, optional github-token, optional github-app
  • Clarifies validation constraints:
    • refs must be pinned to a 40-char lowercase SHA
    • github-token and github-app are mutually exclusive per entry
    • github-token must be a GitHub expression

• Example and cross-references

  • Added a mixed-auth example showing:
    • shared token usage
    • per-skill token override
    • per-skill GitHub App credentials
  • Added links to:
    • glossary term for frontmatter skills
    • .github/workflows/mattpocock-skills-reviewer.md as a full production example

skills:
  - mattpocock/skills/tdd@801dca688564c529fa84f247f64472520d9ebe28
  - skill: mattpocock/skills/diagnosing-bugs@801dca688564c529fa84f247f64472520d9ebe28
    github-token: ${{ secrets.MATT_SKILLS_PAT || secrets.GITHUB_TOKEN }}
  - skill: mattpocock/skills/domain-modeling@801dca688564c529fa84f247f64472520d9ebe28
    github-app:
      client-id: ${{ vars.MATT_SKILLS_APP_CLIENT_ID }}
      private-key: ${{ secrets.MATT_SKILLS_APP_PRIVATE_KEY }}

[Copilot]

Pull request overview

Adds first-class reference documentation for the skills: frontmatter field so workflow authors can declare external skill repositories (with optional per-skill auth) that are installed during the activation job before the agent runs.

Changes:

• Documents skills: and its supported entry shapes (string vs object).
• Specifies validation constraints (40-char lowercase SHA pinning; per-entry auth field rules).
• Adds a mixed-auth YAML example plus cross-references to the glossary and a real workflow example.

Show a summary per file

File	Description
docs/src/content/docs/reference/frontmatter.md	Adds a new “Frontmatter Skills (skills:)” reference section with formats, constraints, example config, and links.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 1/1 changed files
• Comments generated: 2
• Review effort level: Low