clickup-stories


Type	Skill
Plugin	awl-project-management · v0.0.12
Invoke	`/awl-project-management:clickup-stories`
Source	plugins/awl-project-management/skills/clickup-stories/SKILL.md

When Claude uses it

Create and manage user stories in ClickUp via MCP. Triggers: “create story”, “add user story”, “sprint planning”, “backlog”, “story points”, “clickup task”, “update story status”.

Trigger phrases: create story · add user story · sprint planning · backlog · story points · clickup task · update story status

Definition

Manage user stories in ClickUp using the official MCP server integration.

Prerequisites: ClickUp MCP Server

This skill requires ClickUp’s official MCP server.

Check if ClickUp MCP is Active

Look for “clickup” in the MCP server list (you can check this automatically).

Activate ClickUp MCP (if Not Present)

Guide user to run:

claude mcp add --transport http clickup https://mcp.clickup.com/mcp

Authentication: OAuth 2.1 (browser popup on first use, no manual API keys needed)

Verify Setup

After activation, test connection:

> Show me my ClickUp workspace hierarchy

Should return workspace structure with Spaces, Folders, and Lists.

ClickUp Hierarchy

Understanding the workspace structure:

Workspace (Organization)
  └─ Space (Major project area, e.g., "Engineering", "Marketing")
      └─ Folder (Optional grouping)
          └─ List (Container for tasks, e.g., "Sprint 3", "Backlog")
              └─ Task (Individual user story or task)

Key Concepts:

Workspace: Top-level organization
Space: Major project area
Folder: Optional grouping within space
List: Container for tasks (sprints, backlogs, etc.)
Task: Individual user story

AWL User Story Template

Full Structure

Title: [Descriptive title for easy identification]

User Story:
As a [persona], I [want to], [so that].

Preconditions:
- e.g. User is logged in
- e.g. User has permission X

Acceptance Criteria:
- [ ] User can go to next step
- [ ] User can ...
- [ ] System validates ...

Postconditions:
- e.g. User knows that application is not running on mobile devices
- e.g. Data is saved to database

Design:
- Figma link to relevant design(s)

Further Documentation:
- Field types (Textstring, Dropdown, Number, Boolean, etc.)
- Data sources and structure
- Default values
- Validation rules (e.g. has 1 value selected)
- Mandatory/optional fields
- Error messages

Test Data:
- Add needed test data or relevant testing info

Backend / API:
- Needed backend endpoints
- API specifications
- Data models

Notes:
- Additional context or considerations

Complete Example

Title: User can filter tasks by status

User Story:
As a project manager, I want to filter tasks by their status, so that I can quickly see what's in progress.

Preconditions:
- User is logged in
- User has access to project

Acceptance Criteria:
- [ ] Filter dropdown shows all statuses (To Do, In Progress, In Review, Done)
- [ ] Selecting status updates task list immediately
- [ ] Filter persists on page reload
- [ ] Clear filter button resets view
- [ ] Works with pagination (maintains filter across pages)

Postconditions:
- User sees filtered task list
- Filter selection saved in user preferences

Design:
- Figma: [link to filter component design]

Further Documentation:
- Status dropdown: Single-select dropdown
- Data source: task.status field
- Default value: "All statuses"
- Validation: At least one status must exist
- Error handling: Show message if no tasks match filter

Test Data:
- Tasks with various statuses
- Edge case: Empty task list

Backend / API:
- GET /api/tasks?status={status_id}
- Returns filtered task array
- Supports pagination

Notes:
- Consider adding multi-select filter in future

User Story Maturity Levels

New User Story (for Discussion/Scope)

Purpose: Story mapping, rough estimation, scope definition

Requirements:

Basic “As a… I want to… so that…” format
No acceptance criteria needed yet
Used for planning conversations

Status: “New” or “In Discussion”

Implementable User Story (Ready for Development)

Purpose: Ready for development team to implement

Requirements:

Must follow INVEST criteria
Complete acceptance criteria (3-7 recommended)
All specifications documented
Test data defined
Backend/API requirements clear

Status: “To Do” or higher

INVEST Criteria

Implementable stories must be:

Independent: Can be developed separately
Negotiable: Details can be refined
Valuable: Provides user value
Estimable: Can be sized
Small: Fits in one sprint
Testable: Clear acceptance criteria

Story Sizing Guidelines

Story Points (Fibonacci Scale)

1 point: Trivial (< 2 hours)
- Example: Change button label, fix typo
2 points: Simple (2-4 hours)
- Example: Add validation to form field
3 points: Medium (4-8 hours)
- Example: Create new API endpoint with tests
5 points: Complex (1-2 days)
- Example: Implement authentication flow
8 points: Very complex (2-3 days, consider splitting)
- Example: Build complete feature with multiple screens
13+ points: Too large, must split into smaller stories

Estimation Tips

