opencode-skills-collection 4.1.15 → 4.1.16

package/bundled-skills/automated-triage/UPSTREAM-LICENSE.txt

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/bundled-skills/automated-triage/UPSTREAM-NOTICE.md

@@ -0,0 +1,12 @@
+# Upstream helpers for automated-triage
+
+The files listed below were recovered from [monte-carlo-data/mc-agent-toolkit](https://github.com/monte-carlo-data/mc-agent-toolkit) at commit `f1ea90fa2b7fa1ece98e52a45d887c609f2a8de6`. The repository ID is `1166903665`.
+
+They retain the upstream **Apache-2.0** license reproduced in [UPSTREAM-LICENSE.txt](UPSTREAM-LICENSE.txt). This notice applies to the listed support files; it does not replace the license metadata of other catalog files. Preserve the upstream license and this attribution when redistributing them.
+
+License wording is unchanged; text-only trailing whitespace and EOF blank lines are normalized. Original license: https://github.com/monte-carlo-data/mc-agent-toolkit/blob/f1ea90fa2b7fa1ece98e52a45d887c609f2a8de6/LICENSE
+
+| Local file | Original upstream path | Original Git blob SHA | Import changes |
+| --- | --- | --- | --- |
+| `references/triage-stages.md` | `skills/automated-triage/references/triage-stages.md` | `0432f8e5a40db4af4ff1f79d1df6d53df5b806e4` | text-only trailing whitespace and EOF blank lines normalized |
+| `references/triage-example.md` | `skills/automated-triage/references/triage-example.md` | `e18c39fd7cd6af2f24c76e93687dddb62eb47a95` | text-only trailing whitespace and EOF blank lines normalized |

package/bundled-skills/automated-triage/references/triage-example.md

@@ -0,0 +1,115 @@
+# Triage Example Workflow
+
+This is a complete triage workflow that supports two modes:
+
+- **Recommendation mode** — runs the full investigation and tells you what it would do, without writing anything to your environment. Use this while tuning your triage prompt.
+- **Action mode** — runs the full workflow and applies actions (comments, status updates) for real.
+
+Run in recommendation mode first. Once the classifications and recommendations match how your team would respond manually, switch to action mode.
+
+---
+
+## What this workflow does
+
+1. Asks whether to run in recommendation or action mode
+2. Fetches all alerts from the last 3 hours
+3. Scores every alert by incident likelihood and potential impact (in parallel)
+4. Fires deep troubleshooting on all high-signal alerts simultaneously, classifying each as results arrive
+5. In **action mode**: posts a triage comment on every alert and updates statuses
+   In **recommendation mode**: outputs what it would comment and what status it would set — no writes
+
+---
+
+## Procedure
+
+### Step 1: Choose mode
+
+Ask: "Run in **recommendation mode** (no writes — I'll show you what actions would be taken) or **action mode** (comments and status updates applied for real)?"
+
+Also ask: "Run all stages **straight through**, or **step by step** — pausing after each stage to show results before continuing?"
+
+Wait for both answers before proceeding. In step-by-step mode, after each stage completes, summarise what it produced, proactively suggest alternatives or adjustments based on what you observed, and wait for confirmation before moving to the next.
+
+### Step 2: Fetch alerts
+
+Call `get_alerts` for the last 3 hours.
+
+If no alerts are returned, report: "No alerts in the last 3 hours." and stop.
+
+### Step 3: Score each alert
+
+Call `alert_assessment` in parallel for every alert from step 2, in batches of up to 10 at a time. Each result includes `incident_likelihood`, `alert_impact` (HIGH/MEDIUM/LOW each), `alert_description` (plain-language description of what happened in the incident), and `triage_summary` (the key reasoning behind the incident likelihood and potential impact scores). Use `alert_description` and `triage_summary` to inform the triage comment in step 4 for alerts that don't go through troubleshooting.
+
+### Step 4: Troubleshoot and classify high-signal alerts
+
+For each alert where BOTH `incident_likelihood` AND `alert_impact` are MEDIUM or HIGH, call `run_troubleshooting_agent` (default `async_mode=True`). Fire all eligible alerts simultaneously — each call returns immediately with one of: `success` (previous results available immediately), `queued` (accepted, not started yet), or `running` (in progress).
+
+Skip any alert where either value is LOW — troubleshooting is expensive and not warranted for low-signal alerts.
+
+For each job that returned `queued` or `running`, poll with `get_troubleshooting_agent_results(incident_id=...)` — start at ~30 seconds, then increase to 60s intervals. Classify each alert as its result arrives (`success`), before moving on. If a job returns `failed`, note it and continue.
+
+**Classifications:**
+
+| Classification                | When to use                                                                                                           |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| **Intentional change**        | Planned migrations, feature releases, or bug fixes                                                                    |
+| **Natural data variation**    | Seasonal patterns or expected volatility                                                                              |
+| **Possible data incident**    | Anything that requires further investigation                                                                          |
+| **Resolved incident**         | A real incident that has already been resolved                                                                        |
+| **Verified ongoing incident** | A clear incident that has not resolved, where troubleshooting identified the root cause (e.g. query change or infrastructure failure) |
+| **Other**                     | Does not fit the above                                                                                                |
+
+Alerts that did not go through troubleshooting are left unclassified.
+
+### Step 5: Comments and status updates
+
+**Action mode:**
+
+Call `create_or_update_alert_comment` for each alert:
+- **Untroubleshot alerts**: one sentence describing the anomaly and the incident likelihood/potential impact scores. Do not explain why it wasn't troubleshot. No recommendations.
+- **Troubleshot alerts**: 2–4 sentences covering classification, reasoning from the troubleshooting output, any action taken, and a recommendation.
+
+Then call `update_alert` for each classified alert:
+
+| Classification              | Status               |
+| --------------------------- | -------------------- |
+| Natural data variation      | `NO_ACTION_NEEDED`   |
+| Intentional change          | `EXPECTED`           |
+| Resolved incident           | `FIXED`              |
+| Verified ongoing incident   | `ACKNOWLEDGED`       |
+| Possible data incident      | *(no change)*        |
+| Other                       | *(no change)*        |
+
+For alerts classified as **natural data variation**, also call `mark_event_as_normal` — this signals the ML threshold detector to recalibrate and avoid re-alerting on the same pattern. Only has an effect on monitors using automated (ML-based) thresholds.
+
+Do not update status for untroubleshot alerts.
+
+**Recommendation mode:**
+
+Do not call any write tools. Instead, for each alert output:
+- The comment you would post
+- The status you would set (or "no change")
+- Whether you would call `mark_event_as_normal`
+
+---
+
+## Output
+
+After completing all steps, produce a summary table:
+
+| Alert ID | Type | Incident Likelihood | Potential Impact | Classification | Action Taken |
+|----------|------|---------------------|------------------|----------------|--------------|
+
+Include every alert from step 1. For untroubleshot alerts, leave Classification blank and set Action Taken to "Comment only".
+
+---
+
+## Adapting this example
+
+Common adjustments:
+
+- **Change the time window** in step 2 (e.g. last 1 hour for a continuous loop, last 24 hours for a daily run)
+- **Adjust the troubleshooting filter** in step 4
+- **Add Slack or ticket creation** in step 5 for confirmed incidents
+- **Customise `alert_assessment` scoring** via `user_instructions` to tune emphasis for your environment (see `triage-stages.md`)
+- **Run step-by-step when tuning** — a useful pattern is to run the full workflow straight through first to see end-to-end behaviour, then re-run in step-by-step mode to inspect each stage's output and make decisions before proceeding

package/bundled-skills/automated-triage/references/triage-stages.md

@@ -0,0 +1,141 @@
+# Triage Stages
+
+Each stage of a triage workflow is optional and customisable. Design your workflow around the stages that match how your team manually reviews alerts — automate the parts that are repetitive or time-consuming, and keep humans in the loop for the parts that need judgement.
+
+---
+
+## Stage 1: Fetching alerts
+
+**Tool:** `get_alerts`
+
+Collect the alerts you want to triage. `get_alerts` supports the following filters — combine them to define your triage scope:
+
+**Status**
+- `statuses` — filter by alert status. Pass `NOT_ACKNOWLEDGED` to only pick up alerts that haven't been triaged yet. Other values: `ACKNOWLEDGED`, `WORK_IN_PROGRESS`, `FIXED`, `EXPECTED`, `NO_ACTION_NEEDED`.
+
+**Scope**
+- `domain_ids` — limit to one or more Monte Carlo domains. Use `getDomains` to look up IDs. Useful if different teams own different parts of the data estate.
+- `audience_ids`
+- `owners`
+
+**Alert Details**
+- `alert_types` — filter by alert category.
+- `priorities` — `P1` through `P5`.
+
+**Asset**
+- `table_mcons`, `table_names`, `table_schemas`, `table_databases` — narrow triage to specific tables or parts of the warehouse.
+
+**Pagination**
+- `first` — number of alerts per page (max 100, default 20). Check for a `truncation_note` in the response — if present, paginate using `cursor` to retrieve the remaining alerts.
+
+Take care to avoid triaging too many alerts in one batch — where required, split alerts across multiple triage runs.
+
+---
+
+## Stage 2: Initial investigation (alert scoring)
+
+**Tool:** `alert_assessment`
+
+This stage replicates what a knowledgeable engineer does when scanning the alert feed — quickly assessing what's fired and how serious it looks. `alert_assessment` is lightweight enough to run on every alert.
+
+It returns:
+- **`incident_likelihood`** (HIGH/MEDIUM/LOW) — how likely the alert represents a real issue. Affected by: number of events, presence of concerning root causes (query changes, failures), how much thresholds were exceeded, and how noisy the monitor typically is.
+- **`alert_impact`** (HIGH/MEDIUM/LOW) — how significant the potential downstream impact is.  Use cases impacted.  Dashboards affected etc.
+- **`alert_description`** — plain-language description of what happened in the incident.
+- **`triage_summary`** — the key reasoning behind the incident likelihood and potential impact scores.
+
+**Run `alert_assessment` in parallel**, in batches of up to 10 at a time.
+
+### Customising the scoring
+
+`alert_assessment` runs with a default prompt but accepts a `user_instructions` parameter that lets you adjust the emphasis it places on different factors. For example:
+
+- Increase the weight given to monitors that feed particular use cases
+- Alter the emphasis placed on different features: for example historical noise
+- Emphasise alerts involving specific tables or domains
+
+Start with the defaults and tune `user_instructions` once you've seen real output.
+
+### Scoring vs. persisting: `alert_assessment` vs `triage_alert`
+
+`alert_assessment` is **read-only** — it returns a verdict but records nothing. That's exactly what you want for this stage: score every alert cheaply, then decide per alert whether it warrants troubleshooting and which action to take. The workflow persists outcomes later, in Stage 5, through the explicit action tools — so you stay in control of what gets written and when.
+
+`triage_alert` is the **persisted** counterpart: it scores *and* writes the verdict back onto the alert (marks it triaged, posts a notification, records ML feedback), identical to the in-app Triage button. It's the right tool for interactive "triage this alert" requests where the user wants the result recorded, but it's a poor fit for the scoring stage of a batch workflow — it would mark every alert in the batch triaged and fire a notification for each. Keep batch scoring on `alert_assessment`, and reserve `triage_alert` for the case where recording a single alert's triage *is* the action. It's idempotent (re-running on an already-triaged alert returns the existing verdict) and requires the `mcp/edit` scope.
+
+---
+
+## Stage 3: Deep troubleshooting
+
+**Tools:** `run_troubleshooting_agent`, `get_troubleshooting_agent_results`
+
+`run_troubleshooting_agent` runs the Monte Carlo Troubleshooting Agent on a single alert. This is substantially more expensive than `alert_assessment` — it tracks the issue upstream through lineage, analyses all queries involved, examines relevant PRs, and samples affected tables to identify root cause.
+
+**Only run `run_troubleshooting_agent` on alerts that warrant it.** A common filter: run troubleshooting only when BOTH `incident_likelihood` AND `alert_impact` are MEDIUM or HIGH. Skip any alert where either is LOW.
+
+You can adjust this threshold based on your environment — for example, also running troubleshooting when either score is HIGH (even if the other is LOW), while still requiring MEDIUM/MEDIUM as the baseline.
+
+**Use async mode for parallelism.** `run_troubleshooting_agent` defaults to `async_mode=True`, returning immediately with one of three statuses:
+- `success` — a previous analysis already completed; results are available immediately, no polling needed
+- `queued` — the job was accepted but hasn't started yet; wait ~30 seconds then start polling
+- `running` — the job is in progress; poll with increasing intervals (30s, 60s, 60s…)
+
+Fire all eligible alerts simultaneously, then poll each with `get_troubleshooting_agent_results(incident_id=...)` until it returns `success` or `failed`. Classify each alert as its result arrives. This avoids the timeout issues of synchronous calls and removes the need to limit concurrency.
+
+---
+
+## Stage 4: Classification
+
+Classify each alert immediately after its troubleshooting result arrives. Use the troubleshooting output to determine which category fits best.
+
+| Classification              | Description                                                                                                                    |
+| --------------------------- |--------------------------------------------------------------------------------------------------------------------------------|
+| **Intentional change**      | Planned migrations, feature releases, or bug fixes                                                                             |
+| **Natural data variation**  | Seasonal patterns or expected volatility                                                                                       |
+| **Possible data incident**  | Anything that requires further investigation                                                                                   |
+| **Resolved incident**       | A real incident that has already been resolved                                                                                 |
+| **Verified ongoing incident** | A clear incident that has not resolved, where troubleshooting identified the root cause (e.g. query change or infrastructure failure) |
+| **Other**                   | Does not fit the above                                                                                                         |
+
+These categories are a starting point. Adapt them to the language your team uses — if you have an internal classification scheme, map to that instead.
+
+---
+
+## Stage 5: Taking actions
+
+What you do after triage depends on your integrations, your team's workflow, and the maturity of your automation process. Start conservative and expand as you validate results.
+
+### Adding comments
+
+`create_or_update_alert_comment` — always a good starting point. Comments provide a record of what the agent found and recommended, without taking any irreversible action. Useful at every stage, regardless of whether you automate anything else.
+
+Suggested comment content:
+- **Scored but not troubleshot**: one sentence describing the anomaly and the incident likelihood/potential impact scores. Do not explain why it wasn't troubleshot. No recommendations.
+- **Troubleshot alerts**: 2–4 sentences — classification, reasoning, action taken or recommended
+
+### Updating alert status
+
+`update_alert` — set status based on classification:
+
+| Classification              | Status               |
+| --------------------------- | -------------------- |
+| Natural data variation      | `NO_ACTION_NEEDED`   |
+| Intentional change          | `EXPECTED`           |
+| Resolved incident           | `FIXED`              |
+| Verified ongoing incident   | `ACKNOWLEDGED`       |
+| Possible data incident      | *(leave unchanged)*  |
+| Other                       | *(leave unchanged)*  |
+
+Only update status for alerts that went through full troubleshooting. Leave untroubleshot alerts unchanged.
+
+### Additional Monte Carlo actions
+
+- **Mark events as normal** — for alerts classified as natural variation, marking the underlying events as normal allows the detector to adapt thresholds to prevent further alerts on similar patterns. Only applies to monitors using automated (ML-based) thresholds — has no effect on static-threshold monitors.
+- **Declare an incident** (`update_alert` with `declared_incident_severity`) — promotes the alert to an incident, escalating visibility. Values: `SEV_1`–`SEV_4`. Use `NO_SEVERITY` to clear. Appropriate for verified ongoing incidents.
+- **Assign ownership** (`set_alert_owner`) — route a confirmed incident or required investigation to the right person.
+
+### External integrations
+
+- **Slack** — message a channel or individual with a triage summary or escalation
+- **Linear / Jira / Teams** — create a ticket for confirmed incidents
+
+Introduce these actions incrementally. Start with comments, validate, then enable status updates and additional actions.

package/bundled-skills/avoid-ai-writing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: avoid-ai-writing
-description: "Audit and rewrite content to remove 21 categories of AI writing patterns with a 43-entry replacement table"
+description: "Audit and rewrite prose for repetitive, vague, or formulaic wording while preserving meaning, evidence, and the writer's voice."
 risk: none
 source: https://github.com/conorbronsdon/avoid-ai-writing
 date_added: "2026-03-06"
@@ -8,7 +8,7 @@ date_added: "2026-03-06"
 
 # Avoid AI Writing — Audit & Rewrite
 
-Detects and fixes AI writing patterns ("AI-isms") that make text sound machine-generated. Covers 21 pattern categories with a 43-entry word/phrase replacement table that maps each flagged term to a specific, plainer alternative.
+Detects and fixes AI writing patterns ("AI-isms") that make text sound machine-generated. Covers 21 pattern categories with examples of plainer alternatives. The full upstream pattern catalog is not bundled in this AAS entrypoint; do not claim a complete 43-entry table is present.
 
 ## When to Use This Skill
 
@@ -37,6 +37,8 @@ Audit this for AI writing patterns:
 4. **Second-pass audit** — re-reads the rewrite to catch any surviving tells
 
 ## Limitations
+- These are editorial heuristics, not proof of AI authorship. Preserve factual claims, uncertainty, attributed quotations, code, identifiers, and the requested scope.
+- For audit-only requests, report findings without rewriting. Avoid replacing a precise technical term merely because it appears on a word list.
 
 - Does not detect AI-generated code, only prose
 - Pattern matching is guideline-based, not absolute — some flagged words are fine in context

package/bundled-skills/awareness-stage-mapper/SKILL.md

@@ -5,12 +5,18 @@ risk: safe
 source: community
 date_added: "2026-04-04"
 ---
-You are a **Cognitive Psychologist specializing in persuasion and belief change**. Your task is to diagnose precisely where a customer sits on the awareness ladder and calibrate the psychological approach, language register, and persuasion strategy accordingly.
+Use a marketing planning and audience-research lens. Your task is to diagnose precisely where a customer sits on the awareness ladder and calibrate the psychological approach, language register, and persuasion strategy accordingly.
 
 ## When to Use
 - Use when you need to identify how aware an audience already is before writing messaging or offers.
 - Use when a campaign needs stage-specific language, sequencing, or persuasion strategy.
 
+## Evidence and scope
+
+Use observed audience research and verified product facts. Psychological interpretations and the author-year references below are inherited conceptual context, not validated evidence for this exact workflow or a guaranteed conversion effect. Before using a scientific claim externally, verify the actual publication, method and applicability; omit unsupported claims. This is marketing planning, not clinical diagnosis. Do not infer sensitive traits or exploit vulnerabilities.
+
+Original contribution: [PR 451](https://github.com/sickn33/agentic-awesome-skills/pull/451) by MMEHDI0606; [immutable source snapshot](https://github.com/MMEHDI0606/antigravity-awesome-skills/blob/9c61357e3e6bb167946036f52ac1e28fc82e04d0/skills/awareness-stage-mapper/SKILL.md). This identifies the contributed instructions, not scientific validation or a new upstream endorsement.
+
 ## CONTEXT GATHERING
 
 Before diagnosing awareness, establish:
@@ -31,23 +37,23 @@ Awareness determines whether the audience can process central arguments or will
 
 **Step 1 - Classify the awareness stage**
 Label the audience as unaware, problem aware, solution aware, product aware, or most aware.
-*Research basis: message processing differs sharply by prior knowledge and perceived relevance (ELM; Zhang et al., 2024).*
+*Planning hypothesis (verify before presenting as research): message processing differs sharply by prior knowledge and perceived relevance (ELM; Zhang et al., 2024).*
 
 **Step 2 - Assess motivation and ability**
-Decide whether the audience has enough motivation and cognitive capacity for detailed argument.
-*Research basis: the central route works when involvement and ability are high; otherwise peripheral cues dominate (Quick et al., 2018; SanJose-Cabezudo et al., 2009).*
+Use observable evidence of interest and familiarity: questions prospects actually asked, concepts they can explain, and the time/format available. If that evidence is absent, record motivation and familiarity as unknown and propose a simple message test. Do not infer intelligence or mental capacity from demographic labels.
+*Planning hypothesis (verify before presenting as research): the central route works when involvement and ability are high; otherwise peripheral cues dominate (Quick et al., 2018; SanJose-Cabezudo et al., 2009).*
 
 **Step 3 - Select the persuasion route**
 Choose educational framing for unaware/problem aware audiences and comparative proof for later-stage audiences.
-*Research basis: premature solution pitching can trigger reactance and weak processing (Lavoie & Quick, 2013; Grandpre et al., 2003).*
+*Planning hypothesis (verify before presenting as research): premature solution pitching can trigger reactance and weak processing (Lavoie & Quick, 2013; Grandpre et al., 2003).*
 
 **Step 4 - Calibrate language register**
 Match vocabulary depth, jargon, and specificity to the stage.
-*Research basis: familiarity and self-relevance shape attention and acceptance (Zhang et al., 2024; Moyer-Gusé et al., 2022).*
+*Planning hypothesis (verify before presenting as research): familiarity and self-relevance shape attention and acceptance (Zhang et al., 2024; Moyer-Gusé et al., 2022).*
 
 **Step 5 - Choose the entry point**
 Recommend the best first touchpoint for downstream content: education, proof, demo, comparison, or direct offer.
-*Research basis: stage-appropriate sequencing improves narrative transportation and belief change (Green & Brock, 2000; Chen & Bell, 2022).*
+*Planning hypothesis (verify before presenting as research): stage-appropriate sequencing improves narrative transportation and belief change (Green & Brock, 2000; Chen & Bell, 2022).*
 
 ## DECISION MATRIX
 
@@ -96,7 +102,7 @@ The line between persuasion and manipulation is using stage-appropriate language
 
 ## SKILL CHAINING
 
-Before invoking this skill, the agent should have completed:
+Optional context from related skills (equivalent supplied research is sufficient; do not create a prerequisite cycle):
 - [ ] `@customer-psychographic-profiler`
 - [ ] `@jobs-to-be-done-analyst`
 
@@ -122,6 +128,8 @@ Before finalizing output, the agent asks:
 
 > Identify how aware an audience already is before writing messaging or offers.
 
+**Illustrative output:** Given an interview where buyers name the problem but no solution, label problem-aware as a provisional inference; propose an explanatory message and list what evidence would change the classification.
+
 ## Limitations
 - Use this skill only when the task clearly matches the scope described above.
 - Do not treat the output as a substitute for environment-specific validation, testing, or expert review.

package/bundled-skills/aws-cdk-development/SKILL.md

@@ -9,6 +9,13 @@ date_added: 2026-07-01
 license: MIT
 license_source: https://github.com/zxkane/aws-skills/blob/main/LICENSE
 ---
+## Bundled upstream support
+
+Supporting files are included at skill-relative paths. See [UPSTREAM-NOTICE.md](UPSTREAM-NOTICE.md) for their pinned sources, licenses, hashes, and import changes.
+
+## Restored helper safety
+
+`scripts/validate-stack.sh` runs `cdk synth` from the caller-selected project root, which executes that project's CDK application and dependencies, can write `cdk.out`, and may contact AWS context providers if the project requires lookups. Review the project and AWS context before invoking it. The helper does not deploy; deployment needs separate user authorization.
 
 # AWS CDK Development
 

package/bundled-skills/aws-cdk-development/UPSTREAM-LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mengxin Zhu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bundled-skills/aws-cdk-development/UPSTREAM-NOTICE.md

@@ -0,0 +1,14 @@
+# Upstream helpers for aws-cdk-development
+
+The files listed below were recovered from [zxkane/aws-skills](https://github.com/zxkane/aws-skills) at commit `68530c6f296ccd2f5e99c79782f3e0fbf962c51a`. The repository ID is `1080226559`.
+
+They retain the upstream **MIT** license reproduced in [UPSTREAM-LICENSE.txt](UPSTREAM-LICENSE.txt). This notice applies to the listed support files; it does not replace the license metadata of other catalog files. Preserve the upstream license and this attribution when redistributing them.
+
+License wording is unchanged; text-only trailing whitespace and EOF blank lines are normalized. Original license: https://github.com/zxkane/aws-skills/blob/68530c6f296ccd2f5e99c79782f3e0fbf962c51a/LICENSE
+
+| Local file | Original upstream path | Original Git blob SHA | Import changes |
+| --- | --- | --- | --- |
+| `references/cdk-patterns.md` | `plugins/aws-iac/skills/aws-cdk-development/references/cdk-patterns.md` | `7c533a80e548956cc50e69233bdc2d1617175c47` | text-only trailing whitespace and EOF blank lines normalized |
+| `scripts/validate-stack.sh` | `plugins/aws-iac/skills/aws-cdk-development/scripts/validate-stack.sh` | `54f9e0512b1b8a3e5aa54b3dd76e3bc56f0814c1` | stored without executable bit; invoke via its interpreter; AAS correctness and scope adaptation: resolves and synthesizes only the caller-selected CDK project root instead of the installed skill catalog |
+
+`scripts/validate-stack.sh` runs the project's `cdk synth` and executes CDK application code; synthesis can write `cdk.out`, execute project dependencies, and contact AWS context providers if the project requires lookups. It now uses the caller's current directory or `CDK_PROJECT_ROOT` as the project root. Review the project and AWS context first. It does not deploy; deployment requires separate user authorization.