Writing Flutter-Craft Skills

Overview

Create new skills for flutter-craft that follow the established patterns and integrate with the skill system.

Announce at start: "I'm using the flutter-writing-skills skill to create a new skill."

Skill Structure

Every skill needs:

skills/
└── skill-name/
    └── SKILL.md

SKILL.md Format

---
name: skill-name
description: Use when [trigger condition] - [what it does]
---

# Skill Title

## Overview

[1-2 sentence description of what this skill does]

**Core principle:** [The key rule this skill enforces]

**Announce at start:** "I'm using the [skill-name] skill to [purpose]."

## When to Use

[Clear criteria for when to trigger this skill]

## The Process

[Step-by-step workflow]

## [Domain-Specific Sections]

[Add sections relevant to the skill's domain]

## Red Flags

**Never:**
- [Things to avoid]

**Always:**
- [Things to ensure]

## REQUIRED SUB-SKILL (if applicable)

After completing this skill, you MUST invoke:
→ **flutter-craft:[next-skill]**

## Integration

**Called by:** [Which skills trigger this one]
**Pairs with:** [Related skills]

Frontmatter Rules

The frontmatter is critical - it's how Claude Code discovers skills:

---
name: skill-name           # kebab-case, unique
description: Use when...   # Must start with "Use when"
---

Description format:

• Start with "Use when [trigger]"
• Add " - [what it does]" after trigger
• Be specific about the trigger condition

Examples:

# Good
description: Use when implementing Flutter features - follows Clean Architecture layer order

# Bad (too vague)
description: Helps with Flutter development

Flutter-Craft Skill Conventions

Naming

• Use flutter- prefix for Flutter-specific skills
• Use kebab-case: flutter-feature-name
• Be descriptive but concise

Core Principles

Include a Core principle that captures the essence:

• "Evidence before claims, always"
• "Fresh subagent per task + two-stage review"
• "Domain → Data → Presentation layer order"

Announce Pattern

Skills should announce themselves:

"I'm using the [skill-name] skill to [action]."

This helps users understand which skill is active.

REQUIRED SUB-SKILL

If the skill MUST be followed by another skill:

## REQUIRED SUB-SKILL

After completing brainstorming, you MUST invoke:
→ **flutter-craft:flutter-planning**

This is NOT optional. The workflow is incomplete without planning.

Flutter-Specific Content

Include Flutter commands where relevant:

flutter analyze
flutter test
flutter build <target> --debug
flutter pub get
dart run build_runner build

Testing Your Skill

1. Syntax Check

# Read the skill file
cat skills/my-skill/SKILL.md

# Check frontmatter is valid
head -5 skills/my-skill/SKILL.md

2. Trigger Test

Verify the skill triggers correctly:

1. Start a new Claude Code session
2. Describe a scenario matching the trigger
3. Check if Claude invokes the skill

3. Workflow Test

Run through the complete workflow:

1. Follow every step in the process
2. Check REQUIRED SUB-SKILLs are invoked
3. Verify integration with other skills

Skill Categories

Workflow Skills (Core)

• Process-oriented
• Have clear steps
• Often have REQUIRED SUB-SKILLs
• Examples: brainstorming, planning, executing

Verification Skills

• Focus on checking/validating
• Include specific commands
• Examples: verification, debugging

Utility Skills

• Support other skills
• May be invoked by multiple skills
• Examples: worktrees, parallel-agents

Review Skills

• Handle feedback loops
• Two-way communication
• Examples: review-request, review-receive

Common Mistakes

Vague trigger:

# Bad
description: Use for Flutter stuff

# Good
description: Use when starting a new Flutter feature - explores requirements and designs before implementation

Missing announce:

# Bad - no announcement
## Overview
This skill helps with...

# Good
**Announce at start:** "I'm using the flutter-brainstorming skill to design this feature."

No verification steps:

# Bad - no verification
After implementation, you're done.

# Good
After implementation, run:
$ flutter analyze
$ flutter test

Checklist for New Skills

• Frontmatter has valid name and description
• Description starts with "Use when"
• Has "Announce at start" instruction
• Has clear "When to Use" section
• Has step-by-step "Process" section
• Includes Flutter-specific commands where relevant
• Has "Red Flags" section
• REQUIRED SUB-SKILL documented if applicable
• Tested trigger in Claude Code session
• Tested full workflow