AndriySvyryd · Oct 8, 2026 · Oct 5, 2026 · Oct 5, 2026
@@ -23,6 +23,10 @@ Manages entity states and detects changes for `SaveChanges()`.
 - Snapshot and notification strategies both call `SetPropertyModified()` to keep property flags and entity state consistent.
 - `SetEntityState()` validates values, updates flags and complex entries, changes state, then runs manager bookkeeping hooks.
 
+## Shared-Identity Replacement
+
+`SharedIdentityEntry` is the invariant that distinguishes an old deleted entry from its replacement with the same identity. When attaching a replacement graph, a deleted nested entry should be reconsidered only when its source entry has a replacement; do not broadly process every deleted node. Likewise, cascading from the old replaced principal must not delete dependents that belong to the replacement graph. Keep synchronous and asynchronous graph-attach paths equivalent and preserve unrelated values in replacement tests so they isolate the identity transition.
+
 ## Testing
 
 Unit tests: `test/EFCore.Tests/ChangeTracking/`. Functional tests: `test/EFCore.Specification.Tests/GraphUpdates/`.
@@ -31,7 +35,7 @@ Unit tests: `test/EFCore.Tests/ChangeTracking/`. Functional tests: `test/EFCore.
 
 | Pitfall | Solution |
 |---------|----------|
-| There is a failure when there is shared identity entry (Added and Deleted) | Add code that checks `SharedIdentityEntry` |
+| State-based checks treat every Added/Deleted entry as a replacement | Scope replacement behavior through `SharedIdentityEntry` and the graph source |
 
 ## Validation
 

@@ -30,8 +30,9 @@ Before reading the author's narrative:
 
 1. Read each changed implementation beyond its diff hunk. Diff-only review is insufficient evidence for a finding. For very large files, read the containing members, their contracts, and relevant state. When many files are changed, use subagents to break down the review into manageable parts and gather context incrementally.
 2. Search callers, implementations, overrides, sibling provider paths, and nearby tests. Read shared helpers whose contracts control the changed behavior.
-3. Use focused history when it can explain an invariant, revert, or prior fix attempt.
-4. Describe the old and new behavior, likely motivation, affected callers/providers, and initial concerns in your own words.
+3. When logic moves, compare the old and new input domains to ensure coverage is preserved.
+4. Use focused history when it can explain an invariant, revert, or prior fix attempt.
+5. Describe the old and new behavior, likely motivation, affected callers/providers, and initial concerns in your own words.
 
 ### 3. Reconcile Pull Request Context
 
@@ -54,6 +55,8 @@ For each non-trivial production change, identify:
 
 Check correctness, error handling, async behavior, concurrency, state and resource lifetime, compatibility, provider hierarchy behavior, NativeAOT constraints, and performance only where the changed path plausibly makes them relevant.
 
+For exception cleanup around shared or concurrent state, distinguish whether this invocation acquired each resource from whether the resource currently appears held. Construct a concrete interleaving and require focused coverage that exercises ownership without weakening existing reentrancy or nesting behavior.
+
 For new functionality consider other feature areas that might be affected but are not directly touched by the change.
 
 Do not request tests for documentation-only changes, comments, formatting, or demonstrably behavior-preserving mechanical changes. Do not flag issues that the compiler, formatter, or existing analyzers deterministically report.

@@ -207,7 +207,16 @@ Key considerations:
 - Use the [GitHub Copilot Extensions documentation](https://docs.github.com/en/copilot/building-copilot-extensions/about-building-copilot-extensions) for the full integration guide
 - For VS Code-specific features (editor access, file trees, command buttons), prefer an extension-based participant instead
 
-### Step 7: Validate
+### Step 7: Author the harness evaluation
+
+Create `eng/harness-evaluation/agents/<agent-id>/eval.yaml` and follow `eng/harness-evaluation/README.md`.
+
+- Declare only the agent file in the eval's root `agent_environment.files`; the experiment removes it from the control.
+- Use realistic stimuli that exercise behavior distinctive to the agent without stating the expected diagnosis or implementation in the prompt.
+- Combine deterministic output checks, a focused semantic rubric, bounded resources, token grading, and a committed scoring threshold.
+- Keep the eval name and directory-derived component ID identical to the agent ID.
+
+### Step 8: Validate
 
 After creating or modifying an agent, verify:
 
@@ -220,6 +229,7 @@ After creating or modifying an agent, verify:
 - [ ] Agent does not duplicate functionality of built-in agents (`@workspace`, `@vscode`, `@terminal`)
 - [ ] Handoff agent names match existing agents
 - [ ] Agent instructions don't include secrets, tokens, or internal URLs
+- [ ] The paired harness eval targets only this agent and is meant to meaningfully distinguish treatment from control
 
 ## Common Pitfalls
 

@@ -106,6 +106,15 @@ Add conditions to avoid unnecessary runs:
 - Early `return` in scripts for PR author, draft status, etc.
 - Idempotency checks (e.g., hidden HTML comments as tags to prevent duplicate actions)
 
+For `pull_request_target` policy workflows that react to `opened`, `edited`, and `reopened`:
+
+- On `edited`, return unless `context.payload.changes?.base` is present; title or body edits must not reapply a target-branch policy.
+- Check permissions for `context.actor`, not only the PR author. A maintainer may edit or reopen an external PR, and that action must use the maintainer's authority.
+- For `opened`, the actor and author are the same, so perform one permission lookup and reuse it for policy and labeling decisions.
+- Exclude automation when either the actor or author is a bot.
+- Encode the prohibited branch class directly (for example, `release/*`) instead of requiring a single allowed branch such as `main`.
+- If permission lookup fails, stop without taking a destructive action; unknown access is not evidence that the contributor is external.
+
 ### Step 5: Validate
 
 After creating the workflow:
@@ -152,19 +161,37 @@ const { data: permissions } = await github.rest.repos.getCollaboratorPermissionL
 const hasWriteAccess = ['admin', 'write'].includes(permissions.permission);
 ```
 
-### Preventing Duplicate Comments (SHA Tag Pattern)
+### Updating Bot-Owned Comments Idempotently
+
+A hidden marker identifies the workflow's comment but does not establish ownership: contributors can place the same marker in their own comments. Match the marker only on a bot-authored comment, then update that comment or create a new one. Preserve the workflow's pinned action SHA and never execute code from a pull-request fork in a `pull_request_target` job.
 
 ```javascript
-const shaTag = `<!-- tag: ${headSha} -->`;
-const { data: comments } = await github.rest.issues.listComments({
+const marker = '<!-- validate-pr-target-branch -->';
+const comments = await github.paginate(github.rest.issues.listComments, {
   owner: context.repo.owner,
   repo: context.repo.repo,
   issue_number: prNumber,
   per_page: 100
 });
-if (comments.some(c => c.body?.includes(shaTag))) {
-  console.log('Already processed');
-  return;
+
+const body = `${marker}\nComment text`;
+const existing = comments.find(comment =>
+  comment.user?.type === 'Bot' && comment.body?.includes(marker));
+
+if (existing) {
+  await github.rest.issues.updateComment({
+    owner: context.repo.owner,
+    repo: context.repo.repo,
+    comment_id: existing.id,
+    body
+  });
+} else {
+  await github.rest.issues.createComment({
+    owner: context.repo.owner,
+    repo: context.repo.repo,
+    issue_number: prNumber,
+    body
+  });
 }
 ```
 

@@ -1,139 +1,54 @@
 ---
 name: make-skill
-description: 'Create and evaluate new Agent Skills for GitHub Copilot. Use when asked to create, scaffold, or add a skill. Generates SKILL.md, optional resources, and a paired Vally harness eval.'
+description: 'Create, review, or fix Agent Skills for GitHub Copilot. Use when asked to create, scaffold, improve, or repair a SKILL.md and its paired harness evaluation.'
 ---
 
-# Create Skill
+# Create Or Fix A Skill
 
-This skill helps you scaffold new agent skills that conform to the Agent Skills specification. Agent Skills are a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows.
+Produce concise, stable task guidance that adds knowledge an agent cannot reliably infer from source alone, together with a paired evaluation that proves the guidance changes behavior.
 
-## When Not to Use
+## Choose The Right Primitive
 
-- Creating custom agents (use the agents/ directory pattern)
-- Adding language-specific, framework-specific, or module-specific coding guidelines (use file-based instructions instead)
-
-### Key Principles
-
-- **Frontmatter is critical**: `name` and `description` determine when the skill triggers—be clear and comprehensive
-- **Concise is key**: Only include what agents don't already know; context window is shared
-- **Useful instructions**: Only include information that's stable, not easily searchable and can be used for any task within the skill's scope
-- **No duplication**: Information lives in SKILL.md OR reference files, not both
+- Use a skill for a task-specific workflow or body of knowledge loaded on demand.
+- Use file instructions for background guidance scoped to paths.
+- Use a custom agent when context isolation or distinct tool restrictions are required.
+- Prefer an existing skill over creating an overlapping one.
 
 ## Workflow
 
-### Step 1: Investigate the Topic
-
-Build deep understanding of the relevant topics using the repository content, existing documentation, and any linked external resources.
-
-After investigating, verify:
-- [ ] Can explain what the skill does in one paragraph
-- [ ] Can list 3-5 specific scenarios where the skill is applicable
-- [ ] Can identify common pitfalls or misconceptions about the topic
-- [ ] Can outline a step-by-step skill workflow with clear validation steps
-- [ ] Have search queries for deeper topics
-- [ ] Can determine if the skill should be user-invocable or background knowledge only
-
-If there are any ambiguities, gaps in understanding, or multiple valid approaches, ask the user for clarification before proceeding to skill creation. Also, evaluate whether the task might be better handled by a custom agent, agentic workflow, an existing skill or multiple narrower skills, and discuss this with the user if relevant.
-
-### Step 2: Create the skill directory
-
-```
-.agents/skills/<skill-name>/
-├── SKILL.md          # Required: instructions + metadata
-```
-
-### Step 3: Generate SKILL.md with frontmatter
-
-Create the file with required YAML frontmatter:
-
-```yaml
----
-name: <skill-name>
-description: <description of what the skill does and when to use it>
-user-invocable: <Optional, defaults to true. Set to false for background knowledge skills.>
-argument-hint: <Optional, guidance for how agents should format arguments when invoking the skill.>
-disable-model-invocation: <Optional, set to true to prevent agents from invoking the skill and only allow to be used through manual invocation.>
-compatibility: <Optional, specify any environment, tool, or context requirements for the skill.>
-metadata: <Optional, key-value mapping for additional metadata that may be relevant for discovery or execution.>
-allowed-tools: <Optional, list of pre-approved tools that agents could use when invoking the skill.>
----
-```
-
-### Step 4: Add body content sections
+1. Read the relevant implementation, tests, repository instructions, and neighboring customizations.
+2. Identify repeated mistakes or non-obvious invariants. Do not turn source inventories, line counts, or facts easily rediscovered from code into skill content.
+3. Create `.agents/skills/<name>/SKILL.md`. The frontmatter `name` must exactly match the directory; the description must state what the skill does and when natural user requests should trigger it.
+4. Mark background domain guidance `user-invocable: false`. Keep user-invocable workflows focused on an outcome a user would deliberately request.
+5. Write actionable guidance with observable validation. Explain why edge cases matter; avoid generic engineering advice already present in repository instructions.
+6. Create `eng/harness-evaluation/skills/<name>/eval.yaml` and follow `eng/harness-evaluation/README.md`.
+7. Lint the customization and inspect both control and treatment artifacts before accepting it.
 
-Include these recommended sections, following this file's structure:
+## Paired Evaluation
 
-1. **<Human-readable skill name>**: One paragraph describing the outcome beyond what's already in the description
-2. **When Not to Use**: Bullet list of exclusions, optional
-3. **Inputs and Outputs**: Example inputs and expected outputs, if applicable
-4. **Workflow**: Numbered steps with checkpoints
-5. **Testing**: Instructions for how to create automated tests for the skill output, if applicable
-6. **Validation**: How to confirm the skill worked correctly
-7. **Common Pitfalls**: Known traps and how to avoid them, optional
+- The eval root `agent_environment.skills` contains only the target skill. Stimulus inputs belong under each stimulus's `agent_environment.files`.
+- The runner removes the root skill for control and separately verifies treatment activation. Do not add a `skill-invocation` grader and do not tell the agent to invoke the skill in the shared prompt.
+- Prompts may identify fixtures, proposed code, fixed IDs, and output paths, but must not reveal the expected diagnosis, owning mechanism, or regression-test design.
+- Use deterministic graders for observable artifacts, a narrow semantic rubric for behavior, and a `token-budget` grader. Define bounded turns, tokens, and duration plus a committed scoring threshold.
+- The task must exercise guidance distinctive to the skill. A control that consistently matches treatment means the skill or eval is not useful enough.
 
-### Step 5: Add and populate optional directories if needed
+## Validation
 
-```
-.agents/skills/<skill-name>/
-├── SKILL.md
-├── scripts/          # Optional: executable code that agents can run
-├── references/       # Optional: REFERENCE.md (Detailed technical reference), FORMS.md (Form templates or structured data formats), domain-specific instruction files
-└── assets/           # Optional: templates, resources and other data files that aren't executable or Markdown
-```
-
-### Step 6: Write Scripts (Script-driven Only)
-
-- Prefer PowerShell, but can also use Python or JavaScript
-- Standard param block with defaults
-- Ensure scripts produce clear, structured, and parseable console output (for example, section headers and status lines)
-- Emoji status: ✅ green / ⚠️ yellow / 🔴 red
-- **Fail-closed error handling** — Unknown ≠ Healthy
-
-> ❌ **NEVER** count API failures as success. Return "Unknown" and exclude from positive counts.
-
-### Step 7: Author and validate the harness evaluation
-
-Create `eng/harness-evaluation/skills/<skill-name>/eval.yaml` and follow the authoring and validation rules in `eng/harness-evaluation/README.md`. Do not add a `skill-invocation` grader; the runner separately requires exact invocation of `<skill-name>` in every treatment trial so control and treatment share the same quality score. The eval must meaningfully distinguish the skilled treatment from the unskilled control.
-
-Also verify:
-
-- [ ] The skill name does not start or end with a hyphen, contain consecutive hyphens, or exceed 64 characters
-- [ ] YAML frontmatter name matches the directory name exactly and all frontmatter fields are valid
-- [ ] SKILL.md is under 500 lines and 5000 tokens, splitting stable detail into references when needed
-- [ ] File references are relative and instructions are actionable and specific
-- [ ] Instructions do not duplicate `.github/copilot-instructions.md` or `.github/instructions/`
-- [ ] The workflow has numbered steps and observable success criteria
-- [ ] No secrets, tokens, or internal URLs are included
-- [ ] Optional directories are used appropriately
-- [ ] Scripts handle edge cases, fail closed, and return structured, helpful errors
-- [ ] The paired Vally comparison demonstrates distinctive value over the unskilled control
-
-### Step 8: Test with Multi-Model Subagents
-
-Follow [references/testing-patterns.md](references/testing-patterns.md):
-
-1. Select top-tier model from 2-4 different families
-2. Give each the same test prompt exercising the skill
-3. Launch in parallel via `task` tool with `model` parameter
-4. Synthesize: consensus findings = high confidence
-5. Fix errors first, then warnings, then consider suggestions
-6. **Retrospective**: When an agent misapplies guidance, ask the *same model* why it made that choice — its self-analysis reveals guidance gaps you can close with targeted anti-patterns (see references/anti-patterns.md)
-7. **A/B test**: After fixing issues, re-run the same task to verify improvement — same model, same prompt, compare correctness/speed/tool calls (see references/testing-patterns.md)
-
-**For new skills or major restructuring**, use the writer-critic convergence loop instead: one agent writes, a different-model agent critiques, writer applies fixes, repeat until convergence (2-3 rounds). See references/testing-patterns.md#writer-critic-convergence-loop.
+- Frontmatter parses and the name matches the directory.
+- The skill is concise, stable, and does not duplicate root or scoped instructions.
+- File references are relative and exist.
+- Validation steps are observable and task-specific.
+- The paired eval targets only the skill, has complete bounded grading, and uses a solution-neutral prompt.
+- `npm run lint` and the harness inventory tests pass.
 
 ## Common Pitfalls
 
-| Pitfall | Solution |
-|---------|----------|
-| Description is vague | Include what it does AND when to use it |
-| Instructions are ambiguous | Use numbered steps with concrete actions |
-| Missing validation steps | Add checkpoints that verify success |
-| Hardcoded environment assumptions | Document requirements in `compatibility` field |
-| Key files section lists files previously mentioned | Avoid duplication, only include in one place and rename section to "Other Key Files" |
-| Testing section lists test folders that are obvious from the repo structure | Remove the section if it doesn't add value |
-
-## References
-
-- [Agent Skills Specification](https://agentskills.io/specification)
-- Repository guidance: `.github/copilot-instructions.md` and `.github/CONTRIBUTING.md`
+| Pitfall | Correction |
+|---|---|
+| Copying implementation inventories into the skill | Keep only non-obvious invariants and routing decisions |
+| Exact line counts or volatile metrics | Remove them; point to stable symbols or behavior |
+| Generic test-folder guidance | Describe the distinctive test shape or omit it |
+| Eval prompt tells the agent what to find | Move expected facts into the hidden rubric |
+| Eval root contains repository fixtures | Keep only the target skill at root; stage fixtures per stimulus |
+| Prompt instructs skill invocation | Let the treatment-only runner gate enforce activation |
+| Initial scaffold launches multi-model review | First produce and lint the requested artifacts; run expensive behavioral validation separately |