Include time for testing and code review
Account for unknowns and dependencies
When uncertain, estimate higher
If > 8 points, break down into sub-stories

Acceptance Criteria Best Practices

Guidelines

Specific and testable: Clear pass/fail conditions
User-focused: Describe outcomes, not implementation
Include edge cases: Not just happy path
3-7 criteria: If more, consider splitting story
Use checkboxes: - [ ] format for tracking

Good Examples

✓ User can upload files up to 10MB
✓ System displays error message for invalid email format
✓ Dashboard loads in under 2 seconds
✓ Filter persists after page refresh

Bad Examples

✗ Code should be clean (not testable)
✗ Use React hooks (implementation detail)
✗ Make it fast (not specific)
✗ Handle errors properly (vague)

Common Workflows

Create User Story

Example prompt:

Create a task in the 'Backlog' list titled 'User can export reports' with description:

[paste full template]

Assign to me, priority high, due next Friday

MCP tools used: Create Task, Resolve Assignees

Sprint Planning

Example prompt:

Show me all tasks in 'Backlog' list that are unassigned and have no due date.
I want to plan next sprint.

MCP tools used: Get Workspace Tasks (with filters)

Update Story Status

Example prompt:

Change status of task 'User can filter tasks' to 'In Progress' and
add comment 'Starting development today'

MCP tools used: Update Task, Create Task Comment

Set Story Points

Example prompt:

Add custom field 'Story Points' with value 5 to task 'User can export reports'

MCP tools used: Update Task (custom fields)

Query Sprint Stories

Example prompt:

Show me all tasks assigned to me that are due this week, grouped by status

MCP tools used: Get Workspace Tasks (with assignee + date filters)

Link Dependencies

Example prompt:

Task 'Frontend implementation' depends on task 'API endpoint creation'.
Create this dependency.

MCP tools used: Update Task (relationships)

Bulk Story Creation

Example prompt:

Create 5 tasks in my 'Sprint 3' list:
1. User can login
2. User can logout
3. User can reset password
4. User can update profile
5. User can delete account

All assigned to me, 3 story points each, medium priority

MCP tools used: Create Bulk Tasks

Status Workflow

Typical story progression:

Backlog → Story created, not yet planned
To Do → Planned for current sprint
In Progress → Actively being worked on
In Review → Code review / QA testing
Done → Completed and verified

Custom Fields for Stories

Recommended Fields

Field	Type	Values	Purpose
Story Points	Number	1, 2, 3, 5, 8, 13	Estimate effort
Sprint	Dropdown	Sprint 1, Sprint 2, etc.	Plan releases
Story Type	Dropdown	Feature, Bug, Tech Debt, Spike	Categorize work
Priority	Dropdown	Urgent, High, Normal, Low	Prioritize backlog

Setting Custom Fields

Use Update Task with custom_fields parameter via MCP tools.

Meta-Information for Stories

Required Fields

Title: Descriptive (not the “As a…” statement)
- Good: “User can filter tasks by status”
- Bad: “Task filtering”
Status: Current state in workflow
Priority: Urgency level
Assignee (Owner): PO or PM
Category: Epic or Feature this story belongs to

Optional Fields

Sub-tasks: Break down implementation steps
Due date: Sprint deadline
Tags: Additional categorization
Watchers: Team members to notify

Quick Reference

Story Creation Checklist

Quick Start Example

After activating ClickUp MCP:

> Show me my ClickUp workspace hierarchy

Returns workspace structure. Then:

> Create a task in the 'Backlog' list with this user story:

Title: User can view profile

User Story:
As a user, I want to view my profile, so that I can verify my information.

Preconditions:
- User is logged in

Acceptance Criteria:
- [ ] Profile page loads under 2s
- [ ] Displays name, email, avatar
- [ ] Edit button visible for own profile

Postconditions:
- User sees current profile data

Design:
- [Figma link would go here]

Assign to me, priority high, 5 story points, due next Friday

Reference Documentation

MCP Tools Reference - Complete MCP tool catalog
User Story Templates - Additional templates and examples
Sprint Workflows - Advanced workflows and patterns

Troubleshooting

MCP Not Active

Issue: ClickUp MCP server not found

Solution: Guide user through installation:

claude mcp add --transport http clickup https://mcp.clickup.com/mcp
Restart Claude Code
Test with workspace hierarchy query

OAuth Failed

Issue: Authentication popup blocked

Solution:

Check browser popup blockers
Try different browser
Clear cache/cookies for clickup.com

Tool Permissions

Issue: MCP tools return permission errors

Solution:

Verify user has workspace access
Check workspace admin enabled API
Re-authenticate if needed

Rate Limits

Issue: “Rate limit exceeded” errors

Solution:

Batch operations instead of individual calls
Use Create Bulk Tasks for multiple stories
Contact ClickUp support for limit increases