The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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