# Skill Writer

> Guide users through creating Agent Skills for Claude Code. Use when the user wants to create, write, author, or design a new Skill for TorchRec, or needs help with SKILL.md files.

- Skill: `meta-pytorch/skill-writer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add meta-pytorch/skill-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/meta-pytorch/skill-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: meta-pytorch (https://skillmd.com/u/meta-pytorch)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/meta-pytorch/skill-writer

---


# TorchRec Skill Writer

This Skill helps you create well-structured Agent Skills for Claude Code specifically for the TorchRec project.

## When to use this Skill

Use this Skill when:
- Creating a new Agent Skill for TorchRec
- Writing or updating SKILL.md files
- Designing skill structure and frontmatter
- Converting existing TorchRec workflows into Skills

## Instructions

### Step 1: Determine Skill scope

First, understand what the Skill should do:

1. **Ask clarifying questions**:
   - What specific TorchRec capability should this Skill provide?
   - When should Claude use this Skill?
   - What tools or resources does it need?

2. **Keep it focused**: One Skill = one capability
   - Good: "sharding-optimizer", "embedding-config-validator"
   - Too broad: "distributed-training", "model-tools"

### Step 2: Choose Skill location

TorchRec Skills should be placed in:
```
fbcode/torchrec/.claude/skills/<skill-name>/SKILL.md
```

### Step 3: Create Skill structure

Create the directory and files:

```bash
mkdir -p fbcode/torchrec/.claude/skills/skill-name
```

For multi-file Skills:
```
skill-name/
├── SKILL.md (required)
├── reference.md (optional)
├── examples.md (optional)
└── templates/ (optional)
```

### Step 4: Write SKILL.md frontmatter

Create YAML frontmatter with required fields:

```yaml
---
name: skill-name
description: Brief description of what this does and when to use it
---
```

**Field requirements**:

- **name**:
  - Lowercase letters, numbers, hyphens only
  - Max 64 characters
  - Must match directory name
  - Good: `sharding-optimizer`, `kjt-validator`
  - Bad: `Sharding_Optimizer`, `KJT Validator!`

- **description**:
  - Max 1024 characters
  - Include BOTH what it does AND when to use it
  - Use specific trigger words users would say
  - Mention TorchRec concepts (embeddings, sharding, KJT, etc.)

**Optional frontmatter fields**:

- **allowed-tools**: Restrict tool access (comma-separated list)
  ```yaml
  allowed-tools: Read, Grep, Glob
  ```

- **argument-hint**: Hint for expected arguments
  ```yaml
  argument-hint: [feature or task description]
  ```

### Step 5: Write effective descriptions

The description is critical for Claude to discover your Skill.

**Formula**: `[What it does] + [When to use it] + [TorchRec keywords]`

**Examples**:

✅ **Good**:
```yaml
description: Optimize sharding plans for TorchRec embedding tables. Use when configuring DistributedModelParallel, analyzing sharding strategies, or tuning embedding performance.
```

✅ **Good**:
```yaml
description: Validate KeyedJaggedTensor (KJT) configurations and debug sparse tensor issues. Use when working with KJT, debugging embedding lookups, or validating feature configurations.
```

❌ **Too vague**:
```yaml
description: Helps with TorchRec
description: For distributed training
```

### Step 6: Structure the Skill content

Use clear Markdown sections:

```markdown
# Skill Name

Brief overview of what this Skill does for TorchRec.

## Quick start

Provide a simple example to get started immediately.

## Instructions

Step-by-step guidance for Claude:
1. First step with clear action
2. Second step with expected outcome
3. Handle edge cases

## TorchRec-Specific Patterns

Document TorchRec-specific patterns and conventions.

## Examples

Show concrete usage examples with TorchRec code.

## Best practices

- Key conventions to follow
- Common pitfalls to avoid
- When to use vs. not use

## Files to Reference

List important TorchRec files for context:
- `torchrec/distributed/` - Distributed training code
- `torchrec/modules/` - Core modules
```

### Step 7: Validate the Skill

Check these requirements:

✅ **File structure**:
- [ ] SKILL.md exists in correct location
- [ ] Directory name matches frontmatter `name`

✅ **YAML frontmatter**:
- [ ] Opening `---` on line 1
- [ ] Closing `---` before content
- [ ] Valid YAML (no tabs, correct indentation)
- [ ] `name` follows naming rules
- [ ] `description` is specific and < 1024 chars

✅ **Content quality**:
- [ ] Clear instructions for Claude
- [ ] TorchRec-specific examples provided
- [ ] Edge cases handled
- [ ] References to relevant TorchRec code

## TorchRec Skill Ideas

Here are some useful Skills to consider creating:

| Skill Name | Purpose |
|------------|---------|
| `sharding-optimizer` | Analyze and optimize embedding sharding plans |
| `kjt-validator` | Validate KeyedJaggedTensor configurations |
| `distributed-debug` | Debug distributed training issues |
| `embedding-benchmark` | Benchmark embedding performance |
| `migration-helper` | Help migrate to newer TorchRec APIs |

## Example: Complete TorchRec Skill

```yaml
---
name: sharding-analyzer
description: Analyze TorchRec sharding plans and suggest optimizations. Use when reviewing ShardingPlan, DistributedModelParallel configuration, or optimizing embedding distribution across devices.
---

# Sharding Analyzer

Analyze TorchRec sharding plans and suggest optimizations for embedding tables.

## Quick start

Run `/sharding-analyzer` on a file containing a ShardingPlan to get optimization suggestions.

## Instructions

1. Read the sharding plan configuration
2. Analyze table sizes and sharding strategies
3. Check for common anti-patterns:
   - Large tables with TABLE_WISE sharding
   - Small tables with ROW_WISE sharding
   - Unbalanced memory distribution
4. Suggest optimizations

## TorchRec Sharding Strategies

| Strategy | Best For | Avoid When |
|----------|----------|------------|
| TABLE_WISE | Small tables, < 1M rows | Large tables |
| ROW_WISE | Large tables, uniform access | Small tables |
| COLUMN_WISE | Wide embeddings, > 256 dim | Narrow embeddings |

## Files to Reference

- `torchrec/distributed/planner/` - Sharding planner
- `torchrec/distributed/sharding/` - Sharding implementations
```

## Output format

When creating a Skill, I will:

1. Ask clarifying questions about scope and requirements
2. Suggest a Skill name and location
3. Create the SKILL.md file with proper frontmatter
4. Include TorchRec-specific instructions and examples
5. Add references to relevant TorchRec code
6. Provide validation checklist