From eb647ab2dbd4b8e4e71029fd5753463df2ce5d8c Mon Sep 17 00:00:00 2001 From: Dotta Date: Sun, 15 Mar 2026 07:11:57 -0500 Subject: [PATCH] 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) --- .agents/skills/company-creator/SKILL.md | 180 +++++++++++++++++ .../references/companies-spec.md | 144 ++++++++++++++ .../references/example-company.md | 184 ++++++++++++++++++ .../references/from-repo-guide.md | 79 ++++++++ 4 files changed, 587 insertions(+) create mode 100644 .agents/skills/company-creator/SKILL.md create mode 100644 .agents/skills/company-creator/references/companies-spec.md create mode 100644 .agents/skills/company-creator/references/example-company.md create mode 100644 .agents/skills/company-creator/references/from-repo-guide.md diff --git a/.agents/skills/company-creator/SKILL.md b/.agents/skills/company-creator/SKILL.md new file mode 100644 index 00000000..e9fa142a --- /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.md +├── agents/ +│ └── /AGENTS.md +├── teams/ +│ └── /TEAM.md (if teams are needed) +├── projects/ +│ └── /PROJECT.md (if projects are needed) +├── tasks/ +│ └── /TASK.md (if tasks are needed) +├── skills/ +│ └── /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//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: + : + adapter: + type: claude_local + config: + model: claude-sonnet-4-6 # or claude-opus-4-6 for CEO/leadership + inputs: + env: + : + 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: + attribution: Owner or Org Name + 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 00000000..cc8e84e9 --- /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/ +│ └── /AGENTS.md +├── teams/ +│ └── /TEAM.md +├── projects/ +│ └── / +│ ├── PROJECT.md +│ └── tasks/ +│ └── /TASK.md +├── tasks/ +│ └── /TASK.md +├── skills/ +│ └── /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: +skills: + - skill-shortname +``` + +- Body content is the agent's default instructions +- Skills resolve by shortname: `skills//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: + sha256: + 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 00000000..ba7623b9 --- /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 00000000..b9458693 --- /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: + attribution: + license: + 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