Best for
- Use when creating a new SKILL.
Source profileQuality 89/100
vercel/next.js/.agents/skills/authoring-skills/SKILL.md
authoring-skills
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 conventions, and the relationship between always-loaded AGENTS.md and on-demand skills.
- Source repository stars
- 141,364
- Declared platforms
- 0
- Static risk flags
- 0
- Last source update
- 2026-08-05
- Source checked
- 2026-08-05
Decision brief
What it does—and where it fits
Use this skill when creating or modifying agent skills in .agents/skills/.
Not for
- Tasks that require unconfirmed production actions or broad system permissions.
- Environments where the pinned source and install steps cannot be inspected.
Compatibility matrix
Platform support, with evidence labels
| Platform | Status | Evidence | What to check |
|---|---|---|---|
| Codex | Not declared | No explicit evidence | Portability before use |
| Claude Code | Not declared | No explicit evidence | Portability before use |
| Cursor | Not declared | No explicit evidence | Portability before use |
| Gemini CLI | Not declared | No explicit evidence | Portability before use |
Installation
Inspect first. Install second.
The source command is displayed only when detected. A safe inspection prompt is always available so your agent can explain every action before execution.
Source-detected install commandSource
npx skills add https://github.com/vercel/next.js --skill ".agents/skills/authoring-skills"Safe inspection promptEditorial
Inspect the Agent Skill "authoring-skills" from https://github.com/vercel/next.js/blob/bcea67d4e96fbaf8c51f50951e497724d2a02cfb/.agents/skills/authoring-skills/SKILL.md at commit bcea67d4e96fbaf8c51f50951e497724d2a02cfb. List every install step, command, network request, credential, file read/write, external action, and rollback step. Explain whether it fits my task. Do not install or execute anything until I approve.
Workflow
What the source asks the agent to do
- 01
When to Create a Skill
Create a skill when content is:
Too detailed for AGENTS.md (code templates, multi-step workflows, diagnostic procedures)Only relevant for specific tasks (not needed every session)Self-contained enough to load independently - 02
File Structure
Review the “File Structure” section in the pinned source before continuing.
Review and apply the “File Structure” source section. - 03
Supported Frontmatter Fields
Only use fields from this list. Unknown fields are silently ignored.
Only use fields from this list. Unknown fields are silently ignored. - 04
Writing Descriptions
The description is the primary matching surface for auto-activation. Include:
What the skill covers (topic)When to use it (trigger scenario)Key file names the skill references (e.g. config-shared.ts)
Permission review
Static risk signals and limitations
No configured static risk pattern was detected
This is not proof of safety. Runtime behavior, indirect dependencies, and hidden external systems are outside the static scan.
Evidence record
Why each signal appears
EvidenceSourceComputedTestedEditorial
| Signal | Value | Evidence type | Meaning |
|---|---|---|---|
| Quality score | 89/100 | Computed | Documentation, specificity, maintenance, and trust rules |
| Repository stars | 141,364 | Source | Repository attention, not individual Skill quality |
| Compatibility | 0 platforms | Source | Declared in the catalog source record |
| Usage guide | automated source guide | Editorial | Generated or reviewed according to the visible evidence level |
Pinned source
Provenance and original SKILL.md
- Repository
- vercel/next.js
- Skill path
- .agents/skills/authoring-skills/SKILL.md
- Commit
- bcea67d4e96fbaf8c51f50951e497724d2a02cfb
- License
- MIT
- Collected
- 2026-08-05
- Default branch
- canary
View the original SKILL.md
Authoring Skills
Use this skill when creating or modifying agent skills in .agents/skills/.
When to Create a Skill
Create a skill when content is:
- Too detailed for AGENTS.md (code templates, multi-step workflows, diagnostic procedures)
- Only relevant for specific tasks (not needed every session)
- Self-contained enough to load independently
Keep in AGENTS.md instead when:
- It's a one-liner rule or guardrail every session needs
- It's a general-purpose gotcha any agent could hit
File Structure
.agents/skills/
└── my-skill/
├── SKILL.md # Required: frontmatter + content
├── workflow.md # Optional: supplementary detail
└── examples.md # Optional: referenced from SKILL.md
Supported Frontmatter Fields
---
name: my-skill # Required. Used for $name references and /name commands.
description: > # Required. How Claude decides to auto-load the skill.
What this covers and when to use it. Include file names and keywords.
argument-hint: '<pr-number>' # Optional. Hint for expected arguments.
user-invocable: false # Optional. Set false to hide from / menu.
disable-model-invocation: true # Optional. Set true to prevent auto-triggering.
allowed-tools: [Bash, Read] # Optional. Tools allowed without permission.
model: opus # Optional. Model override.
context: fork # Optional. Isolated subagent execution.
agent: Explore # Optional. Subagent type (with context: fork).
---
Only use fields from this list. Unknown fields are silently ignored.
Writing Descriptions
The description is the primary matching surface for auto-activation. Include:
- What the skill covers (topic)
- When to use it (trigger scenario)
- Key file names the skill references (e.g.
config-shared.ts) - Keywords a user or agent might mention (e.g. "feature flag", "DCE")
# Too vague - won't auto-trigger reliably
description: Helps with flags.
# Good - specific files and concepts for matching
description: >
How to add or modify Next.js experimental feature flags end-to-end.
Use when editing config-shared.ts, config-schema.ts, define-env-plugin.ts.
Content Conventions
Structure for Action
Skills should tell the agent what to do, not just what to know:
- Lead with "Use this skill when..."
- Include step-by-step procedures
- Add code templates ready to adapt
- End with verification commands
- Cross-reference related skills in a "Related Skills" section
Relationship to AGENTS.md
| AGENTS.md (always loaded) | Skills (on demand) |
|---|---|
| One-liner guardrails | Step-by-step workflows |
| "Keep require() behind if/else for DCE" | Full DCE pattern with code examples, verification commands, edge cases |
Points to skills via $name | Expands on AGENTS.md rules |
When adding a skill, also add a one-liner summary to the relevant AGENTS.md section with a $skill-name reference.
Naming
- Short, descriptive, topic-scoped:
flags,dce-edge,react-vendoring - No repo prefix (already scoped by
.agents/skills/) - Hyphens for multi-word names
Supplementary Files
For complex skills, use a hub + detail pattern:
pr-status-triage/
├── SKILL.md # Overview, quick commands, links to details
├── workflow.md # Prioritization and patterns
└── local-repro.md # CI env matching