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%

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

The body is highly actionable with concrete commands, templates, and a well-sequenced workflow backed by validation checkpoints and recovery loops. Its main weakness is structure: a 310-line monolith with repeated scope statements and inline reference-style material that would benefit from being split into bundle files.

Suggestions

Move the T1–T9 templates into a references/ file (e.g. templates.md) and link to it from a short Template Selection Guide, reducing SKILL.md length and repetition.

De-duplicate the 'issues and discussions only / no PR replies' scope statement, stating it once in the Scan section and referencing it elsewhere.

Extract the audit-entry format and Bad Post Recovery procedure into a references/ file so the main workflow stays a lean overview.

Dimension	Reasoning	Score
Conciseness	Mostly efficient and actionable, but the ~310-line body repeats scope statements ('issues and discussions only' appears at lines 42, 51, 327) and inlines the full T1–T9 template catalog, which could be tightened or split out.	2 / 3
Actionability	Provides fully executable, copy-paste-ready guidance: concrete `gh issue list` / `gh api` / GraphQL mutation commands, an exact review-table format, ready-to-use T1–T9 templates with placeholders, and a complete audit-entry example.	3 / 3
Workflow Clarity	Clear seven-step sequence (Scan → Classify → Draft → Present → Human Action → Post → Audit) with explicit validation checkpoints (Thread-Read Verification with abort-on-mismatch), confidence escalation rules, a 'banana' safe word, and a Bad Post Recovery feedback loop for the destructive post action.	3 / 3
Progressive Disclosure	No bundle files exist and the skill is monolithic — templates, audit format, and rollback procedures that could live in separate reference files are all inlined in SKILL.md, with only runtime paths (`.squad/comms/...`) referenced rather than skill-local files.	2 / 3
	Total	10 / 12 Passed

Description

60%

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 clearly states what the skill does with three concrete actions, but it omits an explicit 'Use when' trigger clause and relies on domain jargon ('PAO') rather than natural user language. Completeness and trigger quality are the main weaknesses.

Suggestions

Add an explicit 'Use when...' clause with natural triggers, e.g. 'Use when managing community responses on GitHub issues and discussions, or when the user asks to check or reply to community threads.'

Replace or supplement the internal term 'PAO' with natural language a user would actually say (e.g. 'community responses', 'GitHub issues and discussions').

Include common trigger variations like 'forums', 'discussions', or 'community threads' to improve trigger-term coverage.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — 'scanning, drafting, and presenting community responses' — plus the 'human review gate' constraint, matching the anchor for three distinct specific actions.	3 / 3
Completeness	Answers 'what' (scan/draft/present community responses) but lacks any 'Use when...' or equivalent explicit trigger clause, so 'when' is only implied — capping completeness at 2 per the rubric guideline.	2 / 3
Trigger Term Quality	Contains some relevant keywords ('community responses', 'scanning', 'drafting') but misses common natural variations a user would say ('forums', 'GitHub issues', 'discussions') and omits the actual invocation phrase ('check community').	2 / 3
Distinctiveness Conflict Risk	The 'PAO workflow' framing and 'human review gate' give it a niche, but 'community responses' is broad enough to overlap with other comms/response skills and the trigger terms are not strongly distinctive.	2 / 3
	Total	9 / 12 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: e23dd92

Reviewed: 1 day 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.