openshell-policy-advisor

Use when an OpenShell sandbox returns policy_denied, mentions policy.local, or needs a narrow network policy proposal.

Quality

64%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./crates/openshell-supervisor-process/src/skills/policy-advisor/SKILL.md

Quality

Content

72%Weight 40%Scale 1-3

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is exceptionally lean and gives a clear, gated retry workflow for a simple skill, but its actionability is undermined by missing executable commands and a proposal payload, and its workflow would benefit from explicit step numbering and a rejection/timeout branch.

Suggestions

Add an executable example for the submit step (e.g., a curl POST with the proposal JSON body) so the guidance is copy-paste ready rather than just naming an endpoint.

Break the run-on sentence into a numbered workflow and add an explicit branch for when the wait times out or the proposal is rejected (e.g., re-submit a narrower proposal).

Clarify how {chunk_id} is obtained from the proposal submission response so the wait URL is fully resolvable.

Dimension	Reasoning	Score
Conciseness	A single dense directive with exact paths, URLs, and flags and no padding or explanation of concepts Claude already knows; every token earns its place, matching the lean-and-efficient score-3 anchor.	3 / 3
Actionability	It names concrete endpoints and parameters ('http://policy.local/v1/proposals', '/v1/proposals/{chunk_id}/wait?timeout=300', 'policy_reloaded: true') but gives no executable HTTP command, request body, or proposal format, so the core submit step is incomplete.	2 / 3
Workflow Clarity	The read -> inspect -> submit -> wait -> retry sequence is present with an approval gate, but it is delivered as one run-on sentence with no numbered steps and no error-recovery branch for the wait timing out or the proposal being rejected.	2 / 3
Progressive Disclosure	For a short single-purpose skill under 50 lines with no need for bundle files, the single heading and one clearly signaled reference ('Read /etc/openshell/skills/policy_advisor.md') are appropriately organized, meeting the simple-skills score-3 allowance.	3 / 3
	Total	10 / 12 Passed

Description

57%Weight 40%Scale 1-3

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description has an explicit, well-targeted 'Use when' trigger and a clear niche, but it is trigger-only: it lacks a crisp statement of what the skill actually does (e.g., drafting and submitting a narrow network policy proposal).

Suggestions

Lead with a concrete capability clause before the trigger, e.g., 'Drafts and submits the narrowest network policy proposal to unblock an OpenShell sandbox. Use when...'

Replace the unusual 'mentions policy.local' trigger with phrasing a user would naturally say, such as 'when an OpenShell request is blocked by policy' or 'when the user sees policy_denied'.

Name the concrete actions (read current policy, submit proposal, wait for approval, retry) so the 'what' is explicit rather than implied.

Dimension	Reasoning	Score
Specificity	It names the domain ('OpenShell sandbox', 'policy') and hints at an action ('needs a narrow network policy proposal'), but does not enumerate multiple concrete capabilities like the score-3 anchor requires.	2 / 3
Completeness	The explicit 'Use when' clause answers 'when' clearly, but the 'what does this do' is only weakly implied via 'needs a narrow network policy proposal' rather than a clear capability statement, so it does not reach the both-answered score-3 anchor.	2 / 3
Trigger Term Quality	'policy_denied' is a natural trigger a user would see, but 'mentions policy.local' is an unusual user-facing phrase and coverage of natural variations is thin, matching the 'some relevant keywords but missing common variations' anchor.	2 / 3
Distinctiveness Conflict Risk	'OpenShell sandbox returns policy_denied' and 'mentions policy.local' form a narrow, distinctive niche that is very unlikely to trigger for an unrelated skill.	3 / 3
	Total	9 / 12 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: NVIDIA/OpenShell
Path: crates/openshell-supervisor-process/src/skills/policy-advisor/SKILL.md
Commit: deced87

Reviewed: 6 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.