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

# Optimizing package descriptions

> How to improve Agent Companies descriptions so packages and attached skills are discovered reliably.

Agent Companies relies on lightweight discovery metadata before full activation.
That makes `description` fields important across `COMPANY.md`, `TEAM.md`, `AGENTS.md`, `PROJECT.md`, `TASK.md`, and especially `SKILL.md`.

An under-specified description means the right package or skill is missed.
An over-broad one causes false activations and wasted context.

## How discovery works

A compatible runtime should first load only lightweight metadata:

* package name
* slug
* description
* basic kind information

That metadata helps the runtime decide which company subtree, role, or skill to activate for the current task.

## Write descriptions around intent

Good descriptions explain when the package matters, not just what file it is.

Prefer:

```yaml theme={null}
description: Use this team package when work needs product and platform engineering leadership, role delegation, and code review support.
```

Over:

```yaml theme={null}
description: Engineering team package.
```

Useful patterns:

* describe the work context
* mention the kind of decisions the package supports
* include adjacent signals such as team function, workflow type, or project phase
* keep it concise enough to stay readable in a catalog

## Design trigger evals

Test descriptions with realistic prompts and planning situations.
Label each one `should_trigger` or `should_not_trigger`.

Examples:

* `Import a startup operating package with a CEO, CTO, and weekly review workflow` should trigger a company package
* `Fix a small CSS bug in one file` should not trigger a whole company package
* `Attach review and release-management skills to the engineering lead` should trigger relevant agent and skill metadata

The most valuable negative tests are near-misses that share vocabulary but do not actually need the package.

## Measure false positives and misses

For each query, check whether the runtime:

* surfaced the right package or skill
* avoided loading unrelated packages
* used skill shortnames consistently

Run each case multiple times if the underlying model behavior is nondeterministic.

## Iterate without overfitting

Use a train and validation split:

1. revise descriptions based on train-set failures
2. keep the validation set untouched
3. choose the version that generalizes best

Avoid stuffing specific keywords from failed prompts into the description.
Fix the broader concept instead.

## Common failure modes

* descriptions that name a team but not the work it handles
* descriptions that are too generic to distinguish company, team, and skill scopes
* descriptions that blur role behavior and reusable capability
* descriptions that omit the context needed for shortname-based skill activation

When the activation surface includes both company packages and skill packages, precision matters more than keyword density.