Skip to content

chore(tools): align Augment config with skill-validator #2016

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
alexeyv merged 3 commits into from
Mar 16, 2026
Merged

chore(tools): align Augment config with skill-validator #2016

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
07f1a44
chore(tools): align Augment config with skill-validator as single sou…
alexeyv Mar 15, 2026
6dc9ce0
chore(tools): remove Claude Code-specific sections from skill cheatsheet
alexeyv Mar 16, 2026
ebe490a
Merge branch 'main' into chore/augment-skill-validator-update
alexeyv Mar 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
144 changes: 11 additions & 133 deletions .augment/code_review_guidelines.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# Augment Code Review Guidelines for BMAD-METHOD
# https://docs.augmentcode.com/codereview/overview
# Focus: Workflow validation and quality
# Focus: Skill validation and quality
# Canonical rules: tools/skill-validator.md (single source of truth)

file_paths_to_ignore:
# --- Shared baseline: tool configs ---
Expand Down Expand Up @@ -48,123 +49,17 @@ file_paths_to_ignore:

areas:
# ============================================
# WORKFLOW STRUCTURE RULES
# SKILL FILES
# ============================================
workflow_structure:
description: "Workflow folder organization and required components"
skill_files:
description: "All skill content — SKILL.md, workflow.md, step files, data files, and templates within skill directories"
globs:
- "src/**/skills/**"
- "src/**/workflows/**"
- "src/**/tasks/**"
rules:
- id: "workflow_entry_point_required"
description: "Every workflow folder must have workflow.md as entry point"
severity: "high"

- id: "sharded_workflow_steps_folder"
description: "Sharded workflows (using workflow.md) must have steps/ folder with numbered files (step-01-*.md, step-02-*.md)"
severity: "high"

- id: "workflow_step_limit"
description: "Workflows should have 5-10 steps maximum to prevent context loss in LLM execution"
severity: "medium"

# ============================================
# WORKFLOW ENTRY FILE RULES
# ============================================
workflow_definitions:
description: "Workflow entry files (workflow.md)"
globs:
- "src/**/workflows/**/workflow.md"
rules:
- id: "workflow_name_required"
description: "Workflow entry files must define 'name' field in frontmatter or root element"
severity: "high"

- id: "workflow_description_required"
description: "Workflow entry files must include 'description' explaining the workflow's purpose"
severity: "high"

- id: "workflow_installed_path"
description: "Workflows should define installed_path for relative file references within the workflow"
severity: "medium"

- id: "valid_step_references"
description: "Step file references in workflow entry must point to existing files"
severity: "high"

# ============================================
# SHARDED WORKFLOW STEP RULES
# ============================================
workflow_steps:
description: "Individual step files in sharded workflows"
globs:
- "src/**/workflows/**/steps/step-*.md"
rules:
- id: "step_goal_required"
description: "Each step must clearly state its goal (## STEP GOAL, ## YOUR TASK, or step n='X' goal='...')"
severity: "high"

- id: "step_mandatory_rules"
description: "Step files should include MANDATORY EXECUTION RULES section with universal agent behavior rules"
severity: "medium"

- id: "step_context_boundaries"
description: "Step files should define CONTEXT BOUNDARIES explaining available context and limits"
severity: "medium"

- id: "step_success_metrics"
description: "Step files should include SUCCESS METRICS section with ✅ checkmarks for validation criteria"
severity: "medium"

- id: "step_failure_modes"
description: "Step files should include FAILURE MODES section with ❌ marks for anti-patterns to avoid"
severity: "medium"

- id: "step_next_step_reference"
description: "Step files should reference the next step file path for sequential execution"
severity: "medium"

- id: "step_no_forward_loading"
description: "Steps must NOT load future step files until current step completes - just-in-time loading only"
severity: "high"

- id: "valid_file_references"
description: "File path references using {variable}/filename.md must point to existing files"
severity: "high"

- id: "step_naming"
description: "Step files must be named step-NN-description.md (e.g., step-01-init.md, step-02-context.md)"
severity: "medium"

- id: "halt_before_menu"
description: "Steps presenting user menus ([C] Continue, [a] Advanced, etc.) must HALT and wait for response"
severity: "high"

