# Agent Skills Guidelines

This directory ships the public Hive skill corpus. It inherits the root
`AGENTS.md` rules and adds skill-specific quality gates.

## Purpose

- Treat skills as workflow harnesses, not endpoint catalogs.
- Keep `SKILL.md` files short enough for agents to load quickly.
- Put deeper command matrices, schemas, and domain context in `references/`.
- Use scripts for deterministic validation instead of prose-only checks.

## Authoring Rules

- Frontmatter `description` must clearly say when to use the skill.
- The first screen of each skill should route the agent through discovery,
  schema lookup, bounded execution, diagnostics, and provenance reporting.
- Add or update eval prompts when changing triggers, routing, tool selection,
  output format, or failure handling.
- Prefer durable task skills over narrow one-endpoint skills.
- Do not duplicate full provider catalogs inside skill bodies; point to
  `hive://toolsets`, `search_tools`, and `get_api_endpoint_schema`.

## Verification

Run focused validation after edits:

```bash
npm run verify:agent-skills
npm --workspace @hiveintelligence/agent-skills run validate
```

Run the skills installer smoke check when packaging or install behavior changes:

```bash
npx skills add ./agent-skills --list
```