FTC Skill Builder

This skill teaches you how to create high-quality skills for the FTC Claude Skills Marketplace. Skills are knowledge packs that help AI coding agents assist FTC teams with specific hardware, libraries, frameworks, or tools.

Quick Reference

When to Create a Skill vs Other Options

FTC Skill Categories

Available Commands

Note: Version bumps are automated during the release process. Contributors should add changes to the ## [Unreleased] section of CHANGELOG.md instead. See RELEASES.md for details.

Skill Anatomy

plugins/your-skill-name/
├── plugin.json                    # Plugin metadata
├── CHANGELOG.md                   # Version history
└── skills/
    └── your-skill-name/
        ├── SKILL.md               # Main instructions (required)
        ├── API_REFERENCE.md       # Detailed API docs (optional)
        ├── TROUBLESHOOTING.md     # Common issues (optional)
        ├── EXAMPLES.md            # Extended examples (optional)
        └── scripts/               # Utility scripts (optional)
            └── convert.py

plugin.json Format (IMPORTANT)

Every plugin needs a plugin.json file with the correct schema:

{
  "name": "your-skill-name",
  "version": "1.0.0",
  "description": "Brief description for marketplace listing",
  "author": {
    "name": "Your Name or Team",
    "url": "https://github.com/your-username"
  },
  "repository": "https://github.com/ncssm-robotics/ftc-claude",
  "license": "MIT",
  "keywords": ["ftc", "category", "relevant", "keywords"]
}

Required Fields

Author Object Format

"author": {
  "name": "NCSSM Robotics",
  "url": "https://github.com/ncssm-robotics"
}

Common Mistake: Using "author": "Name" (string) instead of an object will cause installation to fail.

Optional but Recommended Fields

Invalid Fields (Do NOT Use)

These fields are NOT supported and will cause errors:

• ❌ tags – use keywords instead
• ❌ compatibility – not a valid field
• ❌ author as string – must be object

marketplace.json Entry

When adding your plugin to the marketplace, add an entry to .claude-plugin/marketplace.json:

{
  "name": "your-skill-name",
  "description": "Brief description",
  "source": "./plugins/your-skill-name",
  "skills": ["./skills/your-skill-name"]
}

Marketplace Fields

Common Mistake: Using "path" instead of "source" will cause marketplace registration to fail.

Writing the Description (CRITICAL)

The description field determines when your skill activates. It must answer:

1. WHAT does this skill do?
2. WHEN should Claude use it?

Good Description (Clear WHAT + WHEN)

description: >-
  Helps configure and use the GoBilda Pinpoint odometry computer for robot
  localization. Use when setting up Pinpoint, configuring pod offsets,
  troubleshooting LED status, tuning encoders, or integrating with Pedro Pathing.

Why it works:

• WHAT: Configure GoBilda Pinpoint odometry
• WHEN: Setup, pod offsets, LED status, tuning, Pedro integration

Bad Description (Too Vague)

description: Helps with odometry.

Why it fails:

• No specific hardware mentioned
• No trigger scenarios
• Won’t activate on relevant questions

FTC-Specific Trigger Words

Include these in descriptions where relevant:

• Hardware: “GoBilda”, “REV”, “Limelight”, “Spark Mini”, “encoder”
• Libraries: “Pedro Pathing”, “RoadRunner”, “FTCLib”, “NextFTC”
• Concepts: “autonomous”, “teleop”, “path following”, “PID”, “odometry”
• Actions: “setup”, “configure”, “tune”, “troubleshoot”, “integrate”

Frontmatter Reference

---
name: your-skill-name              # Required: kebab-case, max 64 chars
description: >-                    # Required: max 1024 chars
  What this skill does.
  Use when [trigger 1], [trigger 2], or [trigger 3].
license: MIT                       # Recommended for FTC community
compatibility: Claude Code, Codex CLI, VS Code Copilot, Cursor
metadata:
  author: your-github-username     # Your GitHub username or team number
  version: "2.0.0"
  category: hardware               # hardware | library | framework | tools | game
allowed-tools: Read, Write, Edit   # Optional: restrict tool access
---

Tool Restriction Patterns

# Read-only skill (safe, no modifications)
allowed-tools: Read, Grep, Glob

# Can create/edit files
allowed-tools: Read, Write, Edit, Glob, Grep

# Can run specific commands (use uv only when scripts need external deps)
allowed-tools: Read, Write, Edit, Bash(./gradlew:*), Bash(python:*)

# Full access (omit field entirely)
# allowed-tools: (not specified)

Progressive Disclosure

Keep SKILL.md focused (~500 lines max). Link to detailed files that load on-demand.

# My Hardware Skill

## Quick Start
[Essential setup - what 80% of users need]

## Common Patterns
[Frequently used code patterns]

## Detailed Reference
For complete API documentation, see [API_REFERENCE.md](API_REFERENCE.md).
For troubleshooting guides, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md).

