Agent skill

effective-tasks

Best practices for writing SIMBL tasks that Claude can execute with zero context. Use when creating or refining tasks for maximum clarity.

Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/effective-tasks

SKILL.md

Writing Effective SIMBL Tasks

Write tasks that Claude Code can execute with ZERO context - even in a fresh session.

Goal

A well-written task contains everything needed to complete it without searching the codebase for context. Future sessions shouldn't need to ask "what did we mean by this?"

Title Formula

Action verb + specific noun + context

Good Titles

  • "Add email validation to signup form"
  • "Fix null pointer in UserService.getProfile()"
  • "Refactor auth middleware to use JWT"
  • "Update error messages in checkout flow"
  • "Remove deprecated analytics calls"

Bad Titles

  • "Fix the bug" (what bug?)
  • "Update user stuff" (too vague)
  • "Auth" (not actionable)
  • "Investigate issue" (no clear outcome)
  • "Improvements" (not specific)

Description Structure

1. Context (What Exists Now)

Provide concrete references:

  • File paths: src/services/auth.ts
  • Function names: validateToken()
  • Current behavior: "Returns 500 when token expired"
  • Error messages: "TypeError: Cannot read property 'id' of null"
markdown
### Context
- File: `src/services/UserService.ts:45`
- Function: `getProfile(userId)`
- Current: Returns 500 on missing user
- Stack trace shows null dereference at line 52

2. Requirement (What Should Change)

Be explicit about:

  • Expected behavior: "Return 401 with error message"
  • Constraints: "Must be backwards compatible"
  • Edge cases to handle: "Null user, expired token, missing permissions"
markdown
### Requirement
- Return 404 with `{ error: "user_not_found" }` for missing users
- Keep existing behavior for valid users
- Add null check before accessing user.id

3. Relevant Code Snippets

Paste the specific code that needs changing - don't make Claude search for it:

markdown
### Current Code
\`\`\`typescript
// src/services/UserService.ts:45-55
async getProfile(userId: string) {
  const user = await this.repo.findById(userId);
  return {
    id: user.id,  // <-- crashes here when user is null
    name: user.name
  };
}
\`\`\`

Acceptance Criteria

Concrete, testable conditions with checkboxes:

markdown
### Acceptance Criteria
- [ ] `getProfile()` returns 404 for non-existent users
- [ ] Response includes `{ error: "user_not_found" }`
- [ ] Existing tests pass
- [ ] New test covers null user case
- [ ] No console errors in browser

Good Criteria

  • Specific and verifiable
  • Binary (done or not done)
  • Testable by running code

Bad Criteria

  • "Works correctly" (vague)
  • "Handles errors well" (subjective)
  • "Is performant" (no metric)

Context Embedding Tips

Paste Error Messages Directly

markdown
Error: TypeError: Cannot read property 'id' of null
    at UserService.getProfile (src/services/UserService.ts:52:15)
    at async ProfileController.show (src/controllers/profile.ts:18:22)

Reference Related Work

markdown
Related: task-12 (same service), task-8 (similar null handling)
See also: PR #234 where we fixed the same pattern in OrderService

Include External References

markdown
Per RFC 7519 section 4.1 - JWT claims must include 'exp'
Following pattern from: https://docs.example.com/auth#tokens

Add File Paths Even If Obvious

markdown
Files to modify:
- src/services/UserService.ts (main fix)
- src/services/__tests__/UserService.test.ts (add test)
- src/types/errors.ts (add UserNotFoundError if needed)

Priority Guidelines

Match priority to actual urgency:

Priority Use For
p1 Production broken, data loss, security issue
p2 Important feature, significant bug
p3 Normal development work
p4 Nice to have, polish
p5-p9 Backlog items, someday/maybe

Complete Task Example

markdown
## task-42 Fix null user crash in getProfile

[p2] [backend] [bug]

### Context
- File: `src/services/UserService.ts:45-55`
- Current: `getProfile()` crashes when user not found
- Error: `TypeError: Cannot read property 'id' of null`
- Reproduces: Call `/api/users/nonexistent-id`

### Current Code
\`\`\`typescript
async getProfile(userId: string) {
  const user = await this.repo.findById(userId);
  return {
    id: user.id,  // crashes when user is null
    name: user.name
  };
}
\`\`\`

### Requirement
Return 404 response instead of crashing. Use existing NotFoundError pattern from OrderService.

### Acceptance Criteria
- [ ] GET /api/users/:id returns 404 for non-existent user
- [ ] Response body: `{ error: "user_not_found", userId: "<id>" }`
- [ ] Existing user tests still pass
- [ ] New test: "returns 404 for missing user"

### Notes
See OrderService.getOrder() for similar pattern.
Related: task-38 (added NotFoundError class)

Expand your agent's capabilities with these related and highly-rated skills.

Didn't find tool you were looking for?

Be as detailed as possible for better results