# Vault-Hosted Skills

ContextNest lets a vault host reusable **skills** — governed procedures an agent runs when a matching situation comes up. A skill is not a separate kind of file or a special CLI command: it is an ordinary node with `type: skill`, whose frontmatter declares when it fires, what it takes in, what tools it needs, and what it must not do. Because the skill lives in the vault, it is versioned, reviewable, and stays authoritative across every agent that reads the vault.

## A skill is a node type

Skills are created the same way as any other document — with `ctx add` — by asking for the `skill` type and giving it a trigger:

```bash
ctx add skills/summarize-call --type skill \
  --trigger "User pastes a call transcript or asks to summarize a client call"
```

There is **no** separate `ctx skill` command group; `skill` is a value of `--type`, alongside `document`, `snippet`, `agent`, `tool`, and the other node types. See [Node Types](https://nest.promptowl.ai/d/promptowl-documents/protocol/concepts/node-types).

`ctx add --type skill` scaffolds the node with the skill frontmatter block and a step-oriented body template, then publishes version 1 like any other document.

## Skill node frontmatter

A skill node carries a structured `skill:` block in its frontmatter in addition to the usual document fields. See [Frontmatter](https://nest.promptowl.ai/d/promptowl-documents/protocol/concepts/frontmatter) for the shared model.

| Field (under `skill:`) | Required | Purpose |
| --- | --- | --- |
| `trigger` | **Yes** | When the skill should fire. The skill schema treats `trigger` as required — set it with `--trigger`. |
| `inputs` | No | Typed inputs the skill expects (defaults to an empty list). |
| `tools_required` | No | Tools the harness must make available for the skill to run. |
| `guard_rails` | No | Constraints the agent must respect while executing the skill. |
| `output_format` | No | Shape of the skill's output (defaults to `markdown`). |

### Scaffolded skill node

This is the shape `ctx add --type skill` writes — the skill metadata is nested under a `skill:` key, and the body is a steps-and-output template:

```yaml
---
title: Summarize a Client Call
type: skill
skill:
  trigger: "User pastes a call transcript or asks to summarize a client call"
  inputs:
    - name: transcript
      type: string
      description: "Raw transcript text of the call"
    - name: client
      type: string
      description: "Client name or account alias"
  tools_required:
    - context_query
    - context_publish
  output_format: markdown
  guard_rails:
    - "Never send the summary to any external service"
    - "Write only to the client's account node"
status: published
---

# Summarize a Client Call

## Steps

1. Read the client's existing account node from the vault.
2. Distill the transcript into decisions, next actions, and open questions.
3. Publish the summary back to the account node.

## Expected Output

A markdown recap: decisions, next actions, and open questions.
```

Edit the scaffolded fields with `ctx update` (or your editor, then `ctx publish`); every change is versioned like any other document.

## How agents use a skill

Because a skill is a published node, an agent gets it the same way it gets any other context — by querying the vault. An agent connected over the [MCP server](https://nest.promptowl.ai/d/promptowl-documents/protocol/mcp-server) retrieves published skill nodes alongside the rest of the vault; the `trigger` tells the agent when the procedure applies, and `guard_rails` / `tools_required` bound how it runs. Keeping the skill in the vault means every agent reads the same, current version rather than a copy that can drift.

## Roadmap: installing skills into a harness

A dedicated **install** path — copying or linking a skill into a specific agent harness (Claude Code, Cursor, Codex, or a raw harness) with a choice between a live **loader** (the harness fetches the current steps from the vault at runtime) and an offline **snapshot** (a copy written into the harness that flags when it has drifted) — is a planned direction, not a shipped command. In the current build (`ctx` v2.2.0) there is no `ctx skill install` verb and no `context_skill_install` MCP tool; skills are authored and retrieved as nodes as described above. A **bootstrap** skill handed automatically to every agent that opens a vault is part of the same planned direction.

## Related

- [Frontmatter](https://nest.promptowl.ai/d/promptowl-documents/protocol/concepts/frontmatter) — shared frontmatter model
- [Node Types](https://nest.promptowl.ai/d/promptowl-documents/protocol/concepts/node-types) — the `type: skill` node
- [MCP Server](https://nest.promptowl.ai/d/promptowl-documents/protocol/mcp-server) — how agents retrieve vault nodes