A skill is a single capability: “rewrite a hero section”, “run a Lighthouse audit”, “post a message to Slack”. A skill is reusable, testable, and owned by exactly one team. Agents pick skills off the skill registry the same way a developer picks libraries off npm. If you are going to write one thing for Company Agents, write a skill. Skills are the building block.

​
The shape of a skill

A skill is a directory: 
skills/
  rewrite-hero-section/
    skill.yaml            # metadata
    instructions.md       # how the agent should use this skill
    examples.md           # before/after examples
    implementation.ts     # optional code
    test.ts               # optional test
The skill.yaml is the only required file. The rest are optional but recommended.

​
skill.yaml

name: rewrite-hero-section
version: 0.3.1
description: Rewrite a marketing hero section to be sharper and on-brand
owner: marketing-team
tags: [copy, marketing, website]
inputs:
  currentCopy:
    type: string
    description: The current hero copy
  brandVoice:
    type: string
    description: Two or three lines describing the brand's voice
  length:
    type: number
    description: Target character count
    default: 180
outputs:
  revisedCopy:
    type: string
    description: The revised hero copy
  reasoning:
    type: string
    description: Why the agent made the changes it made
tools:
  - read_file
  - write_file
cost:
  estimatedTokens: 3000
  estimatedUsd: 0.05
The fields matter:
  • name is the identifier agents use to invoke the skill
  • version is semantic; increment on behavior change
  • owner is the team responsible for maintaining it
  • inputs/outputs are structured so the orchestrator can validate calls before passing them to the agent
  • tools lists the runtime tools this skill needs permission to use
  • cost is an estimate; the orchestrator uses it for budget forecasting

​
instructions.md

This is where you write the prompt the agent will follow when using this skill. Treat it like a short playbook: “To rewrite a hero section, start by reading the current copy, then…” Be specific, include anti-patterns to avoid, and reference the examples file. The agent sees this file when it calls the skill. It is not a runtime config; it is a prompt. Every word in it becomes tokens.

​
examples.md

Two or three worked examples, ideally with before/after pairs. Examples carry more weight than instructions. If you find yourself writing a long instructions file, stop and add more examples instead.

​
implementation.ts (optional)

If the skill is deterministic (run a Lighthouse audit, parse a CSV, call a specific API), you write actual code. The code exports a single function with the signature: 
export async function run(
  inputs: SkillInputs,
  ctx: SkillContext
): Promise<SkillOutputs> {
  // ...
}
The ctx gives you access to the workspace, the tool proxy, and logging. Write the function, export it, and the skill runtime takes care of loading and calling it.

​
test.ts (optional)

If you wrote an implementation, write a test for it. Tests run in CI for every skill in the registry.

​
Registering a skill

Skills live in a registry. To register one: 
company-agents skill publish ./skills/rewrite-hero-section
The CLI validates the skill, runs its tests, checks for name collisions with the same owner team, and publishes it to the local registry (or to Clipmart if you pass --public). Once registered, any agent on the same team (or on another team with an interface agreement) can call the skill by name: 
Use the rewrite-hero-section skill (v0.3) with these inputs:
  currentCopy: "..."
  brandVoice: "..."

​
Designing a good skill

A few rules of thumb:
  1. One clear verb. “Rewrite hero section” is a skill. “Make the website better” is not.
  2. Structured inputs and outputs. If your skill takes natural language and returns natural language, you have written a prompt, not a skill.
  3. Small and composable. A skill that calls three other skills is better than a skill that tries to do three things.
  4. Idempotent when possible. Running the skill twice with the same inputs should give the same outputs, or very close.
  5. Explicit failure modes. List the ways the skill can fail and what the agent should do in each case.
  6. Version every behavior change. Even a prompt edit is a version bump. Downstream agents rely on the version in the skill.yaml.

​
Skills vs. tools

A tool is a primitive: read_file, http_get, run_shell. A skill is a composition of tools with a specific purpose. Agents call tools dozens of times per task and skills a handful of times. If you find yourself wrapping a single tool call in a “skill”, just use the tool directly. If you find yourself writing the same multi-tool sequence in three different agents, extract a skill.

​
Next