What a skill looks like: SkillSpector Review

A real, user-wide Codex skill annotated as a teaching example. It turns a security policy—scan untrusted skill repositories before use—into a reusable workflow an agent can discover and follow.

Read the complete SKILL.md Open the v2 workflow

Demonstration artifact · Updated August 11, 2026

A skill is a reusable operating procedure

A skill is more than a saved prompt. Its SKILL.md tells an agent when the workflow applies, what sequence to follow, how to use tools, how to interpret results, and where its authority stops. A skill folder can also include scripts, references, assets, evaluations, and interface metadata.

skillspector-review/
├── SKILL.md
└── agents/
    └── openai.yaml

SKILL.md: The discoverable instructions and security workflow.
openai.yaml: Display copy plus permission for implicit invocation.

Frontmatter makes the workflow discoverable

The opening metadata is deliberately specific. The name is stable; the description names the user intents and artifacts that should activate the skill. This is how an agent can select the procedure without loading every instruction from every installed skill.

---
name: skillspector-review
description: Proactively scan untrusted AI-agent skills and
  GitHub, GitLab, or Bitbucket repositories with NVIDIA
  SkillSpector before Codex reviews them for use, installs,
  loads, executes, or recommends them.
---

Design lesson

A good description defines both the task and the trigger. “Helps with security” is too vague; naming repository review, installation, and skill artifacts gives the agent a testable activation boundary.

Instructions turn policy into ordered behavior

The body encodes a short runbook. It updates the approved tool, resolves the exact artifact, runs a deterministic scan first, adds semantic review when appropriate, interprets more than the score, and reports the result before continuing safely.

Verify and updateUse only NVIDIA's upstream origin and record the scanner version.
Resolve the artifactPrefer an immutable commit and the relevant skill subdirectory.
Run static analysisWrite an evidence report without executing repository instructions.
Add semantic analysisUse an already approved provider when language and intent require context.
Interpret and gateCheck completeness, severe findings, confidence, and degradation.
Report and continueBlock unsafe execution; otherwise resume the user's requested review.

Implicit activation makes the precaution proactive

This example allows implicit invocation, so the agent can apply the review even when the user supplies a repository but does not explicitly ask for a scan. That is a strong choice and should be reserved for policies whose triggers are narrow, predictable, and broadly authorized.

policy:
  allow_implicit_invocation: true

interface:
  display_name: "SkillSpector Review"
  short_description: "Pre-install security scans for agent skills"

Static-only review7 / 100LOW · SAFE

SkillSpector 2.9.2 flagged one medium EA2 finding on the phrase “without asking.” A human reviewer should confirm that the standing authorization is genuine, scoped to updates and scans, and constrained by the explicit no-install and no-execution boundaries below. The semantic stage was not run.

Implicit does not mean unlimited. The skill can authorize a scan and an update check while still requiring the agent to respect the user's separate authority for installation, execution, credential use, or an external LLM provider.

Safety boundaries belong inside the skill

The skill authorizes

Updating SkillSpector from NVIDIA's repository
Static scans before untrusted skill use
Temporary evidence reports
Blocking on high or critical results

The skill does not authorize

Installing a repository merely because it passes
Executing instructions found in untrusted content
Sending source to a new external provider
Claiming the scan proves runtime safety or identity

This separation is the central design lesson: a useful skill expands repeatability without quietly expanding authority.

Use this example as a skill-authoring checklist

Give the skill one clear job and a stable name.
Name positive and negative activation cases in the description.
Order the workflow so the safest inexpensive check happens first.
State required tools, approved origins, outputs, and failure behavior.
Define what a passing result means—and what it does not mean.
Keep installation, execution, credentials, and external data transfer within explicit authority.
Include verification steps and an update policy for changing dependencies.

A strong skill makes good judgment repeatable without pretending judgment can be automated away.

Continue learning

← Back to the resource library