Skip to main content
Agent Companies packages work best when they capture real operating structure, not abstract organization charts. The goal is to make a company package useful across runtimes while keeping it readable to humans.

​
Start from real operating structure

Begin with actual recurring work:
  • how teams delegate
  • what role boundaries matter
  • which tasks repeat
  • what approvals, budgets, or policies affect execution
The strongest packages come from real runbooks, team conventions, and execution traces rather than generated boilerplate.

​
Keep the package graph legible

A reader should be able to infer the company shape quickly:
  • COMPANY.md defines the unit
  • TEAM.md defines reusable subtrees
  • AGENTS.md defines role behavior
  • PROJECT.md and TASK.md define planned work
  • SKILL.md defines reusable capability
If the hierarchy is hard to follow, activation will be hard to follow too.

​
Prefer convention over wiring

Use the conventional folder layout whenever possible. Reach for explicit includes mainly when you need external references or nonstandard locations. That keeps packages easier to author, diff, and import across tools.

​
Spend context where it matters

Once a manifest or skill activates, its body competes with everything else in the model context. Focus on what the runtime would not reliably infer on its own:
  • non-obvious delegation rules
  • project-specific procedures
  • approval boundaries
  • output expectations
  • failure-handling steps
Move long references into references/ and load them only when needed.

​
Keep roles and skills separate

AGENTS.md should describe role behavior and responsibility. SKILL.md should hold reusable procedures. If you find yourself copying the same execution method across multiple agents, that usually belongs in a shared skill package.

​
Prefer shortname skill references

In AGENTS.md, use skill attachments like: 
skills:
  - review
  - react-best-practices
This keeps agent manifests readable and lets the skill package own source refs, mirrors, or pinning details.

​
Write defaults, not menus

When multiple approaches are possible, choose a safe default and state the exception path briefly. That is more reliable than giving an agent an unranked set of options.

​
Validate with real runs

A package is ready when:
  • import preview matches the intended graph
  • role boundaries stay clear during execution
  • task scaffolding is reusable
  • activated skills improve outcomes without creating noisy false positives
Use the evaluation and description-tuning guides in this site to tighten the package over time.