factory skill

---
name: factory
description: |
  Official CLI (droid) for Factory, an AI-native development platform.
  Use when you need to automate development tasks, run AI agents in CI/CD,
  configure custom subagents (droids), or manage AI skills and hooks.
  Principais funcionalidades: Interactive REPL, Headless execution, Custom Droids, MCP support.
compatibility: Requires `droid` CLI installed.
allowed-tools: Read, Bash, Write
metadata:
  source: https://docs.factory.ai/
  version: "1.x"
  updated: "2026-01-18"
---

# Factory (Droid CLI) Skill

## Overview

Factory is an AI-native development platform. Its primary tool is the **Droid CLI** (`droid`), which acts as an intelligent coding assistant capable of planning, coding, testing, and reviewing.

Use this skill when you need to:
- Automate coding tasks via CLI
- Configure AI behaviors (Skills, Hooks, Custom Droids)
- Integrate AI into CI/CD pipelines
- Manage Model Context Protocol (MCP) servers

## Installation

```bash
# Verify installation
droid --version

# Login
droid login

# Set API Key (for CI/CD or headless)
export FACTORY_API_KEY="your-key-here"
```

## Quick Start

### Interactive Mode
The main way to use Droid is the interactive REPL.

```bash
# Start a session
droid

# Start with a prompt
droid "Refactor src/utils.ts to use modern patterns"
```

**Key Interactive Shortcuts:**
- `!` (at empty prompt): Toggle **Bash Mode** (run shell commands directly)
- `/`: Access Slash Commands (e.g., `/review`, `/mcp`, `/settings`)

### Headless Mode (Exec)
For automation and scripting, use `droid exec`.

```bash
# Run a single task
droid exec "Check src/ for security vulnerabilities"

# Run with higher autonomy (allow editing)
droid exec --auto medium "Fix lint errors in src/components"
```

## Core Concepts

### Autonomy Levels
Control what Droid can do without permission.

| Level | Flag | Capabilities | Use Case |
|-------|------|--------------|----------|
| **Low** | `--auto low` | Safe edits, formatters | Refactoring, comments |
| **Medium** | `--auto medium` | Run tests, install deps, git commit | Feature dev, bug fixes |
| **High** | `--auto high` | Git push, deploy | CI/CD, full automation |

### Specification Mode (`--use-spec`)
Forces Droid to **plan before coding**. Essential for complex features.

```bash
droid exec --use-spec "Implement the user dashboard feature"
```
Droid will:
1. Analyze requirements
2. Create a detailed plan
3. Ask for approval
4. Execute the plan

## Common Patterns

### Code Review
Review changes against the base branch or uncommitted work.

```bash
# Interactive
/review

# Automation
droid exec "Review this PR for security issues and performance"
```

### Refactoring with Plan
```bash
droid exec --use-spec --auto low "Refactor the Auth service to use the new API client"
```

### Fixing Bugs
```bash
droid exec --auto medium "Run tests, identify the failure in UserTest, and fix it"
```

## Configuration Files

- **Global**: `~/.factory/settings.json` (User preferences)
- **Project**: `.factory/` (Shared configuration)
- **Context**: `AGENTS.md` (Project knowledge base for Droid)
- **Hooks**: `.factory/hooks/` (Lifecycle automation)
- **Skills**: `.factory/skills/` (Reusable capabilities)

## API Quick Reference

| Command | Description | Example |
|---------|-------------|---------|
| `droid` | Start interactive session | `droid` |
| `droid exec` | Run one-off task | `droid exec "Summarize changes"` |
| `droid login` | Authenticate | `droid login` |
| `/mcp` | Manage MCP servers | Type `/mcp` in REPL |
| `/droids` | Manage custom subagents | Type `/droids` in REPL |

## Common Gotchas

1. **Permission Prompts**: By default, `droid exec` prompts for every tool use. Use `--auto <level>` to reduce noise.
2. **Context Limits**: Large repos can overwhelm context. Use `AGENTS.md` to guide Droid on what's important.
3. **Model Selection**: Use `--model` to switch between Claude, GPT, etc., for specific tasks (e.g., use Claude Opus for complex reasoning).

## Additional Resources

- **CLI Reference**: [references/API.md](references/API.md)
- **Examples & Workflows**: [references/EXAMPLES.md](references/EXAMPLES.md)
- **Advanced Config (Hooks/Skills/MCP)**: [references/ADVANCED.md](references/ADVANCED.md)
- **Troubleshooting**: [references/TROUBLESHOOTING.md](references/TROUBLESHOOTING.md)