docs(EC-2039): document expected skill format in AGENTS.md

Adds a "Claude Code Skills" section to AGENTS.md documenting the expected
format for .claude/skills/ definitions: YAML frontmatter with trigger
phrases, numbered step-based runbook sections with bash commands, and a
final report step. Lists anti-patterns (how-to guides, missing triggers,
no commands) and points to run-tests as the canonical example.

This prevents future skill authors from writing prose documentation
instead of executable workflows, which caused a multi-day rewrite cycle
on PR #3434.

Resolves: https://redhat.atlassian.net/browse/EC-2039
Upstream: #3451

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: cuipinghuo

AGENTS.md

@@ -92,6 +92,58 @@ Read these before modifying the corresponding areas:
 - [internal/validate/vsa/DESIGN.md](internal/validate/vsa/DESIGN.md) — VSA: storage backends, DSSE signing rationale, expiration model
 - [acceptance/README.md](acceptance/README.md) — acceptance test framework, Testcontainers, WireMock, snapshot testing
 
+## Claude Code Skills
+
+Skills live in `.claude/skills/<name>/SKILL.md`. They are **step-by-step executable workflows**
+that Claude Code follows to complete a task — not reference documentation, how-to guides, or
+API descriptions.
+
+### Format
+
+Every skill file has two parts:
+
+**1. YAML frontmatter** with `name` (kebab-case, matches directory name) and `description`
+(multi-line string listing trigger phrases so Claude Code knows when to invoke the skill):
+
+```yaml
+---
+name: my-skill
+description: >
+  Short description. Use when users ask "trigger phrase 1", "trigger phrase 2",
+  or need help with <topic>.
+---
+```
+
+**2. Numbered step sections** — each `## Step N: Action` contains a brief explanation and
+fenced `bash` code blocks with the actual commands to run. The final step is always
+`## Step N: Report`, describing what to summarize to the user:
+
+````markdown
+## Step 1: Do the first thing
+
+Explanation of what this step accomplishes.
+
+```bash
+make build
+```
+
+## Step 2: Report
+
+Summarize:
+- What happened
+- Pass/fail status
+- What needs attention
+````
+
+### Anti-patterns
+
+- **How-to guides or reference docs.** Skills are not documentation — they are runbooks.
+  "Here's how you could run tests" is wrong; "Run these tests and report the results" is right.
+- **Missing trigger phrases.** Without them, Claude Code won't know when to invoke the skill.
+- **No bash code blocks.** Every action step should have concrete commands, not just prose.
+
+See [.claude/skills/run-tests/SKILL.md](.claude/skills/run-tests/SKILL.md) as the canonical example.
+
 ## Troubleshooting
 
 System-level issues that surface in acceptance tests: