mirror of
https://github.com/hanzoai/next.js.git
synced 2026-10-30 14:46:38 +00:00
6d572c27e0
### What? Adds a `reply-and-resolve-thread` subcommand to `scripts/pr-status.js` that combines replying and resolving a review thread in a single command. Also updates the generated `thread-N.md` files to show this command alongside the existing separate `reply-thread` and `resolve-thread` options, and documents the command in the agent skill files. ### Why? When addressing PR review comments, the typical workflow is to reply with a description of what was done and then immediately resolve the thread. This previously required two separate commands: ```bash node scripts/pr-status.js reply-thread <id> "Done -- ..." node scripts/pr-status.js resolve-thread <id> ``` Having a single command reduces friction for agents (and humans) closing out review threads after addressing feedback. ### How? - Added `reply-and-resolve-thread` subcommand in `main()` that calls the existing `replyToThread()` and `resolveThread()` functions in sequence. - Updated `generateThreadMd()` to include a "Reply and resolve in one step" code block in the Commands section of each unresolved thread file (alongside the existing separate commands, not replacing them). - Updated `.agents/skills/pr-status-triage/SKILL.md` to mention the combined command in workflow step 6 and added a "Thread interaction" quick-command reference section. - Updated `.agents/skills/pr-status-triage/workflow.md` to show the one-step alternative in the "Resolving Review Threads" section. <!-- NEXT_JS_LLM_PR --> --------- Co-authored-by: Tobias Koppers <[email protected]> Co-authored-by: Claude <[email protected]>
Skills Authoring Guide
Skills are on-demand context files that Claude loads when relevant. They extend AGENTS.md with deep-dive workflows, code templates, and verification steps.
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 every session needs it)
- Self-contained enough to load independently
Do NOT create a skill for:
- One-liner rules or guardrails (keep those in AGENTS.md)
- Content every agent session needs (that's what AGENTS.md is for)
- Simple facts without actionable steps
File Structure
.agents/skills/
├── my-skill/
│ └── SKILL.md # Required: frontmatter + content
│ └── workflow.md # Optional: supplementary files
│ └── examples.md # Optional: referenced from SKILL.md
└── README.md # This file
SKILL.md Format
---
name: my-skill
description: >
What this skill covers and when to use it. Include key file names,
concepts, and trigger phrases so Claude can match user intent to this
skill. This is the primary field Claude uses for auto-activation.
---
Supported Frontmatter Fields
| Field | Required | Description |
|---|---|---|
name |
Yes | Skill name, used for $name references and /name slash commands |
description |
Yes | What the skill does and when to use it. This is how Claude decides to auto-load the skill. Include file names, concepts, and keywords. |
argument-hint |
No | Hint for expected arguments in autocomplete |
user-invocable |
No | Set to false to hide from / slash command menu |
disable-model-invocation |
No | Set to true to prevent Claude from auto-triggering this skill |
allowed-tools |
No | Tools Claude can use without permission when this skill is active |
model |
No | Model override for this skill |
context |
No | Set to fork for isolated subagent execution |
agent |
No | Subagent type to use with context: fork |
hooks |
No | Hooks scoped to this skill's lifecycle |
Only use fields from this table. Unknown fields are ignored by Claude Code.
Writing Good Descriptions
The description is the single most important field. Claude uses it to decide when to auto-load the skill. Include:
- What the skill covers (the topic)
- When to use it (the trigger scenario)
- Key file names mentioned in the skill (e.g.
config-shared.ts,entry-base.ts) - Key concepts/keywords a user or agent might mention (e.g. "DCE", "feature flag", "vendored React")
# Bad: too vague, won't match well
description: Helps with flags.
# Good: specific, includes file names and keywords
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,
next-server.ts, export/worker.ts, or module.compiled.js.
Content Guidelines
Relationship to AGENTS.md
AGENTS.md holds always-loaded guardrails (one-liner rules every session needs). Skills hold deep-dive content loaded on demand.
- AGENTS.md should have a one-liner version of any critical rule
- Skills expand on those rules with verification steps, code examples, and context
- AGENTS.md points to skills via
$skill-namereferences - Skills should not duplicate AGENTS.md content; they should go deeper
Structure a Skill for Action
Skills should tell the agent what to do, not just what to know:
- Lead with a clear "Use this skill when..." statement
- Include step-by-step procedures where applicable
- Add code templates ready to adapt
- End with verification commands
- Cross-reference related skills with a "Related Skills" section
Naming
- Use short, descriptive names scoped to the topic:
flags,dce-edge,react-vendoring - No repo-name prefix (skills are already scoped to this repo by being in
.agents/skills/) - Use hyphens for multi-word names
Supplementary Files
For complex skills, split into a hub SKILL.md + detail files:
pr-status-triage/
├── SKILL.md # Overview + quick commands
├── workflow.md # Detailed prioritization and patterns
└── local-repro.md # CI env matching guide
Reference detail files from SKILL.md with relative links. Keep SKILL.md scannable as an entry point.