---
title: "Frazer Skills"
description: "Frazer Skills: skills for every agent in your organization: your own skill repositories synced on every merge, public skills imported through twelve checks, skill sets by layer, one store delivered to every harness, a skill lock per session, a record of which skills each session used, analytics tied to outcomes, evals on every change, suggestions to improve a skill, and gaps where agents struggled with no skill."
url: https://frazer.ai/docs/agents/skills
index: https://frazer.ai/docs/agents/llms.txt
tokens: 7355
---

> For agents: this page is indexed at https://frazer.ai/docs/agents/llms.txt, and every page at https://frazer.ai/llms.txt. Copy commands from this file exactly.

# Frazer Skills

A **skill** is a folder of instructions, scripts and references that teaches an agent how to do one kind of work: a `SKILL.md` and its files, in the open Agent Skills format, unchanged. Your organization keeps one **skill registry** of every version its agents may load. Skills come from your own repositories, from the public, from the Marketplace and from agents’ own drafts; every version is pinned and signed; every session records which skills it was offered and which it used; and Frazer tells you which skills help, which to fix and where a skill is missing.

> **The short version:** Connect your skill repositories and every merge builds signed versions. Import a public skill with `frazer skills import`: it becomes a pull request on your mirror repository and passes twelve checks before a person allows it. Skill sets decide who gets which skills, and each session starts with a **skill lock** that does not change under it. Every load is recorded in the session, so analytics show use, cost and outcomes per version, and suggestions and gaps arrive as pull requests with their evidence.

## Words

| Word | Meaning |
| --- | --- |
| **skill version** | Immutable and content-addressed (each file’s SHA-256 and size), signed in an open format anyone can verify with open-source tools, with attestations of where it came from, what checked it, who allowed it and how it scored. Its label is the author’s `metadata.version`, else `r<n>` |
| **origin** | Where its files live: `fir://pellwyn/team-skills/skills/ledger-entry`, a Hub repository, a pinned public commit, or a Marketplace listing. Two skills with the same name from two teams stay two skills |
| **skill repository** | A Fir repository whose purpose is skills; on Frazer Hub a repository of kind `skill` |
| **mirror repository** | Your organization’s repository of imported public skills (`acme/skills-mirror`), one pull request per import or update |
| **registry states** | `candidate`, `allowed`, `held`, `blocked`, `yanked` |
| **skill set** | Entries (a skill, a pin or a channel, an activation mode, path conditions) at a layer |
| **skill lock** | The resolved list a session runs with: each skill, its origin, digest and activation |
| **lift** | The change in an outcome with the skill against matched runs without it, always with how it was measured |
| **suggestion**, **gap** | A proposed change to a skill with its evidence (`sug-…`); work where agents struggled with no helpful skill (`sgap-…`) |

## Where skills come from

### Your own skill repositories

Any Fir repository with skills at `skills/<name>/SKILL.md` or `.agents/skills/<name>/SKILL.md` is a skill repository; an optional `.frazer/skills.yaml` names folders, owners, channels, eval sets and where releases go. Connect it once:

```sh
frazer skills sources create --repository pellwyn/team-skills
```

Every pull request on it runs the skill checks as Frazer CI tasks, summarized in one line: **lint** (the format’s fields, a description of at most 1,024 characters with a warning above 200, a body of at most 500 lines, references present and one level deep, stale code paths and commands, tools within policy, trigger collisions with other skills in the sets that would get it), **scans**, **evals** for the skills it changes, **cost** (the tokens it adds to every session and per load, per harness) and **reach** (which sets, squads and agents would get it):

```text
trigger 0.86 (+0.55) · output 0.91 (+0.04) · safety 0 regressions · +38 always-on tokens · reaches 12 agents in 3 squads
```

Every merge to the release branch enters the changed skills into the registry as signed `candidate` versions; promotion to `stable` follows the repository’s rule (evals pass, then a ring of sessions without regression) or a person. The repository’s owners decide merges: agents propose skills, and people, or the improvement policy for tightening edits, merge them. Syncing follows merges, not a timer, so a fix reaches new sessions as soon as its checks pass. A repository still on GitHub connects through Fir’s one-way import until it moves. Handbook releases publish their skills the same way.

### Public skills, imported through twelve checks

