Agent skills — turn policy into a tested workflow

Agent skills are versioned workflow packages: a SKILL.md file plus optional scripts, references, and templates. Use them for procedures that should load only when relevant, such as threat modeling, design review, or release evidence. For Scorecard Q6, the strongest evidence is a focused skill owned by the responsible team, tested on real tasks, and improved from failures.

Scorecard Q6: How do you encode organizational policies?

Max-score evidence: a repository-owned skill with a named owner, acceptance cases, bounded tools, and review history.

Choose one portable source of truth

The format is portable, but discovery paths differ. Prefer .agents/skills/<name>/SKILL.md when your current tool set supports it; otherwise keep one canonical directory and add small tool-specific copies or symlinks only after testing them.

Tool	Documented project location	How to verify discovery
Claude Code	.claude/skills/<name>/SKILL.md	Ask a matching question or invoke /<name>
Cursor	.agents/skills/<name>/SKILL.md or .cursor/skills/<name>/SKILL.md	Open Customize → Skills, then run a matching prompt
Codex	.agents/skills/<name>/SKILL.md	Run /skills or mention $<name>

Sources: Claude Code skills, Cursor skills, and Codex skills.

Author the smallest useful skill

Create .agents/skills/security-review/SKILL.md:

---
name: security-review
description: Review authentication, authorization, secrets, and untrusted input before a change is approved. Do not edit files.
---

1. Read the accepted spec and changed files.
2. Check trust boundaries, authorization, secret handling, and input validation.
3. Cite each finding with a file and line.
4. Return PASS or BLOCKED. Do not modify code.

Add references/checklist.md only when the checklist would distract from the main procedure. Add a script only when deterministic execution is needed. A skill describes behavior; it does not replace client permissions, hooks, CI, or human approval.

Validate the contract

Run three cases and save the results with the skill or its tests:

1. A positive trigger: the agent should load the skill and find a seeded issue.
2. A negative trigger: an unrelated documentation task should not load it.
3. A boundary case: the skill should refuse to edit files and should report missing evidence.

Copy-paste prompt — positive case:

Review the authentication change against our security policy. State which skill you loaded, do not edit files, and return PASS or BLOCKED with file-and-line evidence.

Copy-paste prompt — negative case:

Correct spelling in README.md. List any skills you loaded and explain why each was relevant.

Copy-paste prompt — improve from failure:

Compare this skill’s expected result with the latest run. Identify the smallest instruction, reference, or deterministic check that prevents the observed miss. Propose the patch; do not broaden the skill’s scope.

Failure pattern: installed is not governed

A marketplace count is not proof of capability. Third-party skills can contain stale commands, broad tool grants, or instructions that conflict with repository policy. Review the source before trusting it, pin or record its origin, test it in a disposable repository, and remove it when no recurring task justifies the context or access.

Do not encode hard controls only in prose. If a rule must always block production access, secret exposure, or protected-path edits, implement it in permissions, hooks, and CI, then use the skill to explain the procedure and evidence.

Completion evidence

• One canonical, version-controlled skill exists for a recurring policy workflow.
• Its description states when it should and should not trigger.
• Positive, negative, and boundary cases pass in every supported tool.
• Tool access is no broader than the procedure needs.
• A named owner reviews failures and vendor-format changes.

Continue the policy loop

Build custom skills Package a reviewed procedure with references, scripts, and tests.

Q10 · Evidence-based MCP set Grant external data access only when a recurring workflow requires it.

Governance and autonomy Separate advisory instructions from enforced action boundaries.