agent-wf

A CLI tool to scaffold AI Agent configuration for your project — rules, workflows, and skills — in one command.

Architecture Overview

This tool generates three layers of AI Agent intelligence:

Rules     → Always-on behavioral constraints (HOW the agent thinks)
             .cursorrules | CLAUDE.md | .agents/rules/rules.md | .zed/prompts/
             Examples: tech stack persona, Karpathy coding guidelines

Skills    → Opt-in domain knowledge (WHAT the agent knows)
             .agents/skills/<name>/SKILL.md
             Examples: react-best-practices, web-design-guidelines, workflow-router

Workflows → Triggered step-by-step procedures (HOW to do a specific task)
             .agents/workflows/<name>.md
             Examples: agent-routine, git-commit, code-review

Key principle: Behavioral constraints that apply to ALL tasks → Rules. Specialized knowledge needed for specific tasks → Skills. Multi-step procedures → Workflows.

Supported AI Editors

| Editor | Config file generated | |---|---| | Cursor | .cursorrules | | Zed | .zed/prompts/project-rules.md | | Antigravity (Gemini) | .agents/rules/rules.md | | Claude Code | CLAUDE.md |

Quick Start

Start a New Project

cd my-nextjs-app
npx agent-wf

Follow the interactive prompts:

1. Select project type (Frontend / Backend / Fullstack)
2. Select AI editors you use (can select multiple)
3. Select features to enable (workflows, skills, rules)

Non-Interactive (CI/Scripts)

# Full setup for a Frontend + Claude Code + all features
npx agent-wf -p frontend -i claude,cursor -f all

# Minimal setup: only commit shortcut and agent routine
npx agent-wf -p fullstack -i cursor -f agent-routine,git-commit

# Available flags:
#   -p  Project type:  frontend | backend | fullstack
#   -i  IDEs:          cursor | zed | antigravity | claude  (comma-separated)
#   -f  Features:      agent-routine | git-commit | karpathy-guidelines |
#                      workflow-router | code-review | daily-standup |
#                      browser-testing | figma-implement-design |
#                      ui-ux-pro-max | react-best-practices |
#                      web-design-guidelines | web-research | all

Adding New Skills On-the-Fly

# Interactive mode
npx agent-wf add

# Non-interactive mode (import from existing file)
npx agent-wf add -n "strapi-patterns" -t skill -d "Strapi v5 conventions" --file ./my-patterns.md

Global Personal Skills Library (~/.agents)

Agent Skills specification defines ~/.agents/skills/ as the standard location for user-level global skills. Manage this library seamlessly:

# Save a skill from current project to global library
npx agent-wf global save "react-patterns"

# Load a global skill into a new project
npx agent-wf global load "react-patterns"

# List all available global skills
npx agent-wf global list

Available Features

🔴 Rules (always-on, injected into core config)

| Feature | Description | |---|---| | karpathy-guidelines | Behavioral rules derived from Andrej Karpathy's LLM coding observations: Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution |

🟡 Workflows (triggered step-by-step)

| Feature | Trigger | Description | |---|---|---| | agent-routine | /agent-routine | Full Plan → Todo → Implement → Document → Mark Done cycle | | git-commit | /git-commit or type 1 | Auto reads git diff, generates conventional commit, pushes | | code-review | /code-review | Reviews diff for issues and improvements | | daily-standup | /daily-standup | Generates standup from recent git history | | browser-testing | /browser-testing | Automated UI testing via agent-browser | | figma-implement-design | /figma-implement-design | Translates Figma URL to production code | | ui-ux-pro-max | /ui-ux-pro-max | Generates design system and UX guidelines | | web-research | /web-research | Searches docs/GitHub for errors or patterns |

🟢 Skills (opt-in domain knowledge)

| Feature | Source | Description | |---|---|---| | workflow-router | Built-in | Smart auto-detection — routes user messages to the right workflow/skill automatically | | react-best-practices | Vercel Labs | React/Next.js coding patterns and component boundaries | | web-design-guidelines | Vercel Labs | UI/UX accessibility and design quality audit rules | | figma-implement-design | Figma | MCP server guide for pixel-perfect Figma → code | | ui-ux-pro-max | nextlevelbuilder | Comprehensive design system generation |

Daily Development Use Cases

Starting a new feature

You: "Build a user authentication page with email/password login"
Agent: → detects "build" intent → reads agent-routine.md → follows Plan → Todo → Implement

Or explicitly:

You: /agent-routine — build a login page with email/password using JWT

Committing your work

You: 1
Agent: → runs git status → git add . → reads git diff → generates conventional commit → pushes

Or:

You: /git-commit

Reviewing code before PR

You: /code-review — check the diff in the current branch
Agent: → reads git diff → checks performance, security, anti-patterns → outputs summary

Implementing a Figma design