An import brings a public skill into your organization. It is never a download straight into an agent’s folder.

```sh
frazer skills import hub:pellwyn/team-skills/go-errors@2.3.0 --dry-run
frazer skills import hub:pellwyn/team-skills/go-errors@2.3.0 --wait
```

| # | Check | It holds the import when |
| --- | --- | --- |
| 1 | **Resolve and pin**: the URL resolves to a repository, a commit and a path, with the owner’s age and verification and identical copies elsewhere | The source cannot be pinned (a moving branch only) |
| 2 | **Mirror**: the files at the commit become a pull request on your mirror repository (`acme/skills-mirror#212`); updates arrive the same way, with the diff | — |
| 3 | **Content profile**, strict by default: text files and script sources only, images only under `assets/`, no binaries, compiled bytecode, archives, office documents, links or hidden files; at most 64 files and 2 MiB; no invisible or bidirectional Unicode in instructions | Anything outside the profile |
| 4 | **Every byte read**: no check truncates, and each reports the coverage it achieved | Coverage below 100 % |
| 5 | **Outside references**: every URL, package and repository the skill mentions is classified; an instruction to fetch content at run time is vendored at a pinned digest or held; a host it calls becomes a declared host for egress; a package is pinned to your registry mirror | A live outside instruction source, an unpinnable package, a missing or transferred owner |
| 6 | **License**: from the frontmatter or a license file, against your organization’s policy | Unknown or refused |
| 7 | **Scanners**: several engines (static rules, malware, a behavior model, prompt-injection text, secrets), every verdict side by side, disagreements shown | A critical finding; a high finding goes to a person |
| 8 | **Review agent**: an isolated agent with read-only access, no network and no secrets reads the whole skill (the first import) or the diff since the last reviewed version | Its labels say so |
| 9 | **Sandbox run**: the skill’s trigger prompts run in a sandbox with decoy secrets planted and egress captured | A read of a secret path, egress to an undeclared host, a write outside the workspace or to instruction or memory files |
| 10 | **Safety suite**: Frazer Reviewer’s injection and exfiltration probes and the safety concepts the skill’s abilities imply, run with and without the skill | A regression beyond noise: a skill can pass every scanner and still make an agent less safe |
| 11 | **Fit**: name collisions and overlapping descriptions in the target sets; the tokens it adds per harness | A collision without an alias |
| 12 | **Decision**: a person allows it, through an approval, or the narrow rule below allows it outside production | — |

**The narrow rule: allowed without a person, outside production.** A version is allowed at once, with no person, when every one of these holds, each decided by a deterministic check whose result is in its attestation (a model’s opinion can take a skill out of the class, never put one in):

-   **Checked by Frazer’s index**: the public skill index holds this exact digest with its checks passed, re-checked within the last 30 days.
-   **Instructions only**: `SKILL.md` and Markdown or plain-text references, no scripts, executables, assets or archives; frontmatter limited to the specification’s fields and display fields, with none that makes a harness act (`allowed-tools`, `hooks`, `shell`, `model`); no inline syntax a harness runs when the skill loads.
-   **No outside references** of any kind, documentation links included: an agent with a fetch tool may follow one.
-   **A permissive license** on your organization’s list (by default Apache-2.0, MIT, BSD-2-Clause, BSD-3-Clause, ISC, MPL-2.0, CC-BY-4.0, CC0-1.0).
-   **A verified or Frazer publisher**, with no owner change since the index checked it.
-   **Outside production**: no skill set whose sessions can reach production. A production scope always opens an approval, already showing that every check passed.

An update is judged anew, so a version that adds a script or a link waits for a person even when the one before it did not. The registry’s owners get one line a day in their digest (“4 skills allowed by the narrow rule today, none in production”) with Hold on every row. Turn the rule off with `frazer skills policy update` (`narrowClass: off`); `frazer skills decisions list` shows every decision with its rule and the checks it relied on.

An import never honors a public skill’s `allowed-tools` on its own: a grant needs your organization’s policy. Imports are designed to take 5 seconds at the median for a version the public skill index already checked, 10 minutes for an unchecked skill of instructions only, and 30 minutes with scripts and a sandbox run (targets).

### The public skill index and Discover

