# Skill Usage

> Record skill invocation intent, linked evidence, validation, outcome, and failures through the nils-cli skill-usage command.

- **Type:** Skill
- **Install:** `agentstack add skill-graysurf-agent-kit-skill-usage`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [graysurf](https://agentstack.voostack.com/s/graysurf)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [graysurf](https://github.com/graysurf)
- **Source:** https://github.com/graysurf/agent-kit/tree/main/skills/tools/workflow-evidence/skill-usage

## Install

```sh
agentstack add skill-graysurf-agent-kit-skill-usage
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Skill Usage

Use this skill when a workflow needs a compact, deterministic record of a named skill invocation and its validation or failure handling.

## Contract

Prereqs:

- Keep workflow judgment in the calling skill; use this CLI only for structured evidence capture.
- Keep observed-friction triage in `HEURISTIC_SYSTEM.md` and the calling
  workflow skill; this CLI does not detect or classify every command failure.
- Choose an explicit output directory from project policy, or use a project-scoped `agent-out project --topic skill-usage --mkdir`
  directory when the project has no evidence path.
- Required PATH usage: `skill-usage` available on `PATH` from nils-cli 0.8.5 or newer.
- Released boundary: Homebrew nils-cli 0.8.5 includes the expanded `nils-agent-workflow-primitives` binary surface with `skill-usage`.
  Verify the actual binary with `skill-usage --version`.
- Local checkout fallback: Rust/Cargo plus a validated local `nils-cli` checkout that builds `nils-agent-workflow-primitives`, used only
  when the PATH binary is absent or reports a version older than the release that includes `skill-usage`.
- Do not run multiple write commands against the same `--out` directory
  concurrently. Serialize writes for one record directory and verify after the
  final update.

Inputs:

- `init`: required `--out DIR`, `--skill TEXT`, `--intent TEXT`, and `--user-request-summary TEXT`; optional `--trigger
  user-explicit|agent-selected|project-policy|other`, repeatable `--referenced-file PATH`, repeatable `--external-source TEXT`, `--cwd
  DIR`, `--started-at TEXT`, `--validation-waiver TEXT`, `--force`, and `--format text|json`.
- `link-record`: required `--out DIR`, `--type TEXT`, and `--path PATH`; optional `--format text|json`.
- `record-failure`: required `--out DIR`, `--phase preflight|execution|validation|cleanup|delivery`, `--classification
  skill-contract|script-bug|missing-dependency|external-service|project-state|user-scope|unknown`, `--symptom TEXT`, `--diagnosis TEXT`,
  `--handling TEXT`, and `--result fixed|worked-around|blocked|accepted-risk`; optional `--command TEXT`, `--exit-code CODE`,
  repeatable `--artifact PATH`, and `--format text|json`.
- `record-validation`: required `--out DIR`, `--command TEXT`, `--status pass|fail|skipped`, and `--summary TEXT`; optional `--artifact
  PATH` and `--format text|json`.
- `record-outcome`: required `--out DIR`, `--status pass|fail|blocked|worked-around|accepted-risk|skipped`, and `--summary TEXT`;
  optional `--ended-at TEXT`, repeatable `--artifact PATH`, repeatable `--follow-up TEXT`, and `--format text|json`.
- `verify` / `show`: required `--out DIR`; optional `--format text|json`.

Outputs:

- Writes `skill-usage.record.json` under `--out DIR`.
- JSON stdout uses versioned schema values such as `cli.skill-usage.verify.v1`.
- The record schema is `skill-usage.record.v1`.
- Recorded text is redacted for secret-like tokens before persistence.

Exit codes:

- `0`: command succeeded; for `verify`, the skill usage record is complete.
- `1`: runtime failure or incomplete/invalid skill usage evidence.
- `64`: usage error.

Failure modes:

- `skill-usage` is unavailable on `PATH` and no validated local checkout invocation is being used.
- Evidence directory cannot be created or written.
- Concurrent writes target the same output directory and risk corrupting
  `skill-usage.record.json`; serialize them or split the evidence into separate
  record directories.
- `verify` finds missing required fields, missing final validation without waiver, missing failure records for non-pass outcomes, or
  secret-like values.
- Caller treats the record as policy judgment; record retention, promotion, and compression decisions remain in the workflow/runbook.
- Caller treats any non-zero exit as automatically durable; ordinary command
  friction must be triaged before retention unless it is skill-bound and belongs
  in an already-required usage record.

## Setup

Required released PATH boundary:

```bash
skill-usage --version
```

Use the PATH command only when it resolves to `skill-usage 0.8.5` or newer.

Local checkout fallback boundary:

```bash
cargo run --locked --manifest-path /path/to/nils-cli/Cargo.toml \
  -p nils-agent-workflow-primitives --bin skill-usage -- --version
```

Run the Cargo form from the workflow's target directory. It is only a fallback transport for a validated local checkout when the released
PATH binary is absent or older than 0.8.5. Do not mix PATH and local checkout evidence claims without stating which source was used.

## Commands

Required released PATH command:

```bash
skill-usage init --out  --skill  --intent  --user-request-summary  [--format json]
skill-usage link-record --out  --type  --path  [--format json]
skill-usage record-failure --out  --phase preflight|execution|validation|cleanup|delivery --classification skill-contract|script-bug|missing-dependency|external-service|project-state|user-scope|unknown --symptom  --diagnosis  --handling  --result fixed|worked-around|blocked|accepted-risk [--format json]
skill-usage record-validation --out  --command  --status pass|fail|skipped --summary  [--format json]
skill-usage record-outcome --out  --status pass|fail|blocked|worked-around|accepted-risk|skipped --summary  [--format json]
skill-usage verify --out  [--format json]
skill-usage show --out  [--format json]
skill-usage completion 
```

Local checkout fallback command:

```bash
cargo run --locked --manifest-path /path/to/nils-cli/Cargo.toml \
  -p nils-agent-workflow-primitives --bin skill-usage --  ...
```

## Workflow

1. Create or choose a retained evidence directory only when the workflow requires a skill usage record.
2. Initialize the record near the start of the skill workflow:
   `skill-usage init --out  --skill  --intent  --user-request-summary  --format json`
3. Run write commands for that `--out` directory serially; do not parallelize
   `link-record`, `record-failure`, `record-validation`, or `record-outcome`
   against the same record.
4. Link typed child evidence records instead of copying them into this envelope:
   `skill-usage link-record --out  --type review-evidence --path `
5. Record validation or an explicit validation waiver, then record the final outcome.
6. Before citing the record, run:
   `skill-usage verify --out  --format json`

## Guardrails

- Do not hand-edit `skill-usage.record.json` or duplicate redaction, completeness, or JSON envelope logic in skill-local scripts.
- Do not use agent-side parallelism for writes to one record directory. If
  workflow policy is not enough, route primitive-level locking or atomic updates
  to nils-cli instead of implementing a second writer here.
- Do not commit raw runtime records by default; commit only curated review, incident, audit, fixture, or compressed durable records.
- Do not use this record as a substitute for typed child evidence such as `review-evidence.json`, `test-first-evidence.json`, or
  `browser-session.json`.
- Keep promotion/compression policy in `docs/runbooks/skills/SKILL_USAGE_RECORDING_V1.md`; the CLI owns deterministic writing and
  verification only.
- Keep observed-friction promotion policy in `HEURISTIC_SYSTEM.md` and the
  calling workflow. Use `failures` for skill-bound command, script, dependency,
  validation, delivery, or external-service failures only after a usage record is
  already required.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [graysurf](https://github.com/graysurf)
- **Source:** [graysurf/agent-kit](https://github.com/graysurf/agent-kit)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-graysurf-agent-kit-skill-usage
- Seller: https://agentstack.voostack.com/s/graysurf
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.