# ============================================
# WORKFLOW CONTENT QUALITY
# ============================================
workflow_content:
description: "Content quality and consistency rules for all workflow files"
globs:
- "src/**/workflows/**/*.md"
rules:
- id: "communication_language_variable"
description: "Workflows should use {communication_language} variable for agent output language consistency"
severity: "low"

- id: "path_placeholders_required"
description: "Use path placeholders (e.g. {project-root}, {installed_path}, {output_folder}) instead of hardcoded paths"
severity: "medium"

- id: "no_time_estimates"
description: "Workflows should NOT include time estimates - AI development speed varies significantly"
severity: "low"

- id: "facilitator_not_generator"
description: "Workflow agents should act as facilitators (guide user input) not content generators (create without input)"
severity: "medium"

- id: "no_skip_optimization"
description: "Workflows must execute steps sequentially - no skipping or 'optimizing' step order"
- id: "skill_validation"
description: "Apply the full rule catalog defined in tools/skill-validator.md. That file is the single source of truth for all skill validation rules covering SKILL.md metadata, workflow.md constraints, step file structure, path references, variable resolution, sequential execution, and skill invocation syntax."
severity: "high"

# ============================================
Expand All @@ -183,27 +78,10 @@ areas:
description: "Agent files must define persona with role, identity, communication_style, and principles"
severity: "high"

- id: "agent_menu_valid_workflows"
description: "Menu triggers must reference valid workflow paths that exist"
- id: "agent_menu_valid_skills"
description: "Menu triggers must reference valid skill names that exist"
severity: "high"

# ============================================
# TEMPLATES
# ============================================
templates:
description: "Template files for workflow outputs"
globs:
- "src/**/template*.md"
- "src/**/templates/**/*.md"
rules:
- id: "placeholder_syntax"
description: "Use {variable_name} or {{variable_name}} syntax consistently for placeholders"
severity: "medium"

- id: "template_sections_marked"
description: "Template sections that need generation should be clearly marked (e.g., <!-- GENERATE: section_name -->)"
severity: "low"

