Content
75%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A well-structured, actionable skill body: the declarative fast path is fully specified, steps are clearly sequenced, and validation exists as a checklist. Weaknesses are incremental — a missing error-recovery loop after validation, a couple of incomplete code snippets in the extension path, and advanced-path content inlined that could live in reference files.
Suggestions
Add a feedback loop to Step 8: after the validation checklist, instruct what to do on failure (e.g., 'If frontmatter YAML is invalid, fix the syntax and re-run the checklist before proceeding') so validation is a checkpoint, not a one-shot list.
Complete the tool-calling snippet in Step 5 by showing the import/source of `chatUtils` (e.g., the `@vscode/chat-extension-utils` import) so the code is copy-paste runnable.
Move the extension-based participant (Step 5) and GitHub App (Step 6) details into reference files (e.g., references/extension-based.md, references/github-app.md) and keep one-line pointers in SKILL.md, keeping the main file lean for the common declarative path.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is efficient and domain-specific (frontmatter field table, tool patterns, pitfalls table) with only minor trim opportunities — e.g., the "Handoff fields" bullets restate what the YAML example already shows, and the declarative template's placeholder sections slightly pad. This fits the anchor 'efficient; minor instances of over-explanation that could be trimmed' rather than the every-token-earns-its-place level. | 4 / 5 |
Actionability | Mostly executable guidance: file location `.github/agents/<name>.md`, a complete frontmatter table, copy-paste package.json and activate/handler TypeScript, and a concrete eval path (`eng/harness-evaluation/agents/<agent-id>/eval.yaml`). Minor gaps keep it below fully-executable: the tool-calling snippet uses `chatUtils.sendChatParticipantRequest` without showing its import, and Step 6 (GitHub App) has no code, only a documentation link. | 4 / 5 |
Workflow Clarity | Eight clearly numbered steps (choose type → create → tools → handoffs → extension → GitHub App → eval → validate) with a validation checklist in Step 8, matching 'clear sequence with most checkpoints present'. Not a 5 because there is no error-recovery feedback loop (the checklist says what to verify but not what to do on failure, e.g., invalid frontmatter YAML → fix and re-check). | 4 / 5 |
Progressive Disclosure | Good structure with clear sections, a References list of relevant external links, and no nested-reference problem (no bundle files exist; body references are one level deep). Minor gap: the two advanced paths — the ~70-line extension-based section (Step 5) and the GitHub App section — are inlined in SKILL.md when most users need only the declarative path, so splitting them into reference files would match the anchor's 'content appropriately split' ideal. | 4 / 5 |
Total | 16 / 20 Passed |