Create agent company packages conforming to the Agent Companies specification (agentcompanies/v1). Use when a user wants to create a new agent company from scratch, build a company around an existing git repo or skills collection, or scaffold a team/department of agents. Triggers on: "create a company", "make me a company", "build a company from this repo", "set up an agent company", "create a team of agents", "hire some agents", or when given a repo URL and asked to turn it into a company. Do NOT use for importing an existing company package (use the CLI import command instead) or for modifying a company that is already running in Paperclip.
Create agent company packages that conform to the Agent Companies specification.
Spec references:
docs/companies/companies-spec.md (read this before generating files)The user describes what they want. Interview them to flesh out the vision, then generate the package.
The user provides a git repo URL, local path, or tweet. Analyze the repo, then create a company that wraps it.
See references/from-repo-guide.md for detailed repo analysis steps.
Determine which mode applies:
Do not skip this step. Use AskUserQuestion to align with the user before writing any files.
For from-scratch companies, ask about:
For from-repo companies, present your analysis and ask:
Workflow — how does work move through this company?
A company is not just a list of agents with skills. It's an organization that takes ideas and turns them into work products. You need to understand the workflow so each agent knows:
Not every company is a pipeline. Infer the right workflow pattern from context:
For from-scratch companies, propose a workflow pattern based on what they described and ask if it fits.
For from-repo companies, infer the pattern from the repo's structure. If skills have a clear sequential dependency (like plan-ceo-review → plan-eng-review → review → ship → qa), that's a pipeline. If skills are independent capabilities, it's more likely hub-and-spoke or on-demand. State your inference in the interview so the user can confirm or adjust.
Key interviewing principles:
Before generating any files, read the normative spec:
docs/companies/companies-spec.md
Also read the quick reference: references/companies-spec.md
And the example: references/example-company.md
Create the directory structure and all files. Follow the spec's conventions exactly.
Directory structure:
<company-slug>/
├── COMPANY.md
├── agents/
│ └── <slug>/AGENTS.md
├── teams/
│ └── <slug>/TEAM.md (if teams are needed)
├── projects/
│ └── <slug>/PROJECT.md (if projects are needed)
├── tasks/
│ └── <slug>/TASK.md (if tasks are needed)
├── skills/
│ └── <slug>/SKILL.md (if custom skills are needed)
└── .paperclip.yaml (Paperclip vendor extension)
Rules:
schema: agentcompanies/v1 - other files inherit itskills/<shortname>/SKILL.mdsources with usage: referenced (see spec section 12)Generated from [repo-name](repo-url) with the company-creator skill from [Paperclip](https://github.com/paperclipai/paperclip)Reporting structure:
reportsTo set to their manager's slugreportsTo: nullreportsTo: nullWriting workflow-aware agent instructions:
Each AGENTS.md body should include not just what the agent does, but how they fit into the organization's workflow. Include:
This turns a collection of agents into an organization that actually works together. Without workflow context, agents operate in isolation — they do their job but don't know what happens before or after them.
Ask the user where to write the package. Common options:
README.md — every company package gets a README. It should be a nice, readable introduction that someone browsing GitHub would appreciate. Include:
paperclipai company import --from <path>LICENSE — include a LICENSE file. The copyright holder is the user creating the company, not the upstream repo author (they made the skills, the user is making the company). Use the same license type as the source repo (if from-repo) or ask the user (if from-scratch). Default to MIT if unclear.
Write all files, then give a brief summary:
The .paperclip.yaml file is the Paperclip vendor extension. It configures adapters and env inputs per agent.
Do not specify an adapter unless the repo or user context warrants it. If you don't know what adapter the user wants, omit the adapter block entirely — Paperclip will use its default. Specifying an unknown adapter type causes an import error.
Paperclip's supported adapter types (these are the ONLY valid values):
claude_local — Claude Code CLIcodex_local — Codex CLIopencode_local — OpenCode CLIpi_local — Pi CLIcursor — Cursorgemini_local — Gemini CLIopenclaw_gateway — OpenClaw gatewayOnly set an adapter when:
claude_local is appropriate)Do not add boilerplate env variables. Only add env inputs that the agent actually needs based on its skills or role:
GH_TOKEN for agents that push code, create PRs, or interact with GitHubANTHROPIC_API_KEY as a default empty env variable — the runtime handles thisExample with adapter (only when warranted):