Dynamo Repo Agent Instructions Updates (#17025)

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: QilongTang

.agents/README.md

@@ -69,7 +69,7 @@ Each skill lives in its own folder with a `SKILL.md` and optionally a `template.
 | [dynamo-onboarding](skills/dynamo-onboarding/SKILL.md) | Learning the Dynamo codebase, architecture briefings, finding where to start on a Jira ticket. | Repo-specific variant |
 | [dynamo-pr-description](skills/dynamo-pr-description/SKILL.md) | Writing PR descriptions matching the Dynamo template. | Repo-specific variant |
 | [dynamo-jira-ticket](skills/dynamo-jira-ticket/SKILL.md) | Creating or refining Jira tickets from bugs, test failures, or feature requests. | Repo-specific variant |
-| [dynamo-skill-writer](skills/dynamo-skill-writer/SKILL.md) | Authoring/updating skills and enforcing sync across Copilot, Cursor, and Claude surfaces. | Repo-specific variant |
+| [dynamo-skill-writer](skills/dynamo-skill-writer/SKILL.md) | Authoring and updating skills; writing high-quality skill instructions; managing sync across Copilot, Cursor, and Claude surfaces. | Repo-specific variant |
 | [dynamo-unit-testing](skills/dynamo-unit-testing/SKILL.md) | Writing NUnit tests following Dynamo patterns. Test classes, setup/teardown, .dyn file testing. | Repo-specific variant |
 | [dynamo-ux-designer](skills/dynamo-ux-designer/SKILL.md) | Planning UX flows and producing Weave-aligned interface designs and mockups. | Repo-specific variant |
 | [dynamo-webview-component-scaffold](skills/dynamo-webview-component-scaffold/SKILL.md) | Scaffolding new Dynamo WebView2 view-extension package repositories. | Repo-specific variant |

.agents/skills/dynamo-skill-writer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dynamo-skill-writer
-description: Author and maintain Dynamo agent skills while enforcing cross-tool sync between canonical .agents skills and generated wrappers for GitHub Copilot, Cursor, and Claude Code.
+description: Author and maintain Dynamo agent skills. Use this skill whenever creating a new skill in .agents/skills/, updating an existing skill, fixing drift between canonical skills and Copilot/Cursor/Claude wrappers, or asking how to write effective skill instructions for the Dynamo repo.
 ---
 
 # Dynamo Skill Writer
@@ -9,7 +9,7 @@ description: Author and maintain Dynamo agent skills while enforcing cross-tool
 
 - Creating a new skill in `.agents/skills/`.
 - Updating an existing skill and ensuring tool mirrors remain aligned.
-- Adding or updating Copilot agent wrappers that should be generated from canonical skills.
+- Adding or updating Copilot agent wrappers generated from canonical skills.
 - Fixing drift between canonical skill content and generated wrappers.
 
 ## When not to use
@@ -27,43 +27,47 @@ A concrete set of file edits and validation steps that:
 - updates canonical skill content in `.agents/skills/`
 - updates sync metadata in `.github/scripts/sync_agent_wrappers.ps1` when Copilot exposure is needed
 - regenerates and validates wrappers in `.github/agents/`
-- updates index/docs references in `.agents/README.md`, `.github/copilot-instructions.md`, and `CLAUDE.md` when applicable
+- updates index/docs references in `.agents/README.md`, `.github/copilot-instructions.md`, and `AGENTS.md` when applicable
 
 ---
 
 ## Workflow
 
 1. Determine whether this is a **new skill** or an **update to an existing skill**.
 2. Author or update canonical content in `.agents/skills/<skill-name>/SKILL.md`.
-3. If the skill should be available as a Copilot agent, add an entry to the `canonicalSkills` array in `.github/scripts/sync_agent_wrappers.ps1`.
-4. Regenerate wrappers:
-   - `./.github/scripts/sync_agent_wrappers.ps1`
-5. Validate sync:
-   - `./.github/scripts/sync_agent_wrappers.ps1 -Check -VerboseReport`
-6. Update discovery docs when skill inventory changed:
+3. **Ask the user** whether the skill should be surfaced as a Copilot agent before touching any wrapper files. The sync steps below are optional — skip them unless the user confirms.
+4. *(If confirmed)* Add an entry to the `canonicalSkills` array in `.github/scripts/sync_agent_wrappers.ps1`.
+5. *(If confirmed)* Regenerate wrappers: `./.github/scripts/sync_agent_wrappers.ps1`
+6. *(If confirmed)* Validate sync: `./.github/scripts/sync_agent_wrappers.ps1 -Check -VerboseReport`
+7. Update discovery docs when skill inventory changed:
    - `.agents/README.md`
    - `.github/copilot-instructions.md`
-   - `CLAUDE.md`
-7. Ensure no contradictions between canonical and mirrored surfaces.
+   - `AGENTS.md`
+8. Ensure no contradictions between canonical and mirrored surfaces.
+
+## Boundaries
+
+- ✅ **Always**: edit `.agents/skills/<skill>/SKILL.md` and its `assets/`/`references/` files; update `.agents/README.md` and `AGENTS.md`
+- ⚠️ **Ask first**: touch `.github/scripts/sync_agent_wrappers.ps1` or trigger wrapper regeneration — confirm Copilot surfacing intent before running the sync script
+- 🚫 **Never**: hand-edit generated wrappers in `.github/agents/` — they are always overwritten by the sync script, so manual edits are lost and create drift
 
 ## Rules
 
-- `.agents/` is the canonical source of truth for skill logic.
-- Generated wrappers in `.github/agents/` must not be hand-edited.
-- Skill metadata (name/description) should be concise and stable.
-- If mirrors conflict with canonical files, canonical files win.
+- `.agents/` is the canonical source of truth for skill logic. When mirrors conflict with canonical files, canonical wins.
+- Generated wrappers in `.github/agents/` must never be hand-edited — they exist only as outputs of the sync script.
+- Skill metadata (`name`/`description`) should be concise and stable; churn in these fields breaks triggering accuracy.
 - Keep changes deterministic so `-Check` mode stays reliable in CI.
 
 ## New Skill Checklist
 
 - [ ] Created `.agents/skills/<skill-name>/SKILL.md` with frontmatter (`name`, `description`)
 - [ ] Added skill to `.agents/README.md` Quick Reference table
 - [ ] Added skill to `.agents/README.md` parity matrix (if cross-tool surfaced)
-- [ ] Added skill to `.github/scripts/sync_agent_wrappers.ps1` wrapper map (if Copilot surfaced)
-- [ ] Regenerated `.github/agents/*` wrappers
-- [ ] Ran `./.github/scripts/sync_agent_wrappers.ps1 -Check -VerboseReport`
+- [ ] *(If Copilot-surfaced)* Added skill to `.github/scripts/sync_agent_wrappers.ps1` wrapper map
+- [ ] *(If Copilot-surfaced)* Regenerated `.github/agents/*` wrappers
+- [ ] *(If Copilot-surfaced)* Ran `./.github/scripts/sync_agent_wrappers.ps1 -Check -VerboseReport`
 - [ ] Updated `.github/copilot-instructions.md` skill list
-- [ ] Updated `CLAUDE.md` skill list
+- [ ] Updated `AGENTS.md` skill list
 
 ## Naming guidance
 
@@ -72,10 +76,140 @@ A concrete set of file edits and validation steps that:
 
 ## Example intent
 
-"Create a skill that enforces consistent skill-sync behavior across Copilot, Cursor, and Claude."
+> "Create a skill that enforces consistent skill-sync behavior across Copilot, Cursor, and Claude."
 
 Expected result:
 - New canonical skill in `.agents/skills/`
-- New generated wrapper in `.github/agents/`
-- Sync script updated and passing in check mode
-- README/Copilot/Claude skill indexes updated
+- User asked whether Copilot wrapper is needed before any sync steps run
+- *(If yes)* New generated wrapper in `.github/agents/`, sync script updated and passing in check mode
+- `AGENTS.md`, `.agents/README.md`, and `.github/copilot-instructions.md` skill indexes updated
+
+---
+
+## Writing a High-Quality Skill
+
+### Start minimal, then iterate
+
+Write a skill to handle one focused task well. Anticipating all requirements upfront produces bloated prompts that are harder to maintain and easier to overfit. Expand based on observed gaps instead.
+
+### The description is the trigger — make it specific and slightly pushy
+
+The description field is what the agent reads when deciding whether to consult this skill. Vague descriptions cause undertriggering; overly broad ones cause false matches. Include the concrete contexts that should activate the skill, not just a general summary.
+
+❌ Vague:
+```
+description: Helps with code tasks in Dynamo.
+```
+
+✅ Specific and triggering:
+```
+description: Write and review NUnit tests for DynamoCore following Dynamo testing
+patterns, base class selection, and AAA structure. Use when writing test methods,
+setting up test infrastructure, or reviewing tests for quality.
+```
+
+Include the framework and key constraints when they matter (`.NET 10`, `NUnit`, `WPF Windows-only`). Per skill-creator guidance: all "when to use" information belongs in the description, not just the body.
+
+### Commands belong early and must be executable
+
+List commands in an early section with exact flags — not just tool names. An agent that doesn't know the flags will guess, and guesses are wrong.
+
+❌ Missing flags:
+```
+Run dotnet test to execute tests.
+```
+
+✅ Executable:
+```bash
+dotnet test src/DynamoCoreTests/DynamoCoreTests.csproj --filter "Name~MyTest"
+```
+
+### Code examples over prose
+
+One real snippet showing the expected pattern beats three paragraphs describing it. Explain the *why* behind rules rather than issuing mandates — an agent that understands reasoning generalizes better than one following a checklist.
+
+Show both ✅ correct and ❌ anti-pattern forms for non-obvious rules:
+
+❌ Prose only:
+```
+Override BuildOutputAst and return a list of AssociativeNodes.
+```
+
+✅ Code example:
+```csharp
+public override IEnumerable<AssociativeNode> BuildOutputAst(
+    List<AssociativeNode> inputAstNodes)
+{
+    return new[] { AstFactory.BuildAssignment(
+        GetAstIdentifierForOutputIndex(0),
+        AstFactory.BuildFunctionCall("MyLib.MyFunc", inputAstNodes)) };
+}
+```
+
+### Define explicit boundaries
+
+Use a three-tier system so the agent knows what requires human approval before acting:
+
+- ✅ **Always do** — safe, reversible, local actions (read files, run tests, edit `.cs` files)
+- ⚠️ **Ask first** — affects shared state or is hard to reverse (add entries to `PublicAPI.Unshipped.txt`, edit `.resx` files, rename public types)
+- 🚫 **Never do** — destructive or policy-violating (hand-edit generated wrappers in `.github/agents/`, remove entries from `PublicAPI.Shipped.txt`, suppress CA2327/CA2328/CA2329/CA2330)
+
+### Map file-level responsibilities
+
+When a skill touches multiple directories, state which it reads vs. writes. This prevents unintended side effects and makes it obvious what "done" looks like:
+
+| Path | Access |
+|---|---|
+| `.agents/skills/<skill>/SKILL.md` | Read + Write (canonical) |
+| `.github/agents/*.md` | Read only (generated — never hand-edit) |
+| `.github/scripts/sync_agent_wrappers.ps1` | Read + Write (sync map) |
+| `.agents/README.md` | Read + Write (index) |
+
+### Reference assets, don't inline everything
+
+Put detailed reference material in `assets/` or `references/` sub-files and link from the skill. This keeps `SKILL.md` under ~500 lines and scannable.
+
+```
+## Assets & References
+- **[quality-checklist.md](./references/quality-checklist.md)** — anti-patterns and PR checklist
+- **[template.md](./assets/template.md)** — copy-paste skill template
+```
+
+---
+
+## Skill Template
+
+```markdown
+---
+name: dynamo-<skill-name>
+description: One sentence covering what this skill does AND the specific contexts
+that should trigger it. Be concrete. Be slightly pushy.
+---
+
+# Dynamo <Skill Name>
+
+## When to use
+- Bullet list of triggering scenarios.
+
+## When not to use
+- Redirect to the correct skill where applicable.
+
+## Inputs expected
+What the caller must provide.
+
+## Output format
+What the skill produces.
+
+---
+
+## Workflow
+Numbered steps. Reference asset files for detail rather than inlining.
+
+## Boundaries
+- ✅ Always: ...
+- ⚠️ Ask first: ...
+- 🚫 Never: ...
+
+## Assets & References
+- **[asset.md](./assets/asset.md)** — description
+```

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,12 +1,11 @@
 <!--
 Please Note:
 1. Before submitting the PR, please review [How to Contribute to Dynamo](https://github.com/DynamoDS/Dynamo/blob/master/CONTRIBUTING.md)
-2. Dynamo Team will meet 1x a month to review PRs found on Github (Issues will be handled separately)
-3. PRs will be reviewed from oldest to newest
-4. If a reviewed PR requires changes by the owner, the owner of the PR has 30 days to respond. If the PR has seen no activity by the next session, it will be either closed by the team or depending on its utility will be taken over by someone on the team
-5. PRs should use either Dynamo's default PR template or [one of these other template options](https://github.com/DynamoDS/Dynamo/wiki/Choosing-a-Pull-Request-Template) in order to be considered for review.
-6. PRs that do not have one of the Dynamo PR templates completely filled out with all declarations satisfied will not be reviewed by the Dynamo team.
-7. PRs made to the `DynamoRevit` repo will need to be cherry-picked into all the DynamoRevit Release branches that Dynamo supports. Contributors will be responsible for cherry-picking their reviewed commits to the other branches after a `LGTM` label is added to the PR.
+2. PRs will be reviewed from oldest to newest
+3. If a reviewed PR requires changes by the owner, the owner of the PR has 30 days to respond. If the PR has seen no activity by the next session, it will be either closed by the team or depending on its utility will be taken over by someone on the team
+4. PRs should use either Dynamo's default PR template or [one of these other template options](https://github.com/DynamoDS/Dynamo/wiki/Choosing-a-Pull-Request-Template) in order to be considered for review.
+5. PRs that do not have one of the Dynamo PR templates completely filled out with all declarations satisfied will not be reviewed by the Dynamo team.
+6. PRs made to the `DynamoRevit` repo will need to be cherry-picked into all the DynamoRevit Release branches that Dynamo supports. Contributors will be responsible for cherry-picking their reviewed commits to the other branches after a `LGTM` label is added to the PR.
 -->
 
 ### Purpose

.github/agents/dynamo-skill-writer.agent.md

@@ -1,6 +1,6 @@
 ---
 name: Dynamo Skill Writer
-description: Author and maintain Dynamo agent skills while enforcing cross-tool sync between canonical .agents skills and generated wrappers for GitHub Copilot, Cursor, and Claude Code.
+description: Author and maintain Dynamo agent skills. Use this skill whenever creating a new skill in .agents/skills/, updating an existing skill, fixing drift between canonical skills and Copilot/Cursor/Claude wrappers, or asking how to write effective skill instructions for the Dynamo repo.
 ---
 
 # Dynamo Skill Writer

.github/copilot-instructions.md

@@ -42,6 +42,20 @@ dotnet build src/DynamoCore.sln -c Release /p:Platform=NET_Linux
 
 Tests are located in the `test/` directory. Use Visual Studio Test Explorer or dotnet test CLI to run tests.
 
+**Running a single test:**
+```bash
+# Filter by test name (substring match)
+dotnet test src/DynamoCoreTests/DynamoCoreTests.csproj --filter "Name~MyTestClass"
+
+# Filter by NUnit category
+dotnet test src/DynamoCoreTests/DynamoCoreTests.csproj --filter "Category=UnitTests"
+
+# Combine with & (AND) or | (OR)
+dotnet test src/DynamoCoreTests/DynamoCoreTests.csproj --filter "Name~WhenCondition&Category=UnitTests"
+```
+
+UI tests are split across `DynamoCoreWpfTests`, `DynamoCoreWpfTests2`, and `DynamoCoreWpfTests3`.
+
 ## Code Style and Formatting
 
 ### Follow Existing Standards
@@ -100,12 +114,11 @@ Dynamo/
 
 ### Pull Requests
 
+- PR title must include the Jira ticket: `DYN-1234 concise summary`
 - Use one of the [Dynamo PR templates](https://github.com/DynamoDS/Dynamo/wiki/Choosing-a-Pull-Request-Template)
-- All template declarations must be satisfied
+- All template declarations must be satisfied; Release Notes section is mandatory (use `N/A` if not user-facing)
 - Include unit tests when adding new features
 - Start with a test that highlights broken behavior when fixing bugs
-- PRs are reviewed monthly, oldest to newest
-- PR owners have 30 days to respond to feedback
 
 ### API Compatibility
 
@@ -116,6 +129,37 @@ Dynamo/
 
 ## Node Development
 
+### Node Registration Patterns
+
+**Zero-touch** (static methods) — preferred for pure computation. Place static methods in a class under `src/Libraries/`. Namespace becomes the library category. Use XML `<search>` tags for keywords:
+
+```csharp
+/// <summary>Brief description.</summary>
+/// <returns name="result">Output description.</returns>
+/// <search>keyword1,keyword2</search>
+public static double MyFunction(double x) { ... }
+```
+
+**Explicit NodeModel** — required for custom UI, dynamic ports, or multi-output nodes. Inherit from `NodeModel` in `src/Libraries/CoreNodeModels/`. Requires two constructors — a `[JsonConstructor]` private one and a public parameterless one:
+
+```csharp
+[NodeName("Display Name"), NodeCategory("Category.Sub")]
+[IsDesignScriptCompatible]
+public class MyNode : NodeModel
+{
+    [JsonConstructor]
+    private MyNode(IEnumerable<PortModel> inPorts, IEnumerable<PortModel> outPorts)
+        : base(inPorts, outPorts) { }
+
+    public MyNode() { /* AddPorts(); RegisterAllPorts(); */ }
+
+    public override IEnumerable<AssociativeNode> BuildOutputAst(
+        List<AssociativeNode> inputAstNodes) { ... }
+}
+```
+
+Use `[AlsoKnownAs("OldName")]` when renaming nodes to preserve backward compatibility.
+
 ### Detecting New Node Additions
 
 A new node addition is identified by: