What happened
On PR #3434, BohdanMar added 6 new .claude/skills/ definitions. The initial versions were written as reference how-to guides. joejstuart commented on Jul 27 that skills should be "reusable workflows" with step-by-step executable instructions, not passive documentation. He provided a complete rewritten example showing the expected format: YAML frontmatter with trigger phrases, numbered ## Step N: Action sections with bash code blocks, and a final report step.
This feedback drove the largest rewrite of the PR — restructuring all 6 skills from prose to procedural runbooks. The fullsend review agent ran 6 successful rounds (19 inline comments) but never identified the structural/format issue. It focused on line-level correctness (wrong command paths, fabricated APIs, flag syntax) while missing the fundamental design concern that the skills didn't follow the expected format.
The PR took 11 days from open to merge, with the skill restructuring consuming the majority of that time (Jul 27 feedback → Jul 29 rewrite → subsequent refinement rounds).
What could go better
The repo has now established a clear, consistent skill format (YAML frontmatter with name/description/triggers + numbered step-based runbook sections with bash commands + final report step), but this expectation is not documented anywhere. AGENTS.md does not mention skills at all.
This creates two problems:
- Future skill authors must reverse-engineer the format from existing examples, risking the same how-to-guide mistake.
- Review agents (and human reviewers) have no documented criteria to assess whether a new skill follows the expected format, so structural feedback can only come from team members with implicit knowledge.
I am confident this gap exists — I verified that AGENTS.md (82 lines) contains zero mentions of "skill" and no open issues in conforma/cli address this. The risk is moderate: if no more skills are added, the documentation has limited value. But given that 6 skills were just added and the pattern is now established, future additions are plausible.
Proposed change
Add a section to AGENTS.md (or a new .claude/skills/README.md — team's preference) documenting the expected skill format. Suggested content:
- Purpose: Skills are step-by-step executable workflows that Claude Code follows, not reference documentation.
- Frontmatter: YAML block with
name (kebab-case) and description (multi-line string listing trigger phrases like "Use when users ask...").
- Body structure: Numbered
## Step N: Action sections, each containing a brief explanation, fenced bash code blocks with the actual commands, and conditional logic where needed.
- Final step: A
## Step N: Report section describing what to summarize to the user.
- Anti-pattern: Do not write skills as how-to guides, API reference docs, or passive documentation. Skills should be directly executable by the agent.
Point to an existing skill (e.g., run-tests) as the canonical example.
Validation criteria
On the next PR that adds or modifies a .claude/skills/ definition in this repo:
- The author follows the documented format without needing a design-level rewrite comment from reviewers.
- The review agent (or human reviewer) can reference the documented expectations when assessing skill quality.
- No review comment needs to say "these should be workflows, not how-to guides" — the expectation is already established in the repo docs.
Generated by retro agent from #3434
What happened
On PR #3434, BohdanMar added 6 new
.claude/skills/definitions. The initial versions were written as reference how-to guides. joejstuart commented on Jul 27 that skills should be "reusable workflows" with step-by-step executable instructions, not passive documentation. He provided a complete rewritten example showing the expected format: YAML frontmatter with trigger phrases, numbered## Step N: Actionsections with bash code blocks, and a final report step.This feedback drove the largest rewrite of the PR — restructuring all 6 skills from prose to procedural runbooks. The fullsend review agent ran 6 successful rounds (19 inline comments) but never identified the structural/format issue. It focused on line-level correctness (wrong command paths, fabricated APIs, flag syntax) while missing the fundamental design concern that the skills didn't follow the expected format.
The PR took 11 days from open to merge, with the skill restructuring consuming the majority of that time (Jul 27 feedback → Jul 29 rewrite → subsequent refinement rounds).
What could go better
The repo has now established a clear, consistent skill format (YAML frontmatter with name/description/triggers + numbered step-based runbook sections with bash commands + final report step), but this expectation is not documented anywhere. AGENTS.md does not mention skills at all.
This creates two problems:
I am confident this gap exists — I verified that AGENTS.md (82 lines) contains zero mentions of "skill" and no open issues in conforma/cli address this. The risk is moderate: if no more skills are added, the documentation has limited value. But given that 6 skills were just added and the pattern is now established, future additions are plausible.
Proposed change
Add a section to
AGENTS.md(or a new.claude/skills/README.md— team's preference) documenting the expected skill format. Suggested content:name(kebab-case) anddescription(multi-line string listing trigger phrases like "Use when users ask...").## Step N: Actionsections, each containing a brief explanation, fencedbashcode blocks with the actual commands, and conditional logic where needed.## Step N: Reportsection describing what to summarize to the user.Point to an existing skill (e.g.,
run-tests) as the canonical example.Validation criteria
On the next PR that adds or modifies a
.claude/skills/definition in this repo:Generated by retro agent from #3434