Skill: marlowne12/company-creator (version 1.1.0)

--- 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: https://agentcompanies.io/specification - Local quick reference: `references/companies-spec.md` - 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 the User Do not skip this step. Ask focused questions 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 - How work flows through the organization (see "Workflow" below) - 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 - Confirm the workflow you inferred from the repo (see "Workflow" below) **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: - Who gives them work and in what form (a task, a branch, a question, a review request) - What they do with it - Who they hand off to when they're done, and what that handoff looks like - What "done" means for their role **Not every company is a pipeline.** Infer the right workflow pattern from context: - **Pipeline** — sequential stages, each agent hands off to the next. Use when the repo/domain has a clear linear process (e.g. plan → build → review → ship → QA, or content ideation → draft → edit → publish). - **Hub-and-spoke** — a manager delegates to specialists who report back independently. Use when agents do different kinds of work that don't feed into each other (e.g. a CEO who dispatches to a researcher, a marketer, and an analyst). - **Collaborative** — agents work together on the same things as peers. Use for small teams where everyone contributes to the same output (e.g. a design studio, a brainstorming team). - **On-demand** — agents are summoned as needed with no fixed flow. Use when agents are more like a toolbox of specialists the user calls directly. 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:** - 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 at: `https://agentcompanies.io/specification` Also read the local 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 - For companies generated from a repo, add a references footer at the bottom of COMPANY.md body: `Generated from [repo-name](repo-url) with the company-creator skill from [Paperclip](https://github.com/paperclipai/paperclip)` **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` **Writing 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: 1. **Where work comes from** — "You receive feature ideas from the user" or "You pick up tasks assigned to you by the CTO" 2. **What you produce** — "You produce a technical plan with architecture diagrams" or "You produce a reviewed, approved branch ready for shipping" 3. **Who you hand off to** — "When your plan is locked, hand off to the Staff Engineer for implementation" or "When review passes, hand off to the Release Engineer to ship" 4. **What triggers you** — "You are activated when a new feature idea needs product-level thinking" or "You are activated when a branch is ready for pre-landing review" 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. ### 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 README.md and LICENSE **README.md** — every company package gets a README. It should be a nice, readable introduction that someone browsing GitHub would appreciate. Include: - Company name and what it does - The workflow / how the company operates - Org chart as a markdown list or table showing agents, titles, reporting structure, and skills - Brief description of each agent's role - Citations and references: link to the source repo (if from-repo), link to the Agent Companies spec (https://agentcompanies.io/specification), and link to Paperclip (https://github.com/paperclipai/paperclip) - A "Getting Started" section explaining how to import: `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. ### Step 7: 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 ## .paperclip.yaml Guidelines The `.paperclip.yaml` file is the Paperclip vendor extension. It configures adapters and env inputs per agent. ### Adapter Rules **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 CLI - `codex_local` — Codex CLI - `opencode_local` — OpenCode CLI - `pi_local` — Pi CLI - `cursor` — Cursor - `gemini_local` — Gemini CLI - `openclaw_gateway` — OpenClaw gateway Only set an adapter when: - The repo or its skills clearly target a specific runtime (e.g. gstack is built for Claude Code, so `claude_local` is appropriate) - The user explicitly requests a specific adapter - The agent's role requires a specific runtime capability ### Env Inputs Rules **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 GitHub - API keys only when a skill explicitly requires them - Never set `ANTHROPIC_API_KEY` as a default empty env variable — the runtime handles this Example with adapter (only when warranted): ```yaml schema: paperclip/v1 agents: release-engineer: adapter: type: claude_local config: model: claude-sonnet-4-6 inputs: env: GH_TOKEN: kind: secret requirement: optional ``` Example — only agents with actual overrides appear: ```yaml schema: paperclip/v1 agents: release-engineer: inputs: env: GH_TOKEN: kind: secret requirement: optional ``` In this example, only `release-engineer` appears because it needs `GH_TOKEN`. The other agents (ceo, cto, etc.) have no overrides, so they are omitted entirely from `.paperclip.yaml`. ## 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. ## Tips - **Try to keep agents 1:1** - if the readme of the source repo says something like "48 agents, 37 workflows" - then you should have 48 agents when you're done. Though when you have a lot of agents, it's a good idea to invent middle management to break them up into teams. - **Cite the upstream repo in the README** - If you're generating a readme from an upstream github, be sure to credit that near the top of the README.md. Link to the original repo and describe what it does. E.g. an [Agent Company](https://agentcompanies.io) based on [GStack](url) to do <thing> - **Every company MUST be a well-formed graph with a CEO** - make sure _every_ agent reports to either 1. their boss or 2. the ceo. You must have a CEO who reports to no one.

path: references/companies-spec.md
content: # Agent Companies Specification Reference

The normative specification lives at:

- Web: https://agentcompanies.io/specification

This file is a local quick-reference summary for common authoring tasks. Use it alongside the web spec when network access is available.

## 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.


path: references/example-company.md
content: # 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.
```


path: references/from-repo-guide.md
content: # 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


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)