Name: custom-agents
Rating: 54.400000000000006 (1 reviews)
Author: github

Blog Docs Log in Get started

custom-agents

Define and validate GitHub custom agent files, prompts, and examples.

Quality

61%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Critical

Do not install without reviewing

Fix and improve this skill with Tessl

tessl review fix ./.github/skills/custom-agents/SKILL.md

Quality

Content

65%

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 paths, schemas, and copy-paste examples, but it is a verbose monolithic file with redundant sections and no validation-checkpointed workflow or progressive disclosure to bundled references.

Suggestions

Split the large reference into bundled files (e.g. references/tool-aliases.md, references/field-schema.md, references/usage-patterns.md) and keep SKILL.md a concise overview with one-level-deep links; legacy tool names are currently explained three times.

Trim generic advice Claude already knows (the 'Best Practices' and 'Troubleshooting' bullets) and the redundant 'Common Patterns' YAML stubs that duplicate the Usage Patterns examples.

Add a brief sequenced workflow with a validation checkpoint for creating an agent file (1. choose scope/location, 2. write frontmatter per schema, 3. validate YAML and tool names, 4. test in a workflow) instead of topical reference sections only.

Dimension	Reasoning	Score
Conciseness	The core reference (file locations, schema, tool aliases) is efficient, but ~580 lines repeat content (legacy tool names appear in the schema, field descriptions, and examples) and include generic advice Claude already knows ('Make instructions more explicit and specific', 'Provide concrete examples').	2 / 3
Actionability	It provides specific file paths, a complete YAML frontmatter schema, exact tool alias and legacy name lists, glob patterns, and full copy-paste-ready example agent files for each usage pattern, so the guidance is fully executable.	3 / 3
Workflow Clarity	Content is organized by topic (locations → format → fields → patterns) giving an implicit sequence, but there is no explicit multi-step creation workflow with validation checkpoints, and the 'Best Practices' steps are generic rather than a sequenced process.	2 / 3
Progressive Disclosure	Sections are well-organized with headings, but the skill is a single ~580-line monolithic file with no bundled reference files; content that could be split (full tool reference, usage-pattern examples, common patterns) is inline rather than one-level-deep linked.	2 / 3
	Total	9 / 12 Passed

Description

57%

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, specific niche and a couple of concrete actions, but lacks an explicit 'Use when...' trigger and broader natural keyword coverage. It is distinguishable but only partially complete.

Suggestions

Add an explicit 'Use when...' trigger clause, e.g. 'Use when creating or editing GitHub Copilot custom agent files (.github/agents/*.md, AGENTS.md), .instructions.md files, or agentic workflow configurations.'

Broaden trigger terms to concrete paths and filenames users actually mention: AGENTS.md, copilot-instructions.md, .github/agents/, *.instructions.md, applyTo.

Expand beyond 'define and validate' with more concrete actions such as 'configure tool access, scope instructions with applyTo, and integrate agents into gh-aw workflows'.

Dimension	Reasoning	Score
Specificity	Names the domain ('GitHub custom agent files, prompts, and examples') and two concrete actions ('Define and validate'), but stops at two verbs rather than listing multiple specific actions like the score-3 anchor (extract/fill/merge).	2 / 3
Completeness	It answers 'what' (define and validate custom agent files) but provides no 'Use when...' clause or equivalent explicit trigger guidance, which the guidelines cap at 2.	2 / 3
Trigger Term Quality	'GitHub custom agent files, prompts, and examples' surfaces some natural terms a user might say, but omits common concrete variations users actually mention (AGENTS.md, copilot-instructions.md, .github/agents/, .instructions.md).	2 / 3
Distinctiveness Conflict Risk	'GitHub custom agent files, prompts, and examples' carves a clear niche (the GitHub Copilot custom-agent file format) that is unlikely to trigger for unrelated skills.	3 / 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
skill_md_line_count	SKILL.md is long (592 lines); consider splitting into references/ and linking	Warning

	Total	15 / 16 Passed

Repository: github/gh-aw
Path: .github/skills/custom-agents/SKILL.md
Commit: 98bac81

Reviewed: 4 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.