Code review

FTC Code Review Checks

This skill defines the code quality and structure checks for FTC marketplace skills. These checks are the source of truth for both local reviews (/review) and PR bot reviews.

Structure Checks (Errors)

These checks must pass - errors block PR merge.

Plugin Directory Structure

• plugins/<skill-name>/ directory exists
• plugins/<skill-name>/plugin.json exists
• plugins/<skill-name>/CHANGELOG.md exists
• plugins/<skill-name>/skills/<skill-name>/ directory exists
• plugins/<skill-name>/skills/<skill-name>/SKILL.md exists

plugin.json Validation

• File is valid JSON (no syntax errors)
• Has name field matching directory name
• Has version field in semver format (X.Y.Z)
• Has description field (non-empty string)
• Has author field as object (NOT a string)
• Author object has name property
• Has keywords array (NOT tags)
• Keywords array includes "ftc"

SKILL.md Frontmatter Validation

• File starts with --- (YAML frontmatter)
• Has name field matching directory name
• Has description field (non-empty, < 1024 chars)
• Has license field
• Has metadata object
• Has metadata.version field matching plugin.json version
• Has metadata.category field

Version Consistency

• Version in plugin.json matches version in SKILL.md frontmatter
• Version in marketplace.json entry matches plugin.json (if listed)

Content Quality Checks (Warnings)

These are recommendations - warnings don't block merge but should be addressed.

Description Quality

• Description explains WHAT the skill does
• Description explains WHEN to use it (trigger words)
• Description contains FTC-specific keywords
• Description is under 1024 characters

SKILL.md Content

• File is under 500 lines (use progressive disclosure)
• Has "Quick Start" or "Getting Started" section
• Has code examples (java or kotlin blocks)
• Has "Anti-Pattern" or "Don't" section with bad examples
• No [TODO: ...] placeholder markers remaining

Code Examples

• Examples include both good and bad patterns
• Bad examples are marked with comments (// Bad, // Don't, etc.)
• Examples are syntactically correct

Marketplace Checks (Errors)

Registration

• Skill is listed in .claude-plugin/marketplace.json
• Entry uses source field (NOT path)
• Entry has skills array listing skill directories
• Version in marketplace entry matches plugin.json

CHANGELOG Checks (Warnings)

Format

• CHANGELOG.md follows Keep a Changelog format
• Has ## [Unreleased] section at the top
• Categories use correct headers: Added, Changed, Fixed, Removed, Deprecated, Security

New Skill vs Update Checks

For New Skills (version 1.0.0)

• Version is 1.0.0 in all three locations
• This is CORRECT - new skills SHOULD start at 1.0.0
• CHANGELOG.md has initial 1.0.0 entry

For Skill Updates

• New entries added to ## [Unreleased] section
• Version NOT manually bumped (release process handles this)

Common Mistakes

Mistake	Fix
author as string	Use object: {"name": "...", "url": "..."}
Using tags field	Rename to keywords
Using path in marketplace	Rename to source
Missing "ftc" keyword	Add "ftc" to keywords array
SKILL.md too long	Extract to API_REFERENCE.md, TROUBLESHOOTING.md
No anti-patterns	Always show what NOT to do
Version mismatch	Ensure all 3 locations match

Running This Review

/review <skill-name> --type code

Or as part of full review:

/review <skill-name>