# @standardagents/skill

Markdown-authored coding skills for composing and building Standard Agents projects

## Overview

The `@standardagents/skill` package ships editable coding skills for Standard
Agents work. Each skill is authored in plain `.md` files so teams can review,
copy, and customize the guidance without changing a generated artifact.

The first bundled skill is `agentbuilder`, which helps coding agents decide
when to use:

- `defineModel`
- `definePrompt`
- `defineTool`
- `defineAgent`
- `defineHook`
- `defineThreadEndpoint`
- subagents

## Installation

### Recommended: CLI Install

```bash
npx @standardagents/cli@latest skill
```

This opens an interactive picker so you can choose the install target.

Supported targets:

- Codex and other coding agents (Cursor, Gemini CLI, GitHub Copilot, OpenCode, and others): installs the skill folder into `~/.agents/skills`
- Claude Code: installs the skill folder into `~/.claude/skills`

Every target gets the same [Agent Skills](https://agentskills.io) folder, `agentbuilder/SKILL.md`. Without a terminal the command installs into `~/.agents/skills`.

The skill tells your coding agent to read the published [Standard Agent Specification](https://standardagentspec.org/llms.txt) and to treat it as correct when the skill and the specification disagree. There is no separate specification skill to install.

Use `--force` to overwrite an existing installed copy:

```bash
npx @standardagents/cli@latest skill --force
```

Use `--agent` to skip the picker, and `--dir` to install somewhere else, such as a project-level `.agents/skills` folder:

```bash
npx @standardagents/cli@latest skill --agent agents
npx @standardagents/cli@latest skill --agent claude
npx @standardagents/cli@latest skill --dir .agents/skills
```

### Package Install

```bash npm
npm install @standardagents/skill
```

```bash pnpm
pnpm add @standardagents/skill
```

```bash yarn
yarn add @standardagents/skill
```

## Package Layout

```text
node_modules/@standardagents/skill/
├── dist/
└── skills/
    └── agentbuilder/
        └── SKILL.md
```

## Helper API

Use the package API when you want to inspect or install the bundled skill from
Node:

```ts
import {
  copySkill,
  listSkills,
  readSkillFile,
  resolveSkillDir,
} from "@standardagents/skill"

console.log(listSkills())
console.log(resolveSkillDir("agentbuilder"))

const markdown = await readSkillFile("agentbuilder")
await copySkill("agentbuilder", ".agents/skills", { overwrite: true })
```

## Manual Editing

The skill content is intentionally stored as raw markdown. A common workflow is:

```bash
cp -R node_modules/@standardagents/skill/skills/agentbuilder .agents/skills/agentbuilder
```

Then edit:

- `.agents/skills/agentbuilder/SKILL.md`

## What The `agentbuilder` Skill Covers

- Choosing the right Standard Agents Builder primitive for a change
- Keeping prompt logic, tool logic, and orchestration concerns separate
- Knowing when subagents are warranted
- Mapping changes to the correct workspace files
- Applying the docs-and-tests checklist before landing behavior changes
- Reading the published specification before answering what it requires