You: /figma-implement-design — https://figma.com/design/ABC123/LoginPage?node-id=1-2
Agent: → fetches Figma node → downloads assets → translates to Tailwind/ShadCN → validates 1:1 parity

Daily standup

You: /daily-standup
Agent: → reads git log last 24h → formats: What I did / Plan / Blockers / 8hrs

Debugging with web search

You: /web-research — Error: Cannot read properties of undefined reading 'map' in React Query
Agent: → searches GitHub issues + docs → synthesizes solution

The Karpathy Rule in action

When you select karpathy-guidelines, the agent will automatically:

• Ask before assuming — "Do you want X or Y approach?" instead of picking silently
• Push back on complexity — "This could be solved with 20 lines instead of 80, want me to simplify?"
• Only touch what you asked — won't refactor adjacent code, won't add unrequested abstractions
• Define done before starting — "My success criteria is: the form submits and shows error state. Shall I proceed?"

Adding a New Skill to This Library

This section is for contributors who want to add a new built-in skill/workflow/rule to agent-wf.

Step 1: Decide the type

Ask yourself:

• Always applies to every task? → It's a Rule (add to generator.ts as a constant, append to rulesContent)
• Domain knowledge needed for specific tasks? → It's a Skill (write to .agents/skills/<name>/SKILL.md)
• Multi-step procedure triggered by user? → It's a Workflow (write to .agents/workflows/<name>.md)

Step 2: Add the content constant in generator.ts

// For a Rule:
const MY_NEW_RULES = `
## My New Behavioral Rule

- Rule 1: ...
- Rule 2: ...
`;

// For a Skill or Workflow:
const MY_NEW_SKILL = `---
description: My New Skill
---

# My New Skill

Instructions for the agent...
`;

Step 3: Wire it up in generateSetup()

// For a Rule — append to rulesContent so it goes into ALL config files:
if (selectedFeatures.includes("my-new-rule")) {
    rulesContent += "\n" + MY_NEW_RULES;
}

// For a Skill — write to .agents/skills/:
if (selectedFeatures.includes("my-new-skill")) {
    const skillDir = path.join(dirPath, ".agents", "skills", "my-new-skill");
    await fs.mkdir(skillDir, { recursive: true });
    await fs.writeFile(path.join(skillDir, "SKILL.md"), MY_NEW_SKILL.trim());
}

// For a Workflow — write to .agents/workflows/:
if (selectedFeatures.includes("my-new-workflow")) {
    await fs.writeFile(path.join(workflowsDir, "my-new-workflow.md"), MY_NEW_WORKFLOW.trim());
}

Step 4: Register in index.ts

// 1. Add to ALL_FEATURES:
const ALL_FEATURES = [
    ...
    "my-new-rule",   // or my-new-skill / my-new-workflow
];

// 2. Add to multiselect prompt:
{ value: "my-new-rule", label: "My New Rule", hint: "Brief description" },

Step 5: (Workflows only) Add trigger to buildClaudeMd()

if (selectedFeatures.includes("my-new-workflow")) {
    workflowLines.push("- `/my-new-workflow` — Description (`.agents/workflows/my-new-workflow.md`)");
}

Step 6: (Skills only) Add to buildWorkflowRouterSkill()

if (selectedFeatures.includes("my-new-skill")) {
    workflowRoutes.push({
        intent: "When user wants to do X",
        target: ".agents/skills/my-new-skill/",
        type: "skill"
    });
}

Step 7: Build and test

npm run build
mkdir test-my-feature && cd test-my-feature
node ../dist/index.js -p frontend -i claude,cursor -f my-new-rule
cat .cursorrules    # verify rule appears in core config
cat CLAUDE.md       # verify it's in Claude config

Manual Skill Installation

If npx fails to auto-install skills from the registry, install them manually:

# React Best Practices
npx -y skills add vercel-labs/agent-skills@react-best-practices

# Web Design Guidelines
npx -y skills add vercel-labs/agent-skills@web-design-guidelines

# Figma Implement Design
npx -y skills add figma/mcp-server-guide@implement-design

# UI/UX Pro Max
npx -y skills add nextlevelbuilder/ui-ux-pro-max-skill@ui-ux-pro-max

Project Structure After Setup

your-project/
├── .cursorrules                    ← Rules for Cursor
├── CLAUDE.md                       ← Rules for Claude Code (auto-read on startup)
├── .zed/prompts/project-rules.md   ← Rules for Zed
└── .agents/
    ├── rules/
    │   └── rules.md                ← Rules for Antigravity/Gemini
    ├── workflows/
    │   ├── agent-routine.md
    │   ├── git-commit.md
    │   ├── code-review.md
    │   └── ...
    └── skills/
        ├── workflow-router/SKILL.md
        ├── react-best-practices/
        └── web-design-guidelines/

Contributing

1. Fork the repo
2. Follow the Adding a New Skill guide above
3. Run npm run build and verify your output in a test directory
4. Submit a PR with the generated test output included