feat(skills): add adapt skill for evidence-driven change detection

.agents/skills/README.md

@@ -8,6 +8,7 @@ A complete skill is a directory with a required `SKILL.md` file and optional bun
 
 | Skill | Use it for | Notable resources |
 | --- | --- | --- |
+| [`adapt`](adapt/SKILL.md) | Detecting evidence-driven change needs and routing updates to the right skill, workflow, artifact, or owner. | [`evals/`](adapt/evals/) |
 | [`ask-questions`](ask-questions/SKILL.md) | Generating high-leverage questions, clarifying missing context, and surfacing assumptions. | [`evals/`](ask-questions/evals/) |
 | [`audit-skill-security`](audit-skill-security/SKILL.md) | Auditing third-party or local skills before installing, updating, or trusting them. | [`references/audit-protocol.md`](audit-skill-security/references/audit-protocol.md) |
 | [`classify-content`](classify-content/SKILL.md) | Organizing material into meaningful groups by criteria, similarity, priority, dependency, or abstraction level. | [`evals/`](classify-content/evals/) |

.agents/skills/adapt/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: adapt
+description: Detect evidence-driven change needs. Use when the user says "adapt based on this", "what should change after this?", "this keeps happening", "this failed, what should change?", "the workflow no longer fits", "the constraints changed", or asks what skill, rule, doc, eval, memory, or process should change.
+license: MIT
+tags:
+  - adaptation
+  - feedback
+  - process
+metadata:
+  author: Oleg Shulyakov
+  version: "1.0.0"
+  source: github.com/olegshulyakov/agent.md
+  catalog: utility
+  category: productivity
+  references:
+    - create-skill
+    - create-rule
+    - remember-context
+    - write-prd
+    - write-spec
+    - write-tech-docs
+    - write-tests
+    - write-user-story
+---
+
+# adapt
+
+## Workflow
+
+**Detect what should change going forward because reality contradicted the current setup.**
+
+1. Identify the adaptation signal: observed outcome, user feedback, failure, repeated friction, outdated assumption, or changed constraint.
+2. Decide whether the signal is durable enough to justify adaptation, or only a one-off exception.
+3. Identify the affected behavior or artifact: skill, rule, workflow, document, eval, memory convention, test, or process.
+4. Check whether the symptom comes from a governing convention, template, or source-of-truth artifact; route the change there instead of patching only the local artifact.
+5. State the smallest useful change that would prevent recurrence or fit the new constraint.
+6. Route the actual update to the appropriate follow-up skill, workflow, or owner.
+7. Define how the adaptation should be verified.
+
+---
+
+## Output
+
+**Make the diagnosis actionable without doing the update by default.**
+
+- **Signal:** State what happened or changed.
+- **Interpretation:** Explain why it indicates a future behavior or artifact may need to change.
+- **Target:** Name the affected artifact, behavior, or process when identifiable.
+- **Change:** Describe the smallest useful adaptation.
+- **Route:** Identify the appropriate follow-up skill, workflow, or owner for the actual update.
+- **Verification:** State what should be true after the adaptation.
+
+---
+
+## Boundaries
+
+**Adaptation is diagnosis and routing, not a generic rewrite workflow.**
+
+- **Do not overfit:** Avoid changing durable behavior for a single ambiguous incident unless the user explicitly wants a one-off correction.
+- **Do not rewrite by default:** Do not edit skills, rules, docs, evals, tests, or memory unless the user separately asks to proceed with that update.
+- **Use evidence:** Base adaptation on observed outcomes, feedback, failures, repeated friction, outdated assumptions, or changed constraints.
+- **Route precisely:** Skills belong with skill-authoring workflows, rules with rule-authoring workflows, docs with writing workflows, tests with testing workflows, and durable facts with memory workflows.
+- **Prefer source of truth:** When the mismatch comes from a convention, template, or authoring guidance, adapt that governing artifact instead of only patching the artifact that exposed the problem.
+- **Keep uncertainty visible:** If the target artifact or change is unclear, name the likely candidates and the evidence needed to choose.
+
+---
+
+## Non-Triggers
+
+**Nearby requests often need another mode unless they ask what should change going forward.**
+
+- **Direct editing:** "Update this doc" or "rewrite this skill" should perform the requested artifact update, not stop at adaptation diagnosis.
+- **Memory only:** "Remember this decision" should preserve durable context rather than diagnose process change.
+- **Root-cause only:** "Why did this fail?" should explain or investigate unless the user asks what should change afterward.
+- **Decision only:** "Which option should we choose?" should compare options and recommend a direction.
+- **Planning only:** "Break this down" should produce a plan when the desired change is already known.
+
+---
+
+## Verification
+
+**A good adaptation recommendation changes future behavior without broadening the system unnecessarily.**
+
+- **Evidence test:** The recommendation ties back to a concrete signal, not a vague desire to improve.
+- **Durability test:** The change handles a repeated or likely future condition, not only the exact current wording.
+- **Scope test:** The proposed change is the smallest artifact or behavior update that addresses the signal.
+- **Routing test:** The actual update path is clear and does not create a hidden runtime dependency on another skill.

.agents/skills/adapt/evals/evals.json

