external-comms

PAO workflow for scanning, drafting, and presenting community responses with human review gate

Quality

68%

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 ./.squad/skills/external-comms/SKILL.md

Quality

Content

77%Weight 40%Scale 1-5

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

The skill body is highly actionable and workflow-clear, with concrete commands, templates, and robust validation/rollback loops for a public-facing batch operation. Its weaknesses are repetition that hurts conciseness and a monolithic single-file structure with no bundle references, leaving progressive disclosure underdeveloped.

Suggestions

Dedupe the repeated 'Phase 1 scope — issues/discussions only, no PR' guidance and merge the inline Thread-Read Verification steps with its dedicated section to tighten conciseness.

Move the nine response templates and the audit-entry example into referenced bundle files (e.g. references/templates.md, references/audit-entry.md) and link them from the body to improve progressive disclosure.

Consolidate the confidence auto-escalation rules with the confidence table to remove the duplicated 🔴 logic.

Dimension	Reasoning	Score
Conciseness	The body is mostly action-oriented with little concept padding, but it is long (300+ lines) with notable redundancy: 'Phase 1 scope — issues/discussions only, no PR' is stated three times, Thread-Read Verification appears both inline and as its own section, and 'keep the structure, replace placeholders' guidance is repeated.	3 / 5
Actionability	Fully executable guidance throughout: concrete copy-paste commands (`gh issue list --state open --json ...`, `gh api ... --jq`, `gh api -X DELETE ...`), an exact review-table format, an example audit entry, and nine ready-to-use response templates that cover the common response types.	5 / 5
Workflow Clarity	A clear seven-step sequence (Scan → Classify → Draft → Present → Human Action → Post → Audit) with explicit validation checkpoints (Thread-Read Verification count-mismatch abort, deleted-comment check, long-thread flag, confidence escalation), a mandatory human review gate, and a rollback/bad-post recovery feedback loop.	5 / 5
Progressive Disclosure	No bundle files exist (references/scripts/assets absent), so all content sits in one inlined file: nine templates, confidence and template-selection tables, and an audit example that arguably belong in separate files. Internal section structure is reasonable, but the one referenced path (`.squad/comms/templates/audit-entry.md`) is an external runtime path, not a navigable skill reference.	3 / 5
	Total	16 / 20 Passed

Description

58%Weight 40%Scale 1-5

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 states a clear purpose and several concrete actions but omits any 'Use when' trigger guidance and leans on internal jargon ('PAO workflow', 'human review gate') rather than natural user phrases. Distinctiveness is reasonable but completeness is capped by the missing trigger clause.

Suggestions

Append a 'Use when...' clause with natural user triggers, e.g. 'Use when the user asks to draft or reply to community issues and discussions, or says PAO, check community.'

Replace or gloss internal jargon ('PAO workflow', 'human review gate') with user-facing phrasing so the description triggers on natural requests.

Expand the action list toward comprehensive coverage (classify, draft, present, audit) to push specificity from 4 toward 5.

Dimension	Reasoning	Score
Specificity	The description names the domain ('community responses') and three concrete actions ('scanning, drafting, and presenting') plus a 'human review gate', giving several specific actions with only minor coverage gaps (classify, audit, rollback unmentioned).	4 / 5
Completeness	It clearly states the 'what' (a workflow for scanning, drafting, and presenting community responses) but has no 'Use when...' clause or equivalent explicit trigger guidance, which per the rubric caps completeness at 3.	3 / 5
Trigger Term Quality	Relevant terms appear ('community responses', 'scanning', 'drafting', 'presenting') but the natural user phrasings ('reply to issues', 'answer discussions', 'GitHub issues') are absent and 'PAO workflow' / 'human review gate' are internal jargon rather than user-said triggers.	3 / 5
Distinctiveness Conflict Risk	'community responses with human review gate' carves a specific niche that is mostly distinct from generic comms/support skills, with only minor overlap risk against a closely related community-management skill.	4 / 5
	Total	14 / 20 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: bradygaster/squad
Path: .squad/skills/external-comms/SKILL.md
Commit: a0d2563

Reviewed: about 16 hours 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.