Secrets and skills

Skills add instructions to a plugin. Secret providers resolve credentials for supported execution paths. They have different runtime requirements and can coexist with other capabilities in one package.

Bundle a skill

Place each skill at skills/<skill-key>/SKILL.md and reference that path from a skill capability’s resourcePath. Include YAML frontmatter with a non-empty description.

A complete minimal skill package has two files:

apiVersion: 1
kind: plugin
name: orders-review
packageName: orders-review
version: 1.0.0
displayName: Orders review
description: Guidance for reviewing order evidence
author:
  name: Operations team
capabilities:
  - kind: skill
    key: orders-review
    displayName: Orders review
    description: Review delivery changes against source evidence
    resourcePath: skills/orders-review/SKILL.md

---
name: Orders review
description: Review delivery changes using accessible order and receipt evidence
---

Ask which project and time window to inspect.
Read accessible orders and receipts and compare their delivery dates.
Show the records supporting each discrepancy.
If evidence is missing, report the gap rather than inventing a date.
Review any proposed changes with the user before executing them.

A skill-only package can consist of the manifest and instruction file. If it also contains runtime code, include the runtime package and declarations described in Package format.

Implement a secret provider

Define a secret_provider capability, protected installation settings and a secret_resolution contract. Implement the runtime secret-provider declaration with create(config) returning the provider interface.

Scope the names and locations it may resolve. Report a missing or disallowed secret as an error. Do not fall back to arbitrary host environment values or log resolved credentials. See Environment Variables for the internal provider’s behavior.

Verify

For skills, verify frontmatter, referenced resource paths and that the installed instructions match the reviewed version. Skills supply guidance; they do not grant access to records or execute connector code themselves.

For secret providers, test allowed, missing and forbidden references. Then test the intended connector operation without displaying the secret. Validate the deployed resolver path; package tests alone do not prove the provider is registered in the hosted runtime.

FAQ

Does a skill need a runtime entrypoint?

A resource-based skill is loaded from its instruction file. Runtime entrypoints are required for executable capabilities according to their declared interfaces.

Can I use another plugin manifest format?

The custom authoring flow requires the canonical craven.plugin.yaml format. It rejects .claude-plugin/plugin.json and a root manifest.json.