diff --git a/.augment/code_review_guidelines.yaml b/.augment/code_review_guidelines.yaml index d2b33ef4d..0a8d76dc3 100644 --- a/.augment/code_review_guidelines.yaml +++ b/.augment/code_review_guidelines.yaml @@ -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 --- @@ -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" # ============================================ @@ -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., )" - severity: "low" - # ============================================ # DOCUMENTATION # ============================================ diff --git a/tools/skill-validator.md b/tools/skill-validator.md index 2ca33ea8e..c65d90ef9 100644 --- a/tools/skill-validator.md +++ b/tools/skill-validator.md @@ -320,3 +320,79 @@ 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 and Claude Code extensions. +For the full standard, see: [Agent Skills specification](https://agentskills.io/specification) + +### 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 + +### Cross-platform portability +- Same SKILL.md format works on Claude Code, Claude API, Claude.ai, Agent SDK +- Runtime differs per surface: Code has full network access, API has none, claude.ai varies +- Skills don't sync across surfaces — deploy separately to each + +### Extra frontmatter fields (Claude Code only) +- `disable-model-invocation`: `true` = only user can invoke via `/name` +- `user-invocable`: `false` = hidden from `/` menu, only Claude auto-loads it +- `allowed-tools`: restrict tools available during skill execution +- `model`: override model for this skill +- `context`: `fork` runs skill in isolated subagent +- `agent`: which subagent type for `context: fork` — `Explore`, `Plan`, `general-purpose`, or custom +- `hooks`: skill-scoped lifecycle hooks +- `argument-hint`: autocomplete hint like `[issue-number]` + +### String substitutions +- `$ARGUMENTS` / `$ARGUMENTS[N]` / `$N` — argument placeholders +- `${CLAUDE_SESSION_ID}` — current session ID +- If `$ARGUMENTS` absent from content, args appended as `ARGUMENTS: ` + +### Dynamic context injection +- `` !`command` `` syntax runs shell commands at load time, output replaces placeholder +- Runs before Claude sees content — pure preprocessing + +### Subagent execution +- `context: fork` = skill runs in isolated context without conversation history +- Only useful for skills with explicit task instructions, not pure guidelines +- `agent` field picks execution environment; defaults to `general-purpose` + +### Invocation control matrix +| Frontmatter | User invokes | Claude invokes | Description in context | +|---|---|---|---| +| (default) | yes | yes | yes | +| `disable-model-invocation: true` | yes | no | no | +| `user-invocable: false` | no | yes | yes | + +### Context budget +- Skill descriptions budget = 2% of context window, fallback 16k chars +- Override with `SLASH_COMMAND_TOOL_CHAR_BUDGET` env var + +### Practical tips +- Keep SKILL.md under 500 lines +- `description` drives auto-discovery — use keywords users would naturally say +- Include "ultrathink" in skill content to enable extended thinking +- `.claude/commands/` files still work but skills take precedence on name collision