Add company-creator skill for scaffolding agent company packages
Skill guides users through creating Agent Companies spec-conformant packages, either from scratch (with interview-driven hiring plan) or by analyzing an existing git repo and wrapping its skills/agents. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Dotta
180
.agents/skills/company-creator/SKILL.md
Normal file
180
.agents/skills/company-creator/SKILL.md
Normal file
@@ -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.
|
||||
144
.agents/skills/company-creator/references/companies-spec.md
Normal file
144
.agents/skills/company-creator/references/companies-spec.md
Normal file
@@ -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.
|
||||
184
.agents/skills/company-creator/references/example-company.md
Normal file
184
.agents/skills/company-creator/references/example-company.md
Normal file
@@ -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.
|
||||
```
|
||||
79
.agents/skills/company-creator/references/from-repo-guide.md
Normal file
79
.agents/skills/company-creator/references/from-repo-guide.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user