Summary

agents/README.md is placed inside the agents/ directory, which causes a harness warning in tools that scan agents/*.md and parse each file as a custom agent definition (e.g. GitHub Copilot CLI).

What happens

GitHub Copilot CLI scans every *.md file in a plugin's agents/ directory and attempts to parse it as a custom agent (which requires YAML frontmatter with at least a description). On agent-skills, the four real agents parse fine:

• agents/code-reviewer.md ✅
• agents/security-auditor.md ✅
• agents/test-engineer.md ✅
• agents/web-performance-auditor.md ✅

But agents/README.md starts with # Agent Personas and has no YAML frontmatter, so it fails to parse and emits a warning on every session start:

[WARNING] .../installed-plugins/addy-agent-skills/agent-skills/agents/README.md:
custom agent markdown frontmatter is malformed: missing or malformed YAML frontmatter

Impact

Cosmetic only — the four real agents load fine and no skill is affected. But the warning fires on every startup and can be misread by users as "an agent/skill failed to load."

Suggested fix (any one of these)

1. Move the docs to agents/PERSONAS.md won't help (same dir). Instead move it out of the scanned folder, e.g. docs/agents.md, and link to it from the top-level README.md.
2. Or add minimal YAML frontmatter to agents/README.md so it parses as a (harmless/no-op) entry — not recommended, as it would surface a bogus "agent."
3. Document agents in the repo-root README.md instead of shipping a README inside agents/.

Option 1 (relocate to docs/) is cleanest and keeps agents/ containing only real agent definitions.

Environment

• GitHub Copilot CLI 1.0.61 (macOS)
• agent-skills plugin v1.0.0