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.
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"
### 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"
### 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:
### 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:
### 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
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
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
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
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
## 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)
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?