@@ -0,0 +1,67 @@
+{
+  "evals": [
+    {
+      "id": "adapt-001",
+      "category": "true-positive",
+      "prompt": "This failed, what should change so we don't repeat it?",
+      "expected_trigger": "Trigger adapt.",
+      "expected_output": "Identifies the failure signal, decides whether durable adaptation is warranted, names the affected behavior or artifact, routes the actual update, and defines verification."
+    },
+    {
+      "id": "adapt-002",
+      "category": "true-positive",
+      "prompt": "Our instructions didn't handle this edge case. What artifact should change because of this?",
+      "expected_trigger": "Trigger adapt.",
+      "expected_output": "Maps the observed gap to likely instruction, rule, skill, eval, or doc targets and recommends the smallest follow-up update path."
+    },
+    {
+      "id": "adapt-003",
+      "category": "true-positive",
+      "prompt": "We keep hitting this issue during reviews. Do we need to update a skill, rule, doc, eval, or memory?",
+      "expected_trigger": "Trigger adapt.",
+      "expected_output": "Treats the repeated friction as an adaptation signal, compares likely target artifacts, and routes the actual change without rewriting by default."
+    },
+    {
+      "id": "adapt-004",
+      "category": "true-positive",
+      "prompt": "The constraints changed, and the workflow no longer fits. Adapt based on this.",
+      "expected_trigger": "Trigger adapt.",
+      "expected_output": "Identifies the changed constraint, explains the mismatch, proposes the smallest workflow or artifact adaptation, and states verification criteria."
+    },
+    {
+      "id": "adapt-005",
+      "category": "true-positive",
+      "prompt": "You patched this skill, but the real issue was the authoring guidance. What should change?",
+      "expected_trigger": "Trigger adapt.",
+      "expected_output": "Recognizes that the durable change belongs in the governing convention or authoring source of truth, not only in the local skill that exposed the mismatch."
+    },
+    {
+      "id": "adapt-006",
+      "category": "false-positive",
+      "prompt": "Improve this skill's examples and validation checklist.",
+      "expected_trigger": "Do not trigger adapt as the primary skill.",
+      "expected_output": "Should use the skill-authoring workflow directly because the user already requested a concrete skill update."
+    },
+    {
+      "id": "adapt-007",
+      "category": "false-positive",
+      "prompt": "Remember that we decided to keep adapt as a routing skill.",
+      "expected_trigger": "Do not trigger adapt.",
+      "expected_output": "Should preserve durable memory if appropriate rather than diagnose what should change."
+    },
+    {
+      "id": "adapt-008",
+      "category": "non-trigger",
+      "prompt": "Why did the deployment fail yesterday?",
+      "expected_trigger": "Do not trigger adapt.",
+      "expected_output": "Should investigate or explain the failure unless the user asks what should change going forward."
+    },
+    {
+      "id": "adapt-009",
+      "category": "non-trigger",
+      "prompt": "Break the migration into milestones with risks and validation steps.",
+      "expected_trigger": "Do not trigger adapt.",
+      "expected_output": "Should produce a work plan because the user asked for sequencing, not evidence-driven adaptation."
+    }
+  ]
+}

.agents/skills/create-skill/SKILL.md

@@ -60,7 +60,7 @@ If the request spans multiple phases, read the references in workflow order: aut
 - **Scan anchors**: use bold labels for distinct rule bullets in prose skill docs unless the section is a schema, command example, or literal output template.
 - **Size discipline**: keep metadata under 100 tokens and the main instruction body under 500 lines; use references for anything that would push past that.
 - **Metadata fields**: use only `name`, `description`, `license`, `tags`, and `metadata` at the top level; put `author`, `version`, `source`, `catalog`, `category`, and `references` under `metadata`.
-- **Reference metadata**: use `metadata.references` only for local skills or rules the skill uses as part of its workflow; do not list route-away, adjacent-skill, near-miss, or boundary mentions.
+- **Reference metadata**: use `metadata.references` for local skills or rules the skill uses as part of its workflow, including router skills that name follow-up skills as intended routes. Do not list adjacent-skill, near-miss, boundary, or example-only mentions.
 - **Pushy descriptions**: explicitly name the user phrases and contexts that should trigger the skill, not just what it does. Claude tends to undertrigger, so err toward specificity.
 - **Trigger placement**: put all "when to use" and skill-call scope information in the frontmatter `description`; do not add a body `Scope` section for activation criteria. Put routing, exclusions, boundaries, examples, and detailed procedures in the body or references.
 - **No placeholders**: add `scripts/`, `references/`, `assets/`, or `evals/` only when the skill actually uses them.

.agents/skills/create-skill/references/authoring.md

@@ -43,9 +43,9 @@ Common nested metadata fields:
 | `metadata.source` | Repository or canonical source reference, such as `github.com/org/repo`. |
 | `metadata.catalog` | Optional catalog grouping string. |
 | `metadata.category` | Optional domain category string in lowercase kebab-case, such as `development`, `documentation`, or `project-management`. |
-| `metadata.references` | Optional list of local skill or rule names this skill explicitly uses. |
+| `metadata.references` | Optional list of local skill or rule names this skill explicitly uses or routes to. |
 
-Use `metadata.references` only when this skill actually uses another local skill or rule as part of its workflow. Include a referenced item when the body tells the agent to use, apply, delegate to, or run that skill/rule before or during this skill's work. Do not include skills that appear only as route-away guidance, adjacent alternatives, near misses, exclusions, or examples of work this skill should not handle.
+Use `metadata.references` when this skill actually uses another local skill or rule as part of its workflow. Include a referenced item when the body tells the agent to use, apply, delegate to, run, or route follow-up work to that skill/rule. Do not include skills that appear only as adjacent alternatives, near misses, exclusions, boundaries, or examples of work this skill should not handle.
 
 Keep the Markdown body under 500 lines. The body should explain workflow, routing decisions, boundaries, critical rules, and output format. Move deep detail into `references/` and point to it clearly. Do not use a body `Scope` section to describe when the skill should be called; that belongs in `description` per the Agent Skills spec.