Skip to content

The open-source app everyone uses to manage agents at work

Add company-creator skill for scaffolding agent company packages

Dottaeb647ab2dbd4
diff --git a/.agents/skills/company-creator/SKILL.md b/.agents/skills/company-creator/SKILL.md
new file mode 100644
index 0000000000..e9fa142a60
--- /dev/null
+++ b/.agents/skills/company-creator/SKILL.md
@@ -0,0 +1,180 @@
+---
+name: company-creator
+description: >
+ 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.
+---
+
+# Company Creator
+
+Create agent company packages that conform to the Agent Companies specification.
+
+Spec references:
+
+- Normative spec: `docs/companies/companies-spec.md` (read this before generating files)
+- Web spec: https://agentcompanies.io/specification
+- Protocol site: https://agentcompanies.io/
+
+## Two Modes
+
+### Mode 1: Company From Scratch
+
+The user describes what they want. Interview them to flesh out the vision, then generate the package.
+
+### Mode 2: Company From a Repo
+
+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](references/from-repo-guide.md) for detailed repo analysis steps.
+
+## Process
+
+### Step 1: Gather Context
+
+Determine which mode applies:
+
+- **From scratch**: What kind of company or team? What domain? What should the agents do?
+- **From repo**: Clone/read the repo. Scan for existing skills, agent configs, README, source structure.
+
+### Step 2: Interview (Use AskUserQuestion)
+
+Do not skip this step. Use AskUserQuestion to align with the user before writing any files.
+
+**For from-scratch companies**, ask about:
+
+- Company purpose and domain (1-2 sentences is fine)
+- What agents they need - propose a hiring plan based on what they described
+- Whether this is a full company (needs a CEO) or a team/department (no CEO required)
+- Any specific skills the agents should have
+- Whether they want projects and starter tasks
+
+**For from-repo companies**, present your analysis and ask:
+
+- Confirm the agents you plan to create and their roles
+- Whether to reference or vendor any discovered skills (default: reference)
+- Any additional agents or skills beyond what the repo provides
+- Company name and any customization
+
+**Key interviewing principles:**
+
+- Propose a concrete hiring plan. Don't ask open-ended "what agents do you want?" - suggest specific agents based on context and let the user adjust.
+- Keep it lean. Most users are new to agent companies. A few agents (3-5) is typical for a startup. Don't suggest 10+ agents unless the scope demands it.
+- From-scratch companies should start with a CEO who manages everyone. Teams/departments don't need one.
+- Ask 2-3 focused questions per round, not 10.
+
+### Step 3: Read the Spec
+
+Before generating any files, read the normative spec:
+
+```
+docs/companies/companies-spec.md
+```
+
+Also read the quick reference: [references/companies-spec.md](references/companies-spec.md)
+
+And the example: [references/example-company.md](references/example-company.md)
+
+### Step 4: Generate the Package
+
+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:**
+
+- Slugs must be URL-safe, lowercase, hyphenated
+- COMPANY.md gets `schema: agentcompanies/v1` - other files inherit it
+- Agent instructions go in the AGENTS.md body, not in .paperclip.yaml
+- Skills referenced by shortname in AGENTS.md resolve to `skills/<shortname>/SKILL.md`
+- For external skills, use `sources` with `usage: referenced` (see spec section 12)
+- Do not export secrets, machine-local paths, or database IDs
+- Omit empty/default fields
+
+**Reporting structure:**
+
+- Every agent except the CEO should have `reportsTo` set to their manager's slug
+- The CEO has `reportsTo: null`
+- For teams without a CEO, the top-level agent has `reportsTo: null`
+
+### Step 5: Confirm Output Location
+
+Ask the user where to write the package. Common options:
+
+- A subdirectory in the current repo
+- A new directory the user specifies
+- The current directory (if it's empty or they confirm)
+
+### Step 6: Write Files and Summarize
+
+Write all files, then give a brief summary:
+
+- Company name and what it does
+- Agent roster with roles and reporting structure
+- Skills (custom + referenced)
+- Projects and tasks if any
+- The output path
+
+## Adapter Defaults for .paperclip.yaml
+
+```yaml
+schema: paperclip/v1
+agents:
+ <agent-slug>:
+ adapter:
+ type: claude_local
+ config:
+ model: claude-sonnet-4-6 # or claude-opus-4-6 for CEO/leadership
+ inputs:
+ env:
+ <SOME_ENV_VARIABLE>:
+ kind: secret
+ requirement: optional
+ default: ""
+```
+
+## External Skill References
+
+When referencing skills from a GitHub repo, always use the references pattern:
+
+```yaml
+metadata:
+ sources:
+ - kind: github-file
+ repo: owner/repo
+ path: path/to/SKILL.md
+ commit: <full SHA from git ls-remote or the repo>
+ attribution: Owner or Org Name
+ license: <from the repo's LICENSE>
+ usage: referenced
+```
+
+Get the commit SHA with:
+
+```bash
+git ls-remote https://github.com/owner/repo HEAD
+```
+
+Do NOT copy external skill content into the package unless the user explicitly asks.
diff --git a/.agents/skills/company-creator/references/companies-spec.md b/.agents/skills/company-creator/references/companies-spec.md
new file mode 100644
index 0000000000..cc8e84e9e0
--- /dev/null
+++ b/.agents/skills/company-creator/references/companies-spec.md
@@ -0,0 +1,144 @@
+# Agent Companies Specification Reference
+
+The normative specification lives at:
+
+- Web: https://agentcompanies.io/specification
+- Local: docs/companies/companies-spec.md
+
+Read the local spec file before generating any package files. The spec defines the canonical format and all frontmatter fields. Below is a quick-reference summary for common authoring tasks.
+
+## Package Kinds
+
+| File | Kind | Purpose |
+| ---------- | ------- | ------------------------------------------------- |
+| COMPANY.md | company | Root entrypoint, org boundary and defaults |
+| TEAM.md | team | Reusable org subtree |
+| AGENTS.md | agent | One role, instructions, and attached skills |
+| PROJECT.md | project | Planned work grouping |
+| TASK.md | task | Portable starter task |
+| SKILL.md | skill | Agent Skills capability package (do not redefine) |
+
+## Directory Layout
+
+```
+company-package/
+├── COMPANY.md
+├── agents/
+│ └── <slug>/AGENTS.md
+├── teams/
+│ └── <slug>/TEAM.md
+├── projects/
+│ └── <slug>/
+│ ├── PROJECT.md
+│ └── tasks/
+│ └── <slug>/TASK.md
+├── tasks/
+│ └── <slug>/TASK.md
+├── skills/
+│ └── <slug>/SKILL.md
+├── assets/
+├── scripts/
+├── references/
+└── .paperclip.yaml (optional vendor extension)
+```
+
+## Common Frontmatter Fields
+
+```yaml
+schema: agentcompanies/v1
+kind: company | team | agent | project | task
+slug: url-safe-stable-identity
+name: Human Readable Name
+description: Short description for discovery
+version: 0.1.0
+license: MIT
+authors:
+ - name: Jane Doe
+tags: []
+metadata: {}
+sources: []
+```
+
+- `schema` usually appears only at package root
+- `kind` is optional when filename makes it obvious
+- `slug` must be URL-safe and stable
+- exporters should omit empty or default-valued fields
+
+## COMPANY.md Required Fields
+
+```yaml
+name: Company Name
+description: What this company does
+slug: company-slug
+schema: agentcompanies/v1
+```
+
+Optional: `version`, `license`, `authors`, `goals`, `includes`, `requirements.secrets`
+
+## AGENTS.md Key Fields
+
+```yaml
+name: Agent Name
+title: Role Title
+reportsTo: <agent-slug or null>
+skills:
+ - skill-shortname
+```
+
+- Body content is the agent's default instructions
+- Skills resolve by shortname: `skills/<shortname>/SKILL.md`
+- Do not export machine-specific paths or secrets
+
+## TEAM.md Key Fields
+
+```yaml
+name: Team Name
+description: What this team does
+slug: team-slug
+manager: ../agent-slug/AGENTS.md
+includes:
+ - ../agent-slug/AGENTS.md
+ - ../../skills/skill-slug/SKILL.md
+```
+
+## PROJECT.md Key Fields
+
+```yaml
+name: Project Name
+description: What this project delivers
+owner: agent-slug
+```
+
+## TASK.md Key Fields
+
+```yaml
+name: Task Name
+assignee: agent-slug
+project: project-slug
+schedule:
+ timezone: America/Chicago
+ startsAt: 2026-03-16T09:00:00-05:00
+ recurrence:
+ frequency: weekly
+ interval: 1
+ weekdays: [monday]
+ time: { hour: 9, minute: 0 }
+```
+
+## Source References (for external skills/content)
+
+```yaml
+sources:
+ - kind: github-file
+ repo: owner/repo
+ path: path/to/SKILL.md
+ commit: <full-sha>
+ sha256: <hash>
+ attribution: Owner Name
+ license: MIT
+ usage: referenced
+```
+
+Usage modes: `vendored` (bytes included), `referenced` (pointer only), `mirrored` (cached locally)
+
+Default to `referenced` for third-party content.
diff --git a/.agents/skills/company-creator/references/example-company.md b/.agents/skills/company-creator/references/example-company.md
new file mode 100644
index 0000000000..ba7623b98c
--- /dev/null
+++ b/.agents/skills/company-creator/references/example-company.md
@@ -0,0 +1,184 @@
+# Example Company Package
+
+A minimal but complete example of an agent company package.
+
+## Directory Structure
+
+```
+lean-dev-shop/
+├── COMPANY.md
+├── agents/
+│ ├── ceo/AGENTS.md
+│ ├── cto/AGENTS.md
+│ └── engineer/AGENTS.md
+├── teams/
+│ └── engineering/TEAM.md
+├── projects/
+│ └── q2-launch/
+│ ├── PROJECT.md
+│ └── tasks/
+│ └── monday-review/TASK.md
+├── tasks/
+│ └── weekly-standup/TASK.md
+├── skills/
+│ └── code-review/SKILL.md
+└── .paperclip.yaml
+```
+
+## COMPANY.md
+
+```markdown
+---
+name: Lean Dev Shop
+description: Small engineering-focused AI company that builds and ships software products
+slug: lean-dev-shop
+schema: agentcompanies/v1
+version: 1.0.0
+license: MIT
+authors:
+ - name: Example Org
+goals:
+ - Build and ship software products
+ - Maintain high code quality
+---
+
+Lean Dev Shop is a small, focused engineering company. The CEO oversees strategy and coordinates work. The CTO leads the engineering team. Engineers build and ship code.
+```
+
+## agents/ceo/AGENTS.md
+
+```markdown
+---
+name: CEO
+title: Chief Executive Officer
+reportsTo: null
+skills:
+ - paperclip
+---
+
+You are the CEO of Lean Dev Shop. You oversee company strategy, coordinate work across the team, and ensure projects ship on time.
+
+Your responsibilities:
+
+- Review and prioritize work across projects
+- Coordinate with the CTO on technical decisions
+- Ensure the company goals are being met
+```
+
+## agents/cto/AGENTS.md
+
+```markdown
+---
+name: CTO
+title: Chief Technology Officer
+reportsTo: ceo
+skills:
+ - code-review
+ - paperclip
+---
+
+You are the CTO of Lean Dev Shop. You lead the engineering team and make technical decisions.
+
+Your responsibilities:
+
+- Set technical direction and architecture
+- Review code and ensure quality standards
+- Mentor engineers and unblock technical challenges
+```
+
+## agents/engineer/AGENTS.md
+
+```markdown
+---
+name: Engineer
+title: Software Engineer
+reportsTo: cto
+skills:
+ - code-review
+ - paperclip
+---
+
+You are a software engineer at Lean Dev Shop. You write code, fix bugs, and ship features.
+
+Your responsibilities:
+
+- Implement features and fix bugs
+- Write tests and documentation
+- Participate in code reviews
+```
+
+## teams/engineering/TEAM.md
+
+```markdown
+---
+name: Engineering
+description: Product and platform engineering team
+slug: engineering
+schema: agentcompanies/v1
+manager: ../../agents/cto/AGENTS.md
+includes:
+ - ../../agents/engineer/AGENTS.md
+ - ../../skills/code-review/SKILL.md
+tags:
+ - engineering
+---
+
+The engineering team builds and maintains all software products.
+```
+
+## projects/q2-launch/PROJECT.md
+
+```markdown
+---
+name: Q2 Launch
+description: Ship the Q2 product launch
+slug: q2-launch
+owner: cto
+---
+
+Deliver all features planned for the Q2 launch, including the new dashboard and API improvements.
+```
+
+## projects/q2-launch/tasks/monday-review/TASK.md
+
+```markdown
+---
+name: Monday Review
+assignee: ceo
+project: q2-launch
+schedule:
+ timezone: America/Chicago
+ startsAt: 2026-03-16T09:00:00-05:00
+ recurrence:
+ frequency: weekly
+ interval: 1
+ weekdays:
+ - monday
+ time:
+ hour: 9
+ minute: 0
+---
+
+Review the status of Q2 Launch project. Check progress on all open tasks, identify blockers, and update priorities for the week.
+```
+
+## skills/code-review/SKILL.md (with external reference)
+
+```markdown
+---
+name: code-review
+description: Thorough code review skill for pull requests and diffs
+metadata:
+ sources:
+ - kind: github-file
+ repo: anthropics/claude-code
+ path: skills/code-review/SKILL.md
+ commit: abc123def456
+ sha256: 3b7e...9a
+ attribution: Anthropic
+ license: MIT
+ usage: referenced
+---
+
+Review code changes for correctness, style, and potential issues.
+```
diff --git a/.agents/skills/company-creator/references/from-repo-guide.md b/.agents/skills/company-creator/references/from-repo-guide.md
new file mode 100644
index 0000000000..b9458693b4
--- /dev/null
+++ b/.agents/skills/company-creator/references/from-repo-guide.md
@@ -0,0 +1,79 @@
+# Creating a Company From an Existing Repository
+
+When a user provides a git repo (URL, local path, or tweet linking to a repo), analyze it and create a company package that wraps its content.
+
+## Analysis Steps
+
+1. **Clone or read the repo** - Use `git clone` for URLs, read directly for local paths
+2. **Scan for existing agent/skill files** - Look for SKILL.md, AGENTS.md, CLAUDE.md, .claude/ directories, or similar agent configuration
+3. **Understand the repo's purpose** - Read README, package.json, main source files to understand what the project does
+4. **Identify natural agent roles** - Based on the repo's structure and purpose, determine what agents would be useful
+
+## Handling Existing Skills
+
+Many repos already contain skills (SKILL.md files). When you find them:
+
+**Default behavior: use references, not copies.**
+
+Instead of copying skill content into your company package, create a source reference:
+
+```yaml
+metadata:
+ sources:
+ - kind: github-file
+ repo: owner/repo
+ path: path/to/SKILL.md
+ commit: <get the current HEAD commit SHA>
+ attribution: <repo owner or org name>
+ license: <from repo's LICENSE file>
+ usage: referenced
+```
+
+To get the commit SHA:
+```bash
+git ls-remote https://github.com/owner/repo HEAD
+```
+
+Only vendor (copy) skills when:
+- The user explicitly asks to copy them
+- The skill is very small and tightly coupled to the company
+- The source repo is private or may become unavailable
+
+## Handling Existing Agent Configurations
+
+If the repo has agent configs (CLAUDE.md, .claude/ directories, codex configs, etc.):
+- Use them as inspiration for AGENTS.md instructions
+- Don't copy them verbatim - adapt them to the Agent Companies format
+- Preserve the intent and key instructions
+
+## Repo-Only Skills (No Agents)
+
+When a repo contains only skills and no agents:
+- Create agents that would naturally use those skills
+- The agents should be minimal - just enough to give the skills a runtime context
+- A single agent may use multiple skills from the repo
+- Name agents based on the domain the skills cover
+
+Example: A repo with `code-review`, `testing`, and `deployment` skills might become:
+- A "Lead Engineer" agent with all three skills
+- Or separate "Reviewer", "QA Engineer", and "DevOps" agents if the skills are distinct enough
+
+## Common Repo Patterns
+
+### Developer Tools / CLI repos
+- Create agents for the tool's primary use cases
+- Reference any existing skills
+- Add a project maintainer or lead agent
+
+### Library / Framework repos
+- Create agents for development, testing, documentation
+- Skills from the repo become agent capabilities
+
+### Full Application repos
+- Map to departments: engineering, product, QA
+- Create a lean team structure appropriate to the project size
+
+### Skills Collection repos (e.g. skills.sh repos)
+- Each skill or skill group gets an agent
+- Create a lightweight company or team wrapper
+- Keep the agent count proportional to the skill diversity