docs(#99): document valid SKILL.md frontmatter fields in AGENTS.md

[fullsend-ai-coder]

Add a subsection to section 7 (Skill resolution) enumerating the valid SKILL.md frontmatter fields: name (required), description (required), and allowed-tools (optional). These fields are part of the skill spec, so their first appearance in a skill file is not a novel pattern.

This gives the review agent explicit context to avoid false-positive code-organization findings when a valid-but-previously-unused field first appears in the repo.

---

Closes #99

Post-script verification

• Branch is not main/master (agent/99-document-skill-frontmatter)
• Secret scan passed (gitleaks — d0c8a34a8de55e631dea5894eb550b7b56b6212d..HEAD)
• Pre-commit hooks passed (authoritative run on runner)
• Tests ran inside sandbox

[ben-alkov]

This needs the complete YAML frontmatter spec from https://agentskills.io/specification, to wit:

# Table

Field         | Required | Constraints
--------------|----------|------------------------------------------------------------------------------------------------------------------
name          | Yes      | Max 64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen.
description   | Yes      | Max 1024 characters. Non-empty. Describes what the skill does and when to use it.
license       | No       | License name or reference to a bundled license file.
compatibility | No       | Max 500 characters. Indicates environment requirements (intended product, system packages, network access, etc.).
metadata      | No       | Arbitrary key-value mapping for additional metadata.
allowed-tools | No       | Space-separated string of pre-approved tools the skill may use. (Experimental)

[rh-hemartin]

You may need to call the fix agent on it @ben-alkov

[ben-alkov]

/fs-fix This needs the complete YAML frontmatter spec from https://agentskills.io/specification, to wit:

Field         | Required | Constraints
--------------|----------|------------------------------------------------------------------------------------------------------------------
name          | Yes      | Max 64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen.
description   | Yes      | Max 1024 characters. Non-empty. Describes what the skill does and when to use it.
license       | No       | License name or reference to a bundled license file.
compatibility | No       | Max 500 characters. Indicates environment requirements (intended product, system packages, network access, etc.).
metadata      | No       | Arbitrary key-value mapping for additional metadata.
allowed-tools | No       | Space-separated string of pre-approved tools the skill may use. (Experimental)

[fullsend-ai-coder]

🤖 Finished Fix · ✅ Success · Started 2:19 PM UTC · Completed 2:25 PM UTC
Commit: de2f978 · View workflow run →

[fullsend-ai-coder]

🔧 Fix agent — iteration 1 (human-triggered)

Addressed human instruction to add complete YAML frontmatter spec. Added 3 missing fields (license, compatibility, metadata) and enriched all 6 field entries with constraint details from the agentskills.io specification.

Fixed (1):

1. add complete YAML frontmatter spec from agentskills.io/specification (AGENTS.md): Added missing frontmatter fields (license, compatibility, metadata) with full constraint details per the agentskills.io specification. Enriched existing name entry with max-length and character restrictions, description with max-length constraint, and allowed-tools with clarified description noting it is experimental and space-separated.

Tests: passed

Decision points

• Kept the existing bullet-list format rather than switching to a table (alternatives: Markdown table matching the spec table format, Bullet list with constraint details inline; rationale: The PR already established a bullet-list format; changing to a table would be a style refactor beyond the human instruction scope. Inline constraints match the existing entries' style.)

_{Updated by fullsend fix agent}

[ralphbean]

Instead of doing this in AGENTS.md, should we do this in a linter that runs in CI?

Added context: 0
Possible mistakes: 0

[ben-alkov]

Instead of doing this in AGENTS.md, should we do this in a linter that runs in CI?

Added context: 0 Possible mistakes: 0

I mean... yeah.

The original motivator for Retro/Triage/Coder was #99 "document valid skill frontmatter fields in AGENTS.md to prevent false-positive review findings" (#94 introduced allowed-tools, which Review flagged as invalid).

Presumably a linter wouldn't stop false postives (the goals here are orthogonal).