work
npx machina-cli add skill PaulRBerg/agent-skills/work --openclawWork
Orchestrate end-to-end task implementation: understand the task, assess complexity, implement directly or distribute across a team, then polish the result.
Workflow
1) Parse Task
Read the task description from $ARGUMENTS.
- If
$ARGUMENTSis empty, ask the user for a task description and stop. - Extract key signals: scope (files, modules, components mentioned), action type (new feature, bug fix, refactor, migration), and any constraints.
- Note any referenced issues, PRs, or URLs for later context gathering.
2) Assess Complexity
Classify the task as simple or complex using these heuristics:
| Signal | Simple | Complex |
|---|---|---|
| File count | 1-3 files | 4+ files |
| Module span | Single module or package | Cross-module or cross-package |
| Dependency chain | No new dependencies | New packages or service integrations |
| Risk surface | Low (UI, docs, config) | High (auth, payments, data, infra) |
| Parallelism | Sequential steps only | Independent subtasks benefit from concurrency |
A task is complex when 3 or more signals fall in the complex column. When in doubt, prefer the simple path — team overhead is only justified when parallelism provides a real speedup.
- Simple — proceed to Step 3.
- Complex — proceed to Step 4.
3) Implement (Simple Path)
Execute the task directly without spawning subagents.
- Gather context: Read all relevant files. Understand existing code, tests, and conventions.
- Implement: Make the changes. Follow project conventions inferred from existing code, linters, and formatters.
- Verify: Run the narrowest useful checks:
- Formatter/linter on touched files.
- Targeted tests for touched modules.
- Type check when relevant.
- If fast checks pass, run broader checks only when risk warrants it.
- Proceed to Step 5 (Polish).
4) Implement (Complex Path)
Distribute work across a team of subagents.
4a) Decompose
Break the task into independent subtasks. Each subtask should:
- Target a distinct set of files with minimal overlap.
- Be completable without waiting on other subtasks (no circular dependencies).
- Include clear acceptance criteria.
Avoid over-decomposition. If subtasks cannot run in parallel, prefer the simple path.
4b) Create Team and Assign
Create a team with a name derived from the task (e.g., "add-auth", "refactor-api"). Create a task for each subtask. Set up dependencies when ordering matters.
Spawn implementation agents as teammates. Assign each agent one or more tasks.
Recommended team sizing:
- 1 agent per module when modules are independent.
- Separate agent for shared utilities when consumers depend on them (utility blocks consumers).
- Dedicated agent for tests if test volume is high.
4c) Coordinate
Monitor progress. As agents complete tasks:
- Review output for integration issues.
- Resolve cross-agent conflicts (merge overlaps, API mismatches).
- Assign follow-up tasks if gaps emerge.
After all tasks complete:
- Run integration verification: full test suite, type check, lint.
- Fix any integration issues directly — do not re-spawn agents for small fixes.
- Shut down teammates.
- Proceed to Step 5 (Polish).
5) Polish
Invoke /code-polish to simplify and review all session-modified files.
Wait for completion. If it reports residual risks or stop conditions, relay them to the user.
This step is mandatory — always run it, even if the implementation seems clean.
Error Handling
| Error | Response |
|---|---|
Empty $ARGUMENTS | Ask for a task description and stop |
| Verification failures after impl | Attempt to fix; if unfixable, report to user before polishing |
| Team agent fails or times out | Reclaim the task and complete it directly |
code-polish reports stop condition | Relay to user with context |
Stop Conditions
Stop and ask for direction when:
- The task description is ambiguous and multiple interpretations exist.
- Implementation requires changing public APIs or breaking contracts not mentioned in the task.
- The task scope grows beyond the original description during implementation.
- External dependencies (APIs, services, packages) are unavailable or broken.
- A CRITICAL security concern is discovered in existing code adjacent to the task.
Source
git clone https://github.com/PaulRBerg/agent-skills/blob/main/skills/work/SKILL.mdView on GitHub Overview
The Work skill orchestrates end-to-end task implementation: it reads the task description, assesses complexity, and either implements directly or distributes work to subagents for complex tasks. It ends with a thorough code-polish pass to ensure quality and consistency. This capability is invoked only when explicitly requested by the user.
How This Skill Works
It parses the task from ARGUMENTS, extracting scope, action, and constraints. It then classifies the task as simple or complex using defined signals (file count, module span, dependency chain, risk, and parallelism). For simple tasks it implements directly and verifies with targeted checks; for complex tasks it decomposes into independent subtasks, forms a team, assigns work to agents, coordinates integration, and finally runs a code-polish pass.
When to Use It
- The user explicitly invokes the skill to complete a feature, bug fix, or refactor.
- The task spans multiple files or modules and could benefit from parallelized subtasks.
- You need formal task decomposition, team coordination, and cross-subtask integration.
- A final code-polish pass is desired after implementation to ensure quality.
- You want automated verification (lint, tests, type checks) and a clean integration before closing.
Quick Start
- Step 1: Read the task description from ARGUMENTS.
- Step 2: Classify complexity and route to Simple or Complex path.
- Step 3: Implement the task and run the /code-polish pass after changes.
Best Practices
- Parse the task from ARGUMENTS and extract key signals: scope, action, constraints.
- Assess complexity with the 5 signals (files, modules, dependencies, risk, parallelism); a task is complex if 3+ signals fall in the complex column.
- When in doubt, prefer the simple path to minimize overhead; reserve complex path for real parallelizable work.
- For complex tasks, decompose into independent subtasks with clear acceptance criteria and minimal overlap.
- After implementation, run the narrowest checks first (formatting, lint, targeted tests) and then broader checks if risk warrants.
Example Use Cases
- Add a small feature to a single module and polish the changes.
- Fix a bug that touches 2-4 files across modules, using the simple path.
- Refactor an API integration that spans multiple services and requires coordination across subtasks.
- Migrate a data model across several files with accompanying tests and validations.
- Deliver an end-to-end feature with tests, linting, type checks, and a final code-polish pass.
