> ## Documentation Index
> Fetch the complete documentation index at: https://agentcompanies.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Best practices for package authors

> How to write Agent Companies packages that are portable, readable, and effective.

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:

```yaml theme={null}
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.