Frazer runs the checks once per version for the most used public skills, for every organization, and publishes the verdict, the date and what was checked on Frazer Hub. Identical content is one entry, credited to its first publisher, with the copies listed. **Discover**, in the console and the CLI, searches by task (“write a database migration”) and ranks by measured lift for that kind of task, distinct principals that loaded the skill this week (shown at 50 or more), safety results and license, with the tokens a skill adds to every session shown before you import it. A public directory’s own install count appears labeled “reported by the directory, not verified”. Results from public directories that Frazer has not checked appear too, labeled by their source, so the index is never a ceiling. **Packs** install a curated set in one step.

### Marketplace packs, agent drafts and uploads

-   **Skill packs** on the Marketplace are signed releases from verified publishers, with published trigger, output and safety results, installed by pinned version; updates arrive as candidates. A paid pack sells its upkeep, evals and support, not secrecy: a skill’s text is visible to the agents and people who use it.
-   **Agent drafts.** A skill an agent writes, from a session, a gap or a pattern, is visible only to that session until it passes the evals and a person (or the improvement policy, for tightening edits) seals it. A draft is compared with the skills it drew on, and content from held, blocked or yanked skills blocks it.
-   **Uploads.** A person may upload a folder; Frazer turns it into a commit on the mirror repository and runs the import checks.

A yanked version stops serving on every mount and MCP server within 10 seconds, and every session that loaded it is told.

## Who gets which skills

A session’s skills are the union of its layers, then the plan item’s required skills, then the `off` entries:

```text
organization → project → squad role → agent revision → harness profile → plan item
```

