From automaker-tools
This skill should be used when the user asks to "create a feature", "add a feature", "plan feature implementation", "optimize features", "improve feature descriptions", "configure planning mode", "set up feature dependencies", "enhance feature cards", "batch create features", "break down work into features", or wants to create or improve feature cards for better AI agent execution in Automaker. Also use when discussing feature.json schema, feature statuses, description enhancement modes, thinking levels, planning modes (skip/lite/spec/full), or feature execution pipeline configuration.
How this skill is triggered — by the user, by Claude, or both
Slash command
/automaker-tools:feature-optimizerThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Create and optimize feature card definitions in `.automaker/features/` so Automaker's AI agents produce higher-quality implementations with fewer iterations.
Create and optimize feature card definitions in .automaker/features/ so Automaker's AI agents produce higher-quality implementations with fewer iterations.
Each feature in Automaker is stored as .automaker/features/{featureId}/feature.json. Features represent units of work on the Kanban board — the AI agent reads the feature's description and implements it in an isolated git worktree. The quality of the description directly impacts the quality of the agent's output.
Features flow through statuses: pending → running → completed (or failed) → verified.
| Status | Type | Meaning |
|---|---|---|
pending | Core | Queued, not yet started |
running | Core | Agent is actively implementing |
completed | Core | Implementation finished |
failed | Core | Agent encountered an unrecoverable error |
verified | Core | Human or reviewer confirmed the implementation |
backlog | Pipeline | On the board but not prioritized |
ready | Pipeline | Prioritized and ready to run |
in_progress | Pipeline | In the execution pipeline |
interrupted | Pipeline | Execution was halted mid-run |
waiting_approval | Pipeline | Plan generated, awaiting human review |
Generate a feature ID: feature-{Date.now()}-{random9chars} (e.g., feature-1707123456789-abc123def).
Create the feature directory and file:
.automaker/features/{featureId}/feature.json
Minimal feature:
{
"id": "feature-1707123456789-abc123def",
"category": "backlog",
"description": "Add rate limiting to the /api/features endpoint using express-rate-limit with 100 requests per 15-minute window"
}
Use categories matching project areas. Common examples: backlog, in_progress, done, or custom categories like Backend, Frontend, Infrastructure, Testing, Bug Fix, Refactoring. Categories map to Kanban board columns and are defined in .automaker/categories.json.
Before optimizing, read the current features to understand patterns:
The description field is the most impactful field — it's the primary input to the AI agent.
Structure effective descriptions with:
Example — Good description:
Add JWT authentication middleware to the Express API.
Create `src/middleware/auth.ts` that:
- Extracts Bearer token from Authorization header
- Verifies token using jsonwebtoken library (already in package.json)
- Attaches decoded user payload to `req.user`
- Returns 401 for missing/invalid tokens
Apply middleware to all routes in `src/routes/` except:
- POST /api/auth/login
- POST /api/auth/register
- GET /api/health
Follow the error handling pattern in `src/middleware/error-handler.ts`.
Add unit tests in `src/middleware/__tests__/auth.test.ts`.
Example — Bad description:
Add authentication to the API.
Automaker offers built-in enhancement modes via the POST /api/features/{id}/enhance endpoint:
| Mode | Purpose | When to Use |
|---|---|---|
improve | General quality improvement | First pass on rough descriptions |
technical | Add implementation details, file paths, patterns | After initial description is clear |
simplify | Reduce complexity, focus on core requirement | When description is overloaded |
acceptance | Add testable acceptance criteria | Before marking features ready |
ux-reviewer | Add UX considerations and user flow details | For UI/frontend features |
Enhancement history is tracked in descriptionHistory — previous versions are preserved.
Select the right planning mode based on feature complexity:
| Mode | Agent Behavior | Best For |
|---|---|---|
skip | Implement immediately, no planning | Simple changes, bug fixes, one-file edits |
lite | Quick task decomposition, then implement | Small features, 2-3 file changes |
spec | Generate spec with tasks, optionally approve | Medium features, multi-file changes |
full | Full phased plan with task tracking | Complex features, architectural changes |
Rules of thumb:
skip for features under 50 wordslite for features that touch 2-3 filesspec for features spanning 4+ files or requiring new patternsfull for features that need phased rollout or have complex dependenciesSet requirePlanApproval: true with spec or full to review the agent's plan before it executes.
Features can declare dependencies on other features via the dependencies array (list of feature IDs). Automaker uses Kahn's algorithm to resolve dependency order and blocks execution until dependencies complete.
Dependency best practices:
Select appropriate model and thinking level per feature:
| Setting | Options | Impact |
|---|---|---|
model | claude-opus, claude-sonnet, claude-haiku | Quality vs speed tradeoff |
thinkingLevel | none, low, medium, high, ultrathink | Reasoning depth (token budget) |
skipTests | true/false | Skip test generation step |
excludedPipelineSteps | Array of step IDs | Skip specific pipeline steps |
Model selection guide:
When using auto-mode to execute multiple features:
maxConcurrentAgents — Limit parallelism to avoid overwhelming the codebasefull and skip in the same batch unless intentional| Field | Type | Required | Purpose |
|---|---|---|---|
id | string | Yes | Unique feature identifier |
title | string | No | Short display name (auto-generated if empty) |
category | string | Yes | Board column (e.g., "backlog", "in_progress") |
description | string | Yes | Full implementation instructions |
priority | number | No | Sort order within category |
dependencies | string[] | No | Feature IDs this depends on |
model | string | No | Claude model override |
thinkingLevel | string | No | Extended thinking level |
planningMode | string | No | Planning approach |
requirePlanApproval | boolean | No | Require plan review before execution |
skipTests | boolean | No | Skip test generation |
imagePaths | array | No | Reference screenshots/mockups |
textFilePaths | array | No | Reference text files with content |
status | string | No | Current status — see Valid Statuses |
branchName | string | No | Git branch for this feature |
features.py is bundled with this skill. Use ${CLAUDE_SKILL_DIR} to reference it.
Run from any directory inside the project — the script walks up to find .automaker/features/.
# List features by status or category
python3 ${CLAUDE_SKILL_DIR}/scripts/features.py list --status=pending
python3 ${CLAUDE_SKILL_DIR}/scripts/features.py list --category=Core
# Filter by any field
python3 ${CLAUDE_SKILL_DIR}/scripts/features.py list --field=requirePlanApproval:true
python3 ${CLAUDE_SKILL_DIR}/scripts/features.py list --field=planningMode:skip
# Summary statistics (statuses, categories, planning modes)
python3 ${CLAUDE_SKILL_DIR}/scripts/features.py stats
# Bulk update matching features (always --dry-run first)
python3 ${CLAUDE_SKILL_DIR}/scripts/features.py update --filter=status:backlog --set=planningMode:skip --dry-run
python3 ${CLAUDE_SKILL_DIR}/scripts/features.py update --filter=status:backlog --set=requirePlanApproval:false
# Get full JSON of a single feature
python3 ${CLAUDE_SKILL_DIR}/scripts/features.py get cache-policy
# Output formats: table (default), json, ids
python3 ${CLAUDE_SKILL_DIR}/scripts/features.py list --status=pending --format=ids
Always use this bundled script instead of writing ad-hoc discovery scripts.
Feature TypeScript interface with all fields documented, including PlanSpec, ParsedTask, DescriptionHistoryEntry, and export/import types, see references/feature-schema.mdnpx claudepluginhub jbactad/claude-pluginsOrchestrates SAM workflow for new features: discovery, codebase analysis, architecture spec, task decomposition, validation, context manifest. Creates MD/YAML artifacts for GitHub issues. Use for add/plan feature requests.
Coordinates a 4-phase feature development workflow: research, implementation, progress tracking, and status checks. Useful for structured feature delivery.
Orchestrates unified workflows for feature implementation, bug fixes, autonomous batch processing, planning, ATDD agent teams, and end-to-end coding.