authoring-skills

Name: authoring-skills
Author: vercel

141kstars31kforks

How to install authoring-skills?

vercel/next.js/authoring-skills

$npx -y skills add vercel/next.js --skill authoring-skills

Installs into the current project.

Summary

How to create and maintain agent skills in .agents/skills/. Use when creating a new SKILL.md, writing skill descriptions, choosing frontmatter fields, or deciding what content belongs in a skill vs AGENTS.md. Covers the supported spec fields, description writing, naming conventio

Files · 1

View on GitHub

SKILL.md

1	# Authoring Skills
2
3	Use this skill when creating or modifying agent skills in `.agents/skills/`.
4
5	## When to Create a Skill
6
7	Create a skill when content is:
8
9	- Too detailed for AGENTS.md (code templates, multi-step workflows, diagnostic procedures)
10	- Only relevant for specific tasks (not needed every session)
11	- Self-contained enough to load independently
12
13	Keep in AGENTS.md instead when:
14
15	- It's a one-liner rule or guardrail every session needs
16	- It's a general-purpose gotcha any agent could hit
17
18	## File Structure
19
20	```
21	.agents/skills/
22	└── my-skill/
23	├── SKILL.md # Required: frontmatter + content
24	├── workflow.md # Optional: supplementary detail
25	└── examples.md # Optional: referenced from SKILL.md
26	```
27
28	## Supported Frontmatter Fields
29
30	```yaml
31	---
32	name: my-skill # Required. Used for $name references and /name commands.
33	description: > # Required. How Claude decides to auto-load the skill.
34	What this covers and when to use it. Include file names and keywords.
35	argument-hint: '<pr-number>' # Optional. Hint for expected arguments.
36	user-invocable: false # Optional. Set false to hide from / menu.
37	disable-model-invocation: true # Optional. Set true to prevent auto-triggering.
38	allowed-tools: [Bash, Read] # Optional. Tools allowed without permission.
39	model: opus # Optional. Model override.
40	context: fork # Optional. Isolated subagent execution.
41	agent: Explore # Optional. Subagent type (with context: fork).
42	---
43	```
44
45	Only use fields from this list. Unknown fields are silently ignored.
46
47	## Writing Descriptions
48
49	The `description` is the primary matching surface for auto-activation. Include:
50
51	1. What the skill covers (topic)
52	2. When to use it (trigger scenario)
53	3. Key file names the skill references (e.g. `config-shared.ts`)
54	4. Keywords a user or agent might mention (e.g. "feature flag", "DCE")
55
56	```yaml
57	# Too vague - won't auto-trigger reliably
58	description: Helps with flags.
59
60	# Good - specific files and concepts for matching
61	description: >
62	How to add or modify Next.js experimental feature flags end-to-end.
63	Use when editing config-shared.ts, config-schema.ts, define-env-plugin.ts.
64	```
65
66	## Content Conventions
67
68	### Structure for Action
69
70	Skills should tell the agent what to do, not just what to know:
71
72	- Lead with "Use this skill when..."
73	- Include step-by-step procedures
74	- Add code templates ready to adapt
75	- End with verification commands
76	- Cross-reference related skills in a "Related Skills" section
77
78	### Relationship to AGENTS.md
79
80	\| AGENTS.md (always loaded) \| Skills (on demand) \|
81	\| --------------------------------------- \| ---------------------------------------------------------------------- \|
82	\| One-liner guardrails \| Step-by-step workflows \|
83	\| "Keep require() behind if/else for DCE" \| Full DCE pattern with code examples, verification commands, edge cases \|
84	\| Points to skills via `$name` \| Expands on AGENTS.md rules \|
85
86	When adding a skill, also add a one-liner summary to the relevant AGENTS.md section with a `$skill-name` reference.
87
88	### Naming
89
90	- Short, descriptive, topic-scoped: `flags`, `dce-edge`, `react-vendoring`
91	- No repo prefix (already scoped by `.agents/skills/`)
92	- Hyphens for multi-word names
93
94	### Supplementary Files
95
96	For complex skills, use a hub + detail pattern:
97
98	```
99	pr-status-triage/
100	├── SKILL.md # Overview, quick commands, links to details
101	├── workflow.md # Prioritization and patterns
102	└── local-repro.md # CI env matching
103	```

