validate-agent-files

Name: validate-agent-files
Author: JBurlison

70stars8forks

How to install validate-agent-files?

jburlison/metaprompts/validate-agent-files

$npx -y skills add JBurlison/MetaPrompts --skill validate-agent-files

Installs into the current project.

Summary

Validates AI coding assistant customization files (agents, skills, prompts, instructions) for correct format and structure. Works with GitHub Copilot, Claude Code, Codex, OpenCode, and other providers. Use when checking if agent files are properly configured, troubleshooting agen

Files · 1

View on GitHub

SKILL.md

1	# Validate Agent Files
2
3	Validates that agent, skill, prompt, and instruction files follow the correct format and structure.
4
5	## Provider Folder Reference
6
7	This skill works across multiple AI coding assistant providers:
8
9	\| Provider \| Base Folder \|
10	\|----------\|-------------\|
11	\| GitHub Copilot \| `.github/` \|
12	\| Claude Code \| `.claude/` \|
13	\| Codex \| `.codex/` \|
14	\| OpenCode \| `.config/opencode/` \|
15
16	Throughout this document, `<provider>/` represents your chosen provider's base folder.
17
18	## When to Use
19
20	- Before committing new agents, skills, prompts, or instructions
21	- When an agent isn't behaving as expected
22	- To audit existing customization files for issues
23	- After modifying any `.github` customization files
24
25	## Validation Process
26
27	### Step 1: Identify File Type
28
29	Determine the type based on location and extension:
30	- `<provider>/agents/*.md` → Agent file (user-invokable)
31	- `<provider>/agents/*.subagent.agent.md` → Sub-agent file (workflow component)
32	- `<provider>/skills/*/SKILL.md` → Skill file
33	- `<provider>/prompts/*.prompt.md` → Prompt file
34	- `<provider>/instructions/*.instructions.md` → Instruction file
35
36	### Step 2: Apply Type-Specific Validation
37
38	## Agent File Validation (`<provider>/agents/*.md`)
39
40	Required Structure:
41	```yaml
42	---
43	name: agent-name
44	description: When to use this agent (should include examples)
45	user-invokable: true # Optional, defaults to true
46	---
47
48	[System prompt body]
49	```
50
51	Supported Frontmatter Attributes:
52	- `name` (required) - Agent identifier
53	- `description` (required) - When/how to use, with examples
54	- `user-invokable` (optional) - Set to `false` for sub-agents (default: `true`)
55	- `tools` - List of allowed tools
56	- `model` - Specific model to use
57	- `handoffs` - Other agents this can delegate to
58
59	Checks:
60	1. ✓ YAML frontmatter present with `---` delimiters
61	2. ✓ `name` field exists and is non-empty
62	3. ✓ `description` field exists (recommend 50+ characters with examples)
63	4. ✓ Body content exists after frontmatter
64	5. ✓ If `tools` specified, they are valid tool names
65	6. ✓ If filename contains `.subagent.agent.md`, verify `user-invokable: false` is set
66
67	Naming Convention Checks:
68	- User-facing agents: `<name>.agent.md` or `<name>.md`
69	- Sub-agents: `<name>.subagent.agent.md` with `user-invokable: false`
70
71	Common Issues:
72	- Missing `---` delimiters
73	- Empty or minimal description
74	- No usage examples in description
75	- Body content missing or too brief
76	- Sub-agent missing `user-invokable: false`
77	- Sub-agent not using `.subagent.agent.md` naming convention
78
79	## Skill File Validation (`<provider>/skills/*/SKILL.md`)
80
81	Required Structure:
82	```yaml
83	---
84	name: skill-name
85	description: What this skill does and when to use it.
86	---
87
88	[Skill instructions body]
89	```
90
91	Supported Frontmatter Attributes:
92	- `name` (required) - Must match parent directory name, lowercase with hyphens
93	- `description` (required) - Max 1024 chars, describes function and triggers
94	- `license` (optional) - License information
95	- `compatibility` (optional) - Environment requirements
96	- `metadata` (optional) - Key-value pairs for additional info
97	- `allowed-tools` (optional) - Space-delimited pre-approved tools
98
99	Checks:
100	1. ✓ File is named `SKILL.md` inside a directory
101	2. ✓ `name` matches parent directory name exactly
102	3. ✓ `name` is lowercase, alphanumeric with hyphens only
103	4. ✓ `name` doesn't start/end with hyphen or have consecutive hyphens
104	5. ✓ `description` is 1-1024 characters
105	6. ✓ Body content provides clear instructions
106
107	Common Issues:
108	- `name` doesn't match directory name
109	- Uppercase characters in name
110	- Description too vague (should include trigger keywords)
111	- Missing instructions in body
112
113	## Prompt File Validation (`<provider>/prompts/*.prompt.md`)
114
115	Required Structure:
116	```yaml
117	---
118	mode: agent
119	description: What this prompt does
120	---
121
122	[Prompt template with {{variables}}]
123	```
124
125	Supported Frontmatter Attributes:
126	- `mode` (optional) - One of: `agent` (default), `ask`, `edit`, `generate`
127	- `tools` (optional) - Available tools for this prompt
128	- `description` (optional but recommended) - What the prompt accomplishes
129
130	Checks:
131	1. ✓ File has `.prompt.md` extension
132	2. ✓ If `mode` present, it's a valid value
133	3. ✓ Variables use `{{variableName}}` syntax
134	4. ✓ Body content exists (the prompt itself)
135
136	Common Issues:
137	- Wrong extension (`.md` instead of `.prompt.md`)
138	- Invalid `mode` value
139	- Undefined variables in template
140
141	## Instruction File Validation (`<provider>/instructions/*.instructions.md`)
142
143	Required Structure:
144	```yaml
145	---
146	applyTo: "*/.ts"
147	---
148
149	[Contextual instructions]
150	```
151
152	Supported Frontmatter Attributes:
153	- `applyTo` (re

People who liked this also viewed

6 picks

Type

validate-agent-files

70stars8forks

View on GitHub

How to install validate-agent-files?

jburlison/metaprompts/validate-agent-files

$npx -y skills add JBurlison/MetaPrompts --skill validate-agent-files

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Validate Agent Files
2
3	Validates that agent, skill, prompt, and instruction files follow the correct format and structure.
4
5	## Provider Folder Reference
6
7	This skill works across multiple AI coding assistant providers:
8
9	\| Provider \| Base Folder \|
10	\|----------\|-------------\|
11	\| GitHub Copilot \| `.github/` \|
12	\| Claude Code \| `.claude/` \|
13	\| Codex \| `.codex/` \|
14	\| OpenCode \| `.config/opencode/` \|
15
16	Throughout this document, `<provider>/` represents your chosen provider's base folder.
17
18	## When to Use
19
20	- Before committing new agents, skills, prompts, or instructions
21	- When an agent isn't behaving as expected
22	- To audit existing customization files for issues
23	- After modifying any `.github` customization files
24
25	## Validation Process
26
27	### Step 1: Identify File Type
28
29	Determine the type based on location and extension:
30	- `<provider>/agents/*.md` → Agent file (user-invokable)
31	- `<provider>/agents/*.subagent.agent.md` → Sub-agent file (workflow component)
32	- `<provider>/skills/*/SKILL.md` → Skill file
33	- `<provider>/prompts/*.prompt.md` → Prompt file
34	- `<provider>/instructions/*.instructions.md` → Instruction file
35
36	### Step 2: Apply Type-Specific Validation
37
38	## Agent File Validation (`<provider>/agents/*.md`)
39
40	Required Structure:
41	```yaml
42	---
43	name: agent-name
44	description: When to use this agent (should include examples)
45	user-invokable: true # Optional, defaults to true
46	---
47
48	[System prompt body]
49	```
50
51	Supported Frontmatter Attributes:
52	- `name` (required) - Agent identifier
53	- `description` (required) - When/how to use, with examples
54	- `user-invokable` (optional) - Set to `false` for sub-agents (default: `true`)
55	- `tools` - List of allowed tools
56	- `model` - Specific model to use
57	- `handoffs` - Other agents this can delegate to
58
59	Checks:
60	1. ✓ YAML frontmatter present with `---` delimiters
61	2. ✓ `name` field exists and is non-empty
62	3. ✓ `description` field exists (recommend 50+ characters with examples)
63	4. ✓ Body content exists after frontmatter
64	5. ✓ If `tools` specified, they are valid tool names
65	6. ✓ If filename contains `.subagent.agent.md`, verify `user-invokable: false` is set
66
67	Naming Convention Checks:
68	- User-facing agents: `<name>.agent.md` or `<name>.md`
69	- Sub-agents: `<name>.subagent.agent.md` with `user-invokable: false`
70
71	Common Issues:
72	- Missing `---` delimiters
73	- Empty or minimal description
74	- No usage examples in description
75	- Body content missing or too brief
76	- Sub-agent missing `user-invokable: false`
77	- Sub-agent not using `.subagent.agent.md` naming convention
78
79	## Skill File Validation (`<provider>/skills/*/SKILL.md`)
80
81	Required Structure:
82	```yaml
83	---
84	name: skill-name
85	description: What this skill does and when to use it.
86	---
87
88	[Skill instructions body]
89	```
90
91	Supported Frontmatter Attributes:
92	- `name` (required) - Must match parent directory name, lowercase with hyphens
93	- `description` (required) - Max 1024 chars, describes function and triggers
94	- `license` (optional) - License information
95	- `compatibility` (optional) - Environment requirements
96	- `metadata` (optional) - Key-value pairs for additional info
97	- `allowed-tools` (optional) - Space-delimited pre-approved tools
98
99	Checks:
100	1. ✓ File is named `SKILL.md` inside a directory
101	2. ✓ `name` matches parent directory name exactly
102	3. ✓ `name` is lowercase, alphanumeric with hyphens only
103	4. ✓ `name` doesn't start/end with hyphen or have consecutive hyphens
104	5. ✓ `description` is 1-1024 characters
105	6. ✓ Body content provides clear instructions
106
107	Common Issues:
108	- `name` doesn't match directory name
109	- Uppercase characters in name
110	- Description too vague (should include trigger keywords)
111	- Missing instructions in body
112
113	## Prompt File Validation (`<provider>/prompts/*.prompt.md`)
114
115	Required Structure:
116	```yaml
117	---
118	mode: agent
119	description: What this prompt does
120	---
121
122	[Prompt template with {{variables}}]
123	```
124
125	Supported Frontmatter Attributes:
126	- `mode` (optional) - One of: `agent` (default), `ask`, `edit`, `generate`
127	- `tools` (optional) - Available tools for this prompt
128	- `description` (optional but recommended) - What the prompt accomplishes
129
130	Checks:
131	1. ✓ File has `.prompt.md` extension
132	2. ✓ If `mode` present, it's a valid value
133	3. ✓ Variables use `{{variableName}}` syntax
134	4. ✓ Body content exists (the prompt itself)
135
136	Common Issues:
137	- Wrong extension (`.md` instead of `.prompt.md`)
138	- Invalid `mode` value
139	- Undefined variables in template
140
141	## Instruction File Validation (`<provider>/instructions/*.instructions.md`)
142
143	Required Structure:
144	```yaml
145	---
146	applyTo: "*/.ts"
147	---
148
149	[Contextual instructions]
150	```
151
152	Supported Frontmatter Attributes:
153	- `applyTo` (re

People who liked this also viewed

6 picks

Type