Feature Design Assistant Skill

A Claude Code skill for turning rough feature ideas into fully-formed specifications — guiding you through structured information gathering, requirements analysis, user flow design, and technical spec creation.

When to Use This Skill

Choose this skill when:

• Translating a vague product idea into a concrete technical specification
• Collaborating with stakeholders to refine feature requirements
• Designing user flows and interaction patterns before coding
• Creating specs that developers can implement without ambiguity
• Evaluating feature feasibility and identifying technical constraints
• Preparing feature proposals or RFCs for team review

Consider alternatives when:

• You already have a detailed spec and need to implement it
• You need UI/UX wireframing or mockups (use a design tool)
• You need project management or task tracking (use Jira/Linear)

Quick Start

Copy
# Add to your Claude Code project
claude mcp add feature-design

# Design a feature from a rough idea
claude "design a feature for user notifications with email and in-app alerts"

# Refine an existing feature concept
claude "help me spec out the multi-tenant billing system"

Copy
# .claude/skills/feature-design.yml
name: feature-design
description: Turn ideas into structured feature specifications
triggers:
  - "design feature"
  - "spec out"
  - "feature requirements"
config:
  depth: standard
  include_user_flows: true
  include_data_model: true

Core Concepts

Design Process

Phase	Activity	Deliverable
1. Discovery	Ask clarifying questions about goals and users	Problem statement
2. Requirements	Define functional and non-functional requirements	Requirements list
3. User Flows	Map user journeys and interaction sequences	Flow diagrams
4. Data Model	Define entities, relationships, and storage	Schema design
5. API Design	Define endpoints, payloads, and contracts	API specification
6. Edge Cases	Identify error states, limits, and boundaries	Edge case matrix
7. Spec Document	Compile into a reviewable specification	Feature spec

Specification Template

Copy
# Feature: [Name]

## Problem Statement
What user problem does this solve? Why now?

## User Stories
- As a [role], I want to [action] so that [benefit]
- As an admin, I want to configure notification rules so that users get relevant alerts

## Requirements
### Functional
- [ ] Users can set notification preferences (email, in-app, push)
- [ ] System sends notifications on defined trigger events
- [ ] Users can mark notifications as read/unread

### Non-Functional
- Notifications delivered within 30 seconds of trigger
- Support 10,000 concurrent notification deliveries
- 99.9% delivery reliability

## User Flow
1. Event triggers notification → 2. Check user preferences →
3. Route to channels → 4. Deliver → 5. Track delivery status

## Data Model
- notifications: id, user_id, type, title, body, read_at, created_at
- notification_preferences: user_id, channel, enabled, filters

## API Endpoints
- GET /api/notifications — List user's notifications
- PATCH /api/notifications/:id/read — Mark as read
- PUT /api/notification-preferences — Update preferences

## Edge Cases
- User has all channels disabled → Store but don't deliver
- Notification fails to deliver → Retry 3x with backoff
- Bulk event triggers 10,000 notifications → Queue processing

Configuration

Parameter	Type	Default	Description
depth	string	"standard"	Spec detail level: quick, standard, comprehensive
include_user_flows	boolean	true	Include user flow diagrams in spec
include_data_model	boolean	true	Include database schema design
include_api	boolean	true	Include API endpoint specifications
include_edge_cases	boolean	true	Include edge case analysis
include_testing	boolean	false	Include test plan in specification
format	string	"markdown"	Output format: markdown, json

Best Practices

1. Start with the problem, not the solution — define what user problem you're solving before designing how to solve it; features built without a clear problem statement often solve nothing users actually need.

2. Ask five clarifying questions before writing the spec — assumptions kill specifications; ask about user types, scale expectations, existing system constraints, integration points, and success metrics.

3. Design for the common case, document the edge cases — the spec should optimize the primary user flow for simplicity; edge cases should be listed separately with handling strategies.

4. Include acceptance criteria for every requirement — each requirement should have a testable condition that defines "done"; vague requirements lead to endless iteration.

5. Keep specs versioned and link to implementation PRs — specifications should evolve as implementation reveals new constraints; link each section to the PR that implements it.

Common Issues

Spec is too detailed and becomes stale immediately — Focus on behavior and contracts, not implementation details. A spec that says "use Redis for caching" is brittle; "cache results for 5 minutes" is durable.

Stakeholders add scope during design — Set a firm scope boundary in the problem statement. When new ideas arise, add them to a "Future Considerations" section rather than expanding the current spec.

Edge cases discovered during implementation weren't in the spec — No spec catches every edge case. Build a lightweight process for adding newly discovered edge cases to the spec during implementation rather than treating the spec as frozen.