# ============================================
# DOCUMENTATION
# ============================================
Expand Down
34 changes: 34 additions & 0 deletions tools/skill-validator.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -320,3 +320,37 @@ When reporting findings, use this format:
```

If zero findings: report "All {N} rules passed. No findings." and list all passed rule IDs.

---

## Skill Spec Cheatsheet

Quick-reference for the Agent Skills open standard.
For the full standard, see: [Agent Skills specification](https://agentskills.io/specification)

Comment on lines +329 to +330
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

# First, let's check the file structure and read the specific file
git ls-files tools/skill-validator.md

Repository: bmad-code-org/BMAD-METHOD

Length of output: 93

🏁 Script executed:

# Read the file around the mentioned lines
wc -l tools/skill-validator.md

Repository: bmad-code-org/BMAD-METHOD

Length of output: 97

🏁 Script executed:

# Get context around lines 329-330
sed -n '320,340p' tools/skill-validator.md

Repository: bmad-code-org/BMAD-METHOD

Length of output: 1005

🏁 Script executed:

# Search for other references to the Agent Skills specification or versioning
rg -i "agent.*skill|specification|version" tools/skill-validator.md -A 2 -B 2

Repository: bmad-code-org/BMAD-METHOD

Length of output: 802

🏁 Script executed:

# Check if there are any other spec links or version pinning in related files
rg -i "agentskills\.io|spec.*version|version.*spec" --type md -A 2 -B 2

Repository: bmad-code-org/BMAD-METHOD

Length of output: 8852

🏁 Script executed:

# Search for "Agent Skills" mentions throughout the codebase
rg -i "agent.*skills|skills.*specification" --type md --type yaml --type json -B 2 -A 2

Repository: bmad-code-org/BMAD-METHOD

Length of output: 21470

🏁 Script executed:

# Check if there are any version references related to this specification
rg -i "skill.*version|specification.*version|agentskills" --type md

Repository: bmad-code-org/BMAD-METHOD

Length of output: 1240

🏁 Script executed:

# Look at the full context of the skill-validator.md file to see if versions are mentioned anywhere
cat -n tools/skill-validator.md | head -50

Repository: bmad-code-org/BMAD-METHOD

Length of output: 2526

🏁 Script executed:

# Check if there's any documentation about how this validator relates to spec versions
rg -i "validate.*spec|spec.*validate|validator" tools/skill-validator.md -B 3 -A 3

Repository: bmad-code-org/BMAD-METHOD

Length of output: 193

🏁 Script executed:

# Check if skill-validator.md itself mentions spec versioning anywhere
cat tools/skill-validator.md | grep -i "version\|dated\|release" | head -20

Repository: bmad-code-org/BMAD-METHOD

Length of output: 240

🏁 Script executed:

# Search for any explicit spec version tracking in documentation
rg -i "agent.*skills.*version|specification.*version" --type md -B 2 -A 2

Repository: bmad-code-org/BMAD-METHOD

Length of output: 900

🏁 Script executed:

# Check the distillate-format-reference for more context on the spec age/versioning
sed -n '1,100p' src/core/skills/bmad-distillator/resources/distillate-format-reference.md | grep -i "spec\|version" -B 2 -A 2

Repository: bmad-code-org/BMAD-METHOD

Length of output: 874

🏁 Script executed:

# Check CHANGELOG for any mentions of spec version tracking or updates
rg -i "agent.*skill.*spec|spec.*version" CHANGELOG.md -B 2 -A 2

Repository: bmad-code-org/BMAD-METHOD

Length of output: 676

🏁 Script executed:

# Check if there are any comments or documentation about the Agent Skills spec version itself
rg -i "agentskills" tools/skill-validator.md -B 5 -A 10

Repository: bmad-code-org/BMAD-METHOD

Length of output: 904

🏁 Script executed:

# Look for any examples or documentation about how to reference external specs with versions
rg -i "external.*spec|spec.*external|reference.*external" tools/ -A 3 -B 3 | head -40

Repository: bmad-code-org/BMAD-METHOD

Length of output: 2135

🏁 Script executed:

# Check if the validator mentions anything about validating against a specific spec version
sed -n '1,150p' tools/skill-validator.md | cat -n

Repository: bmad-code-org/BMAD-METHOD

Length of output: 9898

Consider adding a spec version reference or last-verified date for clarity.

The link to Agent Skills specification is unversioned. While the spec itself is young and stable, adding a comment like "Last verified against: [date or spec version]" would align with the codebase's emphasis on version precision and prevent silent spec drift from causing validation logic mismatches in the future.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@tools/skill-validator.md` around lines 329 - 330, Add a short "Last verified
against" note next to the unversioned "Agent Skills specification" link: update
the markdown around the link text "Agent Skills specification" to include either
the spec version or a verification date (e.g., "Last verified against:
YYYY-MM-DD (spec vX)") so readers know which spec revision the validator was
checked against and avoid silent drift.

### Structure
- Every skill is a directory with `SKILL.md` as the required entrypoint
- YAML frontmatter between `---` markers provides metadata; markdown body provides instructions
- Supporting files (scripts, templates, references) live alongside SKILL.md

### Path resolution
- Relative file references resolve from the directory of the file that contains the reference, not from the skill root
- Example: from `branch-a/deep/next.md`, `./deeper/final.md` resolves to `branch-a/deep/deeper/final.md`
- Example: from `branch-a/deep/next.md`, `./branch-b/alt/leaf.md` incorrectly resolves to `branch-a/deep/branch-b/alt/leaf.md`

### Frontmatter fields (standard)
- `name`: lowercase letters, numbers, hyphens only; max 64 chars; no "anthropic" or "claude"
- `description`: required, max 1024 chars; should state what the skill does AND when to use it

### Progressive disclosure — three loading levels
- **L1 Metadata** (~100 tokens): `name` + `description` loaded at startup into system prompt
- **L2 Instructions** (<5k tokens): SKILL.md body loaded only when skill is triggered
- **L3 Resources** (unlimited): additional files + scripts loaded/executed on demand; script output enters context, script code does not

### Key design principle
- Skills are filesystem-based directories, not API payloads — Claude reads them via bash/file tools
- Keep SKILL.md focused; offload detailed reference to separate files

### Practical tips
- Keep SKILL.md under 500 lines
- `description` drives auto-discovery — use keywords users would naturally say
Loading