People who liked this also viewed

6 picks

Type

authoring-skills

141kstars31kforks

View on GitHub

How to install authoring-skills?

vercel/next.js/authoring-skills

$npx -y skills add vercel/next.js --skill authoring-skills

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Authoring Skills
2
3	Use this skill when creating or modifying agent skills in `.agents/skills/`.
4
5	## When to Create a Skill
6
7	Create a skill when content is:
8
9	- Too detailed for AGENTS.md (code templates, multi-step workflows, diagnostic procedures)
10	- Only relevant for specific tasks (not needed every session)
11	- Self-contained enough to load independently
12
13	Keep in AGENTS.md instead when:
14
15	- It's a one-liner rule or guardrail every session needs
16	- It's a general-purpose gotcha any agent could hit
17
18	## File Structure
19
20	```
21	.agents/skills/
22	└── my-skill/
23	├── SKILL.md # Required: frontmatter + content
24	├── workflow.md # Optional: supplementary detail
25	└── examples.md # Optional: referenced from SKILL.md
26	```
27
28	## Supported Frontmatter Fields
29
30	```yaml
31	---
32	name: my-skill # Required. Used for $name references and /name commands.
33	description: > # Required. How Claude decides to auto-load the skill.
34	What this covers and when to use it. Include file names and keywords.
35	argument-hint: '<pr-number>' # Optional. Hint for expected arguments.
36	user-invocable: false # Optional. Set false to hide from / menu.
37	disable-model-invocation: true # Optional. Set true to prevent auto-triggering.
38	allowed-tools: [Bash, Read] # Optional. Tools allowed without permission.
39	model: opus # Optional. Model override.
40	context: fork # Optional. Isolated subagent execution.
41	agent: Explore # Optional. Subagent type (with context: fork).
42	---
43	```
44
45	Only use fields from this list. Unknown fields are silently ignored.
46
47	## Writing Descriptions
48
49	The `description` is the primary matching surface for auto-activation. Include:
50
51	1. What the skill covers (topic)
52	2. When to use it (trigger scenario)
53	3. Key file names the skill references (e.g. `config-shared.ts`)
54	4. Keywords a user or agent might mention (e.g. "feature flag", "DCE")
55
56	```yaml
57	# Too vague - won't auto-trigger reliably
58	description: Helps with flags.
59
60	# Good - specific files and concepts for matching
61	description: >
62	How to add or modify Next.js experimental feature flags end-to-end.
63	Use when editing config-shared.ts, config-schema.ts, define-env-plugin.ts.
64	```
65
66	## Content Conventions
67
68	### Structure for Action
69
70	Skills should tell the agent what to do, not just what to know:
71
72	- Lead with "Use this skill when..."
73	- Include step-by-step procedures
74	- Add code templates ready to adapt
75	- End with verification commands
76	- Cross-reference related skills in a "Related Skills" section
77
78	### Relationship to AGENTS.md
79
80	\| AGENTS.md (always loaded) \| Skills (on demand) \|
81	\| --------------------------------------- \| ---------------------------------------------------------------------- \|
82	\| One-liner guardrails \| Step-by-step workflows \|
83	\| "Keep require() behind if/else for DCE" \| Full DCE pattern with code examples, verification commands, edge cases \|
84	\| Points to skills via `$name` \| Expands on AGENTS.md rules \|
85
86	When adding a skill, also add a one-liner summary to the relevant AGENTS.md section with a `$skill-name` reference.
87
88	### Naming
89
90	- Short, descriptive, topic-scoped: `flags`, `dce-edge`, `react-vendoring`
91	- No repo prefix (already scoped by `.agents/skills/`)
92	- Hyphens for multi-word names
93
94	### Supplementary Files
95
96	For complex skills, use a hub + detail pattern:
97
98	```
99	pr-status-triage/
100	├── SKILL.md # Overview, quick commands, links to details
101	├── workflow.md # Prioritization and patterns
102	└── local-repro.md # CI env matching
103	```

People who liked this also viewed

6 picks

Type