## Utilities
Convert coordinates:
\`\`\`bash
uv run scripts/convert.py ftc-to-pedro 0 0 90
\`\`\`

Rule: Link directly from SKILL.md. Avoid A→B→C reference chains.

Content Structure Patterns

DO Patterns Section

## Patterns

- Always call `pinpoint.update()` in your loop
- Set encoder resolution before calling `resetPosAndIMU()`
- Use mm internally, convert to inches for Pedro Pathing
- Check LED status before debugging code issues

DON’T / Anti-Patterns Section

## Anti-Patterns

- ❌ Calling `resetPosAndIMU()` while robot is moving
- ❌ Using I2C port 0 (reserved for internal IMU)
- ❌ Forgetting to call `update()` - position won't refresh
- ❌ Mixing mm and inches without conversion

Examples Section

## Examples

### Good: Proper initialization sequence

\`\`\`java
@Override
public void init() {
    pinpoint = hardwareMap.get(GoBildaPinpointDriver.class, "pinpoint");
    pinpoint.setEncoderResolution(goBILDA_4_BAR_POD);
    pinpoint.setOffsets(forwardOffset_mm, strafeOffset_mm);
    pinpoint.resetPosAndIMU();  // Robot must be stationary!
}
\`\`\`

### Bad: Wrong initialization order

\`\`\`java
// ❌ resetPosAndIMU before setEncoderResolution
@Override
public void init() {
    pinpoint = hardwareMap.get(GoBildaPinpointDriver.class, "pinpoint");
    pinpoint.resetPosAndIMU();  // Wrong! Resolution not set yet
    pinpoint.setEncoderResolution(goBILDA_4_BAR_POD);
}
\`\`\`

Scripts in Skills

Scripts execute without loading content into context (zero token cost):

## Utilities

Convert FTC coordinates to Pedro Pathing:
\`\`\`bash
python scripts/convert.py ftc-to-pedro 1.5 2.0 90
\`\`\`

Mirror red alliance pose for blue:
\`\`\`bash
python scripts/convert.py mirror-blue 7 6.75 0
\`\`\`

Choosing Between python and uv run

Use python when:

• Script has NO external dependencies (only uses Python stdlib)
• Maximum accessibility – all systems have Python
• Example: Math conversions, file parsing with sys/json/math

Use uv run when:

• Script requires external packages (numpy, requests, etc.)
• Need reproducible dependency versions
• Want isolated environment to avoid conflicts
• Example: Data analysis with pandas, API calls with requests

# Simple script with no deps - use `python`
import sys
import math

def convert_coords(x, y):
    return x * 25.4, y * 25.4  # inches to mm

# Complex script with deps - use `uv run`
import numpy as np
import requests

def fetch_and_analyze(url):
    data = requests.get(url).json()
    return np.mean(data['values'])

Make scripts executable:

chmod +x scripts/*.sh scripts/*.py

Complete SKILL.md Template

---
name: your-skill-name
description: >-
  [What this skill does - specific capabilities for FTC].
  Use when [trigger 1], [trigger 2], or [trigger 3].
license: MIT
compatibility: Claude Code, Codex CLI, VS Code Copilot, Cursor
metadata:
  author: your-github-username
  version: "2.0.0"
  category: hardware | library | framework | tools | game
---

# [Skill Name]

Brief introduction - what this helps FTC teams accomplish.

## Quick Start

### Installation/Setup
[How to add the dependency or configure hardware]

### Basic Usage
\`\`\`java
// Minimal working example
\`\`\`

## Key Concepts

| Term | Description |
|------|-------------|
| **Term 1** | What it means in FTC context |
| **Term 2** | What it means in FTC context |

## Common Patterns

### Pattern 1: [Descriptive Name]
\`\`\`java
// Code example
\`\`\`

### Pattern 2: [Descriptive Name]
\`\`\`java
// Code example
\`\`\`

## Anti-Patterns

- ❌ [Thing to avoid] - [Why it's bad]
- ❌ [Thing to avoid] - [Why it's bad]

## Examples

### Good: [Descriptive title]
\`\`\`java
// Working example with comments
\`\`\`

### Bad: [Descriptive title]
\`\`\`java
// ❌ What not to do
\`\`\`

## Reference Documentation

- [API_REFERENCE.md](API_REFERENCE.md) - Complete API documentation
- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Common issues and solutions

## External Resources

- [Official Documentation](https://example.com/docs)
- [GitHub Repository](https://github.com/example/repo)

Skill Creation Checklist

Before submitting your skill:

plugin.json

• name matches folder name (kebab-case)
• author is an object with name field (NOT a string)
• keywords array includes “ftc” (NOT tags)
• No invalid fields (tags, compatibility)

marketplace.json

• Entry added with source field (NOT path)
• skills array lists skill directories

SKILL.md

• name in frontmatter matches folder name
• description includes WHAT and WHEN triggers
• description includes FTC-specific keywords
• Under ~500 lines
• Includes Quick Start section
• Shows Good AND Bad examples
• Anti-patterns marked with ❌
• Code examples are tested and working

General

• Scripts are executable (chmod +x)
• No sensitive information (API keys, credentials)

Testing Your Skill

1. Install locally:

   ./install.sh --project your-skill-name
   

2. Start a new conversation and test triggers:

   "Help me set up [your hardware/library]"
   "How do I configure [specific feature]?"
   "Show me an example of [common task]"
   

3. Claude should ask: “Should I use the [skill-name] skill?”

4. Verify the skill provides accurate, helpful information.

Common Mistakes & Fixes