An agent revision pins its skills, so a skill update for that agent is a new candidate revision with its own checks. A [harness profile](https://frazer.ai/docs/agents/harnesses) references a skill set, so harness, model, tools and skills travel together.

| Activation | Listed to the model | Loads when |
| --- | --- | --- |
| `auto` | Name and description | The model decides |
| `manual` | Hidden | A person types `/name`, or a plan item or campaign task names it |
| `preload` | Its whole text at start | Always (costly: for a skill a plan item requires) |
| `name-only` | The name only | The model asks for it by name |
| `off` | Not listed | Never |

Plan items may name the skills their work needs (`skills: [schema-migration]`), because agents often do not load a skill unless they are asked to. Each harness lists skills within its own budget, so a skill set compiles one catalog per harness your organization uses and reports what would be shortened or dropped before any session runs into it (`frazer skills sets update pellwyn-backend --compile`). Past about 50 skills, a router offers each session the 20 most relevant to its task plus every skill its plan item requires; its recall is measured on your own tasks, with a target of 0.95 at 20. The router starts in shadow in your organization: it ranks without changing what agents see, and decides the catalog only once its recall on your own sessions reaches the target.

**Agents configure skills.** An agent may list and read skill sets, search the registry, open an import, propose a change to a set or a skill as a pull request, run evals, and choose among skills already allowed for the scope it manages. It never allows a skill, raises a set beyond its scope or merges its own proposal. **Firms that set up agents for clients** publish their skill packs as private Marketplace offers to named organizations; a client may grant a firm a partner-managed role limited to skill sets, skill repositories and agents, approved by the client’s owners and recorded in its audit log.

## Delivery to every harness, and the skill lock

| Door | For | How |
| --- | --- | --- |
| Native | The Frazer harness | A skill tool keyed by origin and digest, verifying signatures |
| Mount | Harnesses that read skill folders | A read-only view of the content-addressed store at the folders each harness scans, never written into the repository; the mount logs opens, reads and runs |
| MCP | Any host that implements MCP’s skills extension | Your organization’s skills server through the MCP gateway: one endpoint per skill lock, cacheable for the lock’s lifetime, with the attestations |
| Plugin marketplace | Laptops without the Frazer CLI | Your organization’s marketplaces for the harnesses that read one: a marketplace file over HTTPS whose entries are archives pinned by SHA-256, changed only when a version is allowed |
| Vendor APIs | Your managed agents elsewhere | Pinned versions pushed to the vendor’s skill API, never “latest” |

A repository’s own `.agents/skills/` is a project source. For a repository your organization does not trust, such as a fork or an outside contribution, the mount hides those folders from the agent until a person allows them. A harness may not load a skill outside its lock, write to the skill folders or run a script that is not part of the locked version.

**Where a skill is placed.** Skills your organization wrote go where a harness treats them as your organization’s own; imported skills go in an extra skills folder that no harness treats as yours or the repository’s, and commands that a skill would run when it loads are turned off for every skill not reviewed for them. Names are compared after Unicode normalization, case folding and look-alike letters, across the lock and the repository’s own skill folders; a collision needs an alias before the session starts.

**One skill per job.** Two active skills for the same job make an agent follow one and drop the other’s rules, so every skill carries a **job** (a short label from your organization’s list, in its `metadata`), and a lock refuses two active skills with the same job unless one declares that it `extends` the other; then the extension comes only with its base, and its rules win where they differ. The compile step shows both skills’ load rates and lift, so the owner keeps the better one.

**The skill lock.** At session start the host resolves the session’s skill set into a lock (each skill, its name, origin, digest and activation) and writes it into the [session](https://frazer.ai/docs/sessions). The lock does not change while the session runs: a newer allowed version reaches a running session only when someone refreshes it, and the session’s timeline says so. Long-lived agents pick it up at their next wake.

```sh
frazer skills locks get s-c315
frazer skills locks refresh s-c315
```

## Which skills each session used

| Event | Fields |
| --- | --- |
| `skill_listed` | Once per session: the catalog offered, the ranks when routed, the tokens per harness |
| `skill_loaded` | The skill, its digest, the trigger (`model`, `person`, `plan_item`, `nested`), the turn, the tokens |
| `skill_file_read`, `skill_script_run` | A file it read; a script it ran, with exit code, duration and egress |
| `skill_requested_missing` | A name the agent or a person asked for that is not in the lock: a gap signal |

The Frazer harness reports these exactly. For other harnesses the adapter maps each harness’s own signals; for harnesses that report nothing, the mount’s access log does (an opened `SKILL.md` read to the end is a load), labeled inferred; a vendor’s hosted agent is labeled “reported by the vendor”. Each event names the digest from the lock, so every number is exact per version.

Skill-use events hold names, digests, timings and counts, never transcript text, and they are your organization’s data. A skill’s authors see aggregate use across organizations only where those organizations opt in, with at least 5 organizations behind any number and no repository names.

## Analytics: use, cost and outcomes

| Measure | What it means |
| --- | --- |
| Offered, loaded, load rate | Sessions whose catalog listed the skill; sessions that loaded it; the ratio, by trigger |
| Missed | Sessions in the skill’s scope that did not load it |
| Follow-through | Loaded sessions that then read one of its files or ran one of its scripts |
| Cost | Tokens it adds to every session, tokens per load, dollars per load at list prices |
| Outcomes | Of the work done in sessions that loaded it: merged and kept at 14 days, follow-up fixes within 14 and 90 days, reverts, Frazer Reviewer findings in its scope, incidents linked back, time to done |
| Lift | One number per method, never mixed: the **offer effect** from field trials that randomize which sessions are offered the skill; **paired eval lift** from evals; **association** between loading and outcomes, labeled and never called an effect |
| Reliability, staleness | Script failures and loads abandoned within a turn; references to paths, symbols or commands that no longer exist |

Views go per skill (versions side by side), per set, squad and agent, per harness and model, and per repository. A **never loaded** list (offered in at least 30 sessions over 30 days and never loaded) proposes `name-only` or retirement.

```sh
frazer skills uses list --skill retry-budget --since 14d --by squad
frazer skills get ledger-entry@1.4.2 --outcomes --evals
```

## Evals: does it help, and is it still safe

-   **Formats.** The open files run unchanged: `evals/evals.json` (prompts, expected output, input files, assertions) and trigger query files. You learn nothing new to write a first eval.
-   **Trigger evals.** About 20 queries, half that should load the skill and half near misses that should not, 3 runs each, split 60/40 so the best description is chosen on held-out queries. They run per harness your organization uses, and a field set adds real tasks from your own sessions.
-   **Output evals.** With and without the skill, or old and new; assertions graded by scripts first, then by a judge of another model family that does not know which arm it reads; pass^k beside the pass rate; cost and time deltas.
-   **Safety suite.** With and without the skill; a regression beyond noise fails the check.
-   **Replays and field trials.** Heavily used skills are tested by resuming recorded tasks from the checkpoint before the skill would act. After a merge, a candidate is offered to 5 %, then 25 %, then all eligible sessions, at random per session, with guard metrics (kept rate, follow-up fixes, cost per session, script failures, safety flags) and automatic rollback. A trial lasts until it can detect what it guards against, and says by when.
-   **Gates on a skill pull request** (defaults your policy may raise): the trigger pass rate no more than 5 points below the current version, the output pass rate within 3 points, no safety regression, the added tokens within the set’s budget, then the field trial before `stable`.

```sh
frazer skills evals run retry-budget --kind trigger --baseline previous
```

## Suggestions: adjust or improve a skill

The [improvement step](https://frazer.ai/docs/for-agents/what-agents-get), on by default, drafts suggestions as pull requests on the skill’s repository, each with its evidence, the effect it predicts and how it will be checked.

| Kind | Opened by | Change |
| --- | --- | --- |
| **Describe** | Missed loads in its scope, or loads abandoned in one turn | A new description or a boundary sentence |
| **Shorten**, **Split**, **Merge** | A body over 500 lines; file reads that cluster into parts; two skills loaded together in 80 % of sessions | Parts moved to references; two skills from one; one skill from two |
| **Retire** | Never loaded in 90 days while offered, or an offer effect at or below zero | `name-only`, then removal from sets |
| **Change form** | A rule that must always hold written as prose; a skill loaded in nearly every session; guidance agents skip | A hook or a check, a line in the instructions, or the reverse |
| **Fix a reference**, **Upgrade** | A path, symbol, command or link that no longer exists; a newer upstream version with better evals | The fix; a pull request on the mirror |
| **Security** | A new scanner finding, a referenced owner deleted or transferred, an upstream yank | A hold at once, then the fix |
| **Harness variant** | It works in one harness and not another | A note per harness |

Who seals a suggestion scales with its reach. **Tightening edits merge without a person** on skills whose reach is one project or one repository, under the improvement policy with a canary and rollback, but only edits that cannot widen what an agent does, which a deterministic diff test proves before any probe runs: a narrower description that passes its should-load and should-not-load probes; removed prose that holds no rule (no _must_, _never_, _always_, _do not_, _only_, no check step, stop condition, warning or guard; a sentence the test cannot classify counts as a rule); a fixed reference to content already allowed in the same repository; a split whose parts, joined, equal the original; and retiring a skill never loaded in 90 days that nothing requires. No edit in the class adds a file, a script, a tool, a host or a frontmatter field other than `description`, and a skill gets at most one such edit a week. Edits to organization-wide skills or locked handbook layers are sealed by people. New skills, broader descriptions, scripts, tools, hosts and outside references always go to the repository’s owners. A rejected suggestion is not proposed again without new evidence.

```sh
frazer skills suggestions get sug-4101
frazer skills suggestions apply sug-4101
```

## Gaps: where agents struggled with no skill

Frazer finds gaps in the session records: people’s corrections and rephrased requests, tool errors, failed checks, loop turns, time to done against the median of its class, reverted layers, follow-up fixes and `skill_requested_missing`. Sessions cluster by task signature (paths, tools, the plan item’s type, error kinds), and a cluster becomes a **gap** when it is big enough (at least 20 sessions in 14 days, by default), its friction is at least twice its class’s, and no loaded skill helped.

A gap shows its size (sessions a week, minutes and dollars of friction), the sessions behind it, and remedies ranked by expected value: improve a skill that was in the lock but not loaded; **draft a new skill** from what the sessions that merged and kept did differently, holding only what is outside a model’s own knowledge (commands, conventions, facts about your systems) and citing its sessions; fix the tool (an unclear error, a missing flag); or add a check or a hook. A drafted skill is tested on held-out tasks from the cluster, never on the sessions that found it, passes the safety suite and waits for the owners. When a fix lands, the gap’s sessions are compared before and after, and the gap closes on that evidence.

```sh
frazer skills gaps get sgap-0412
frazer skills gaps draft sgap-0412
```

## Skill repositories on Frazer Hub

A Hub repository of kind `skill` holds skills in the open format. Its page lists the skills and their signed versions, checks, compatibility per harness, how many distinct principals loaded each this week (shown at 50 or more), how many organizations allowed a version, and lift with how it was measured. **Install** imports a skill into your registry under your policy (`frazer skills import hub:pellwyn/team-skills/go-errors@2.3.0`); **fork** makes your own copy, with upstream updates as pull requests. Any agent can download the same repository, from signed releases: as a plugin marketplace for the harnesses that read one, as a skills server over MCP, or as a git export.

## Prices

The registry, sync, skill sets, locks, use tracking, the public skill index and the detection of suggestions and gaps cost nothing. Private skill repositories bill as Fir storage. Evals, field trials and replays bill as usage, with the estimate first. Paid skill packs cost the publisher’s price.

## Reference

### CLI

| Command | What it does |
| --- | --- |
| `frazer skills list` | List the skills in your organization's registry, by source, skill set or the agents that use them. |
| `frazer skills get` | Show a skill or one version, with its checks, attestation, use, outcomes and evals. |
| `frazer skills import` | Import a public skill or a Hub skill repository's skill, pinned to a commit, as a pull request on your mirror repository that runs the import checks. |
| `frazer skills allow` | Allow a skill version for your organization, for people only; hold, block and yank complete the set. |
| `frazer skills sources create` | Connect a skill repository, so every merge builds signed skill versions. |
| `frazer skills sets update` | Change a skill set (entries, pins or channels, activation modes); with --compile, print the catalog each harness would list. |
| `frazer skills locks get` | Show the skill lock a session runs with; refresh moves a running session to newer allowed versions. |
| `frazer skills uses list` | Which sessions loaded a skill, how, and what came of the work, grouped by squad, agent, harness or repository. |
| `frazer skills evals run` | Run a skill's trigger, output or safety evals against a baseline, across your harnesses and models. |
| `frazer skills suggestions list` | Suggestions to improve a skill, each with its evidence; apply opens the pull request. |
| `frazer skills gaps list` | Gaps where agents struggled with no helpful skill; draft writes a candidate skill from the sessions that went well. |
| `frazer skills policy get` | Your organization's skills policy, the narrow rule's state included; update changes it. |
| `frazer skills decisions list` | Every allow, hold, block and yank, with the rule or person behind it and the checks it relied on. |

All of them: [CLI reference](https://frazer.ai/docs/cli).

### MCP tools

| Tool | What it does |
| --- | --- |
| `skills_list` | List the skills in the registry and the skill sets. |
| `skills_get` | Read a skill version, its checks and its use. |
| `skills_search` | Search the registry and the public skill index by task. |
| `skills_uses` | Read which sessions used a skill and what came of them. |
| `skills_import` | Open an import as a pull request on the mirror repository. Writes become a plan that waits for approval. |
| `skills_suggest` | Open a suggestion for a skill, with its evidence. Writes become a plan that waits for approval. |

All of them: [MCP tools reference](https://frazer.ai/docs/mcp).

### Events

| Event type | When it is sent |
| --- | --- |
| `skills.version.allowed` | A skill version was allowed; created, held, blocked and yanked are sent too. |
| `skills.import.decided` | An import was allowed or refused. |
| `skills.suggestion.opened` | A suggestion to change a skill was opened as a pull request. |
| `skills.gap.opened` | A gap was found where agents struggled with no helpful skill. |
| `skills.lock.refreshed` | A running session moved to a newer skill lock. |

All of them: [Events reference](https://frazer.ai/docs/webhooks).

> **For agents:** Use the skills in your session’s lock; `frazer skills locks get <session>` lists them. Load a skill a plan item names before you start that item. Never copy a skill’s files into a repository or write to a skill folder: propose changes as pull requests. To bring in a public skill, open an import (`skills_import`); a person allows it.

## Related

-   [Harnesses](https://frazer.ai/docs/agents/harnesses): profiles carry skill sets
-   [Sessions](https://frazer.ai/docs/sessions): the skill lock and skill-use events live in the session
-   [Frazer Agents](https://frazer.ai/docs/agents): agent revisions pin their skills
-   [What agents get](https://frazer.ai/docs/for-agents/what-agents-get): the improvement step that drafts suggestions

## Pages in Frazer Agents

- [Overview](https://frazer.ai/docs/agents.md)
- [Harnesses](https://frazer.ai/docs/agents/harnesses.md)
- [Frazer Skills](https://frazer.ai/docs/agents/skills.md) (this page)
- [Frazer Browsers](https://frazer.ai/docs/agents/browsers.md)