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.

Additionally:

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 However, a linter wouldn't stop false postives: the goals here are orthogonal.

Edited for clarity

[rh-hemartin]

I mean... yeah.

I don't understand, looks to me that you answer should be... "Not instead, but in addition" as your comment ends with "Presumably a linter wouldn't stop false postives (the goals here are orthogonal).".

So we do need to open an issue to add a linter for in in addition of this PR?

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 8:52 PM UTC · Completed 8:57 PM UTC
Commit: d01d9fe · View workflow run →

[fullsend-ai-retro]

Retro: PR #100 — docs(#99): document valid SKILL.md frontmatter fields

PR #100 added documentation of valid SKILL.md frontmatter fields to AGENTS.md, implementing issue #99. The PR was merged by a human reviewer (Ben Alkov).

Retro limitations

This retro ran with severely degraded capability: the GH_TOKEN provisioned to the sandbox was invalid (Failed to log in to github.com using token). This prevented all GitHub API access — the retro agent could not read PR comments, review feedback, workflow run logs, issue details, or search for existing issues. Additionally, the git clone was depth-1 (shallow), so the actual PR diff could not be reconstructed from git history.

As a result, this retro can only analyze the final merged state of the code, not the workflow that produced it. One proposal is filed addressing the token provisioning issue, which is the root cause of the degraded analysis.

What I could observe

• The code agent created branch agent/99-document-skill-frontmatter and PR docs(#99): document valid SKILL.md frontmatter fields in AGENTS.md #100
• The PR title follows conventional commits format correctly: docs(#99): ...
• The merged content in AGENTS.md section 7.1 documents six frontmatter fields (name, description, license, compatibility, metadata, allowed-tools) with appropriate required/optional annotations
• The documentation includes a defensive instruction preventing the review agent from flagging novel field usage as a concern
• The change was docs-only and appears well-scoped to the issue

Dedup check

Could not search for existing issues due to invalid GH_TOKEN. Proposals below may duplicate existing issues.

Proposals filed

• Retro agent sandbox receives invalid GH_TOKEN, preventing all API access (in fullsend-ai/fullsend)
• Retro agent pre-script should validate GH_TOKEN before sandbox starts (in fullsend-ai/agents)