opencode-skills-collection 4.1.15 → 4.1.16

package/bundled-skills/azure-speech-to-text-rest-py/references/pronunciation-assessment.md

@@ -0,0 +1,276 @@
+# Pronunciation Assessment
+
+Evaluate pronunciation quality of speech input using the REST API for short audio.
+
+## Limitations
+
+- Maximum 30 seconds of audio (vs 60 seconds for regular transcription)
+- Requires reference text to compare against
+
+## Headers
+
+Add the `Pronunciation-Assessment` header with Base64-encoded JSON parameters:
+
+```python
+import base64
+import json
+import os
+import requests
+
+def transcribe_with_pronunciation_assessment(
+    audio_file_path: str,
+    reference_text: str,
+    language: str = "en-US"
+) -> dict:
+    """Transcribe with pronunciation assessment."""
+    region = os.environ["AZURE_SPEECH_REGION"]
+    api_key = os.environ["AZURE_SPEECH_KEY"]
+
+    url = f"https://{region}.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1"
+
+    # Build pronunciation assessment parameters
+    pron_params = {
+        "ReferenceText": reference_text,
+        "GradingSystem": "HundredMark",
+        "Granularity": "Word",
+        "Dimension": "Comprehensive",
+        "EnableProsodyAssessment": True
+    }
+
+    # Base64 encode the JSON
+    pron_header = base64.b64encode(
+        json.dumps(pron_params).encode("utf-8")
+    ).decode("utf-8")
+
+    headers = {
+        "Ocp-Apim-Subscription-Key": api_key,
+        "Content-Type": "audio/wav; codecs=audio/pcm; samplerate=16000",
+        "Accept": "application/json",
+        "Pronunciation-Assessment": pron_header
+    }
+
+    params = {"language": language, "format": "detailed"}
+
+    with open(audio_file_path, "rb") as audio_file:
+        response = requests.post(url, headers=headers, params=params, data=audio_file)
+
+    response.raise_for_status()
+    return response.json()
+
+# Usage
+result = transcribe_with_pronunciation_assessment(
+    "greeting.wav",
+    "Good morning.",
+    "en-US"
+)
+
+# Access pronunciation scores
+if result["RecognitionStatus"] == "Success":
+    nbest = result["NBest"][0]
+    print(f"Accuracy: {nbest['AccuracyScore']}")
+    print(f"Fluency: {nbest['FluencyScore']}")
+    print(f"Prosody: {nbest.get('ProsodyScore', 'N/A')}")
+    print(f"Completeness: {nbest['CompletenessScore']}")
+    print(f"Overall: {nbest['PronScore']}")
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `ReferenceText` | **Yes** | Text the pronunciation is evaluated against |
+| `GradingSystem` | No | `FivePoint` (0-5) or `HundredMark` (0-100). Default: `FivePoint` |
+| `Granularity` | No | `Phoneme`, `Word`, or `FullText`. Default: `Phoneme` |
+| `Dimension` | No | `Basic` (accuracy only) or `Comprehensive`. Default: `Basic` |
+| `EnableMiscue` | No | Enable omission/insertion detection. Default: `False` |
+| `EnableProsodyAssessment` | No | Enable prosody scoring. Default: `False` |
+| `ScenarioId` | No | GUID for custom point system |
+
+## Grading Systems
+
+### FivePoint (Default)
+- Returns floating-point scores from 0.0 to 5.0
+
+### HundredMark
+- Returns floating-point scores from 0.0 to 100.0
+- More intuitive for most applications
+
+## Granularity Levels
+
+### Phoneme (Default)
+Shows scores at full-text, word, and phoneme levels:
+```json
+{
+  "AccuracyScore": 95.0,
+  "Words": [
+    {
+      "Word": "good",
+      "AccuracyScore": 100.0,
+      "Phonemes": [
+        {"Phoneme": "g", "AccuracyScore": 100.0},
+        {"Phoneme": "uh", "AccuracyScore": 95.0},
+        {"Phoneme": "d", "AccuracyScore": 100.0}
+      ]
+    }
+  ]
+}
+```
+
+### Word
+Shows scores at full-text and word levels only.
+
+### FullText
+Shows score at full-text level only.
+
+## Response with Pronunciation Assessment
+
+```json
+{
+  "RecognitionStatus": "Success",
+  "Offset": 700000,
+  "Duration": 8400000,
+  "DisplayText": "Good morning.",
+  "SNR": 38.76819,
+  "NBest": [
+    {
+      "Confidence": 0.98503506,
+      "Lexical": "good morning",
+      "Display": "Good morning.",
+      "AccuracyScore": 100.0,
+      "FluencyScore": 100.0,
+      "ProsodyScore": 87.8,
+      "CompletenessScore": 100.0,
+      "PronScore": 95.1,
+      "Words": [
+        {
+          "Word": "good",
+          "Offset": 700000,
+          "Duration": 2600000,
+          "AccuracyScore": 100.0,
+          "ErrorType": "None",
+          "Feedback": {
+            "Prosody": {
+              "Break": {
+                "ErrorTypes": ["None"],
+                "BreakLength": 0
+              },
+              "Intonation": {
+                "ErrorTypes": [],
+                "Monotone": {
+                  "Confidence": 0.0
+                }
+              }
+            }
+          }
+        },
+        {
+          "Word": "morning",
+          "Offset": 3400000,
+          "Duration": 5700000,
+          "AccuracyScore": 100.0,
+          "ErrorType": "None"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Score Definitions
+
+| Score | Description |
+|-------|-------------|
+| `AccuracyScore` | How closely phonemes match native speaker pronunciation |
+| `FluencyScore` | How well speech matches native speaker's use of silent breaks |
+| `ProsodyScore` | Naturalness including stress, intonation, speaking speed, rhythm |
+| `CompletenessScore` | Ratio of pronounced words to reference text |
+| `PronScore` | Overall pronunciation quality (weighted aggregate) |
+
+## Error Types
+
+When `EnableMiscue` is true, words include `ErrorType`:
+
+| ErrorType | Description |
+|-----------|-------------|
+| `None` | Word pronounced correctly |
+| `Omission` | Word in reference was skipped |
+| `Insertion` | Extra word not in reference |
+| `Mispronunciation` | Word pronounced incorrectly |
+
+## Complete Example with All Features
+
+```python
+import base64
+import json
+import os
+import requests
+
+def full_pronunciation_assessment(
+    audio_path: str,
+    reference_text: str,
+    language: str = "en-US"
+) -> None:
+    """Full pronunciation assessment with detailed output."""
+    region = os.environ["AZURE_SPEECH_REGION"]
+    api_key = os.environ["AZURE_SPEECH_KEY"]
+
+    url = f"https://{region}.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1"
+
+    pron_params = {
+        "ReferenceText": reference_text,
+        "GradingSystem": "HundredMark",
+        "Granularity": "Word",
+        "Dimension": "Comprehensive",
+        "EnableMiscue": True,
+        "EnableProsodyAssessment": True
+    }
+
+    pron_header = base64.b64encode(
+        json.dumps(pron_params).encode()
+    ).decode()
+
+    headers = {
+        "Ocp-Apim-Subscription-Key": api_key,
+        "Content-Type": "audio/wav; codecs=audio/pcm; samplerate=16000",
+        "Accept": "application/json",
+        "Pronunciation-Assessment": pron_header
+    }
+
+    with open(audio_path, "rb") as f:
+        response = requests.post(
+            url,
+            headers=headers,
+            params={"language": language, "format": "detailed"},
+            data=f
+        )
+
+    response.raise_for_status()
+    result = response.json()
+
+    if result["RecognitionStatus"] != "Success":
+        print(f"Recognition failed: {result['RecognitionStatus']}")
+        return
+
+    nbest = result["NBest"][0]
+
+    print(f"\n=== Overall Scores ===")
+    print(f"Accuracy:     {nbest['AccuracyScore']:.1f}")
+    print(f"Fluency:      {nbest['FluencyScore']:.1f}")
+    print(f"Prosody:      {nbest.get('ProsodyScore', 'N/A')}")
+    print(f"Completeness: {nbest['CompletenessScore']:.1f}")
+    print(f"Overall:      {nbest['PronScore']:.1f}")
+
+    print(f"\n=== Word-Level Analysis ===")
+    for word in nbest["Words"]:
+        error = word.get("ErrorType", "None")
+        accuracy = word.get("AccuracyScore", 0)
+        marker = "" if error == "None" else f" [{error}]"
+        print(f"  {word['Word']}: {accuracy:.1f}{marker}")
+
+# Usage
+full_pronunciation_assessment(
+    "user_speech.wav",
+    "The quick brown fox jumps over the lazy dog.",
+    "en-US"
+)
+```

package/bundled-skills/azure-storage-blob-rust/SKILL.md

@@ -10,16 +10,18 @@ date_added: '2026-02-27'
 
 Client library for Azure Blob Storage — Microsoft's object storage solution for the cloud.
 
+The examples below require a reviewed compatible crate set and replacement of every resource placeholder. Do not use production data for demonstration writes.
+
 ## Installation
 
 ```sh
-cargo add azure_storage_blob azure_identity
+cargo add azure_storage_blob@=1.1.0 azure_identity@=1.0.0 azure_core@=1.1.0
 ```
 
 ## Environment Variables
 
 ```bash
-AZURE_STORAGE_ACCOUNT_NAME=<storage-account-name>
+export AZURE_STORAGE_ACCOUNT_NAME="<storage-account-name>"
 # Endpoint: https://<account>.blob.core.windows.net/
 ```
 
@@ -27,13 +29,12 @@ AZURE_STORAGE_ACCOUNT_NAME=<storage-account-name>
 
 ```rust
 use azure_identity::DeveloperToolsCredential;
-use azure_storage_blob::{BlobClient, BlobClientOptions};
+use azure_core::http::Url;
+use azure_storage_blob::clients::{BlobClient, BlobClientOptions};
 
 let credential = DeveloperToolsCredential::new(None)?;
 let blob_client = BlobClient::new(
-    "https://<account>.blob.core.windows.net/",
-    "container-name",
-    "blob-name",
+    Url::parse("https://<account>.blob.core.windows.net/container-name/blob-name")?,
     Some(credential),
     Some(BlobClientOptions::default()),
 )?;
@@ -53,14 +54,13 @@ let blob_client = BlobClient::new(
 
 ```rust
 use azure_core::http::RequestContent;
+use azure_storage_blob::models::BlobClientUploadOptions;
 
 let data = b"hello world";
 blob_client
     .upload(
         RequestContent::from(data.to_vec()),
-        false,  // overwrite
-        u64::try_from(data.len())?,
-        None,
+        Some(BlobClientUploadOptions::if_not_exists()), // fail rather than overwrite an existing blob
     )
     .await?;
 ```
@@ -69,15 +69,17 @@ blob_client
 
 ```rust
 let response = blob_client.download(None).await?;
-let content = response.into_body().collect_bytes().await?;
-println!("Content: {:?}", content);
+// Check the approved size before fetching; use download_into with a bounded buffer for large data.
+let content = response.body.collect().await?;
+// Process authorized bytes; do not log the payload.
 ```
 
 ### Get Blob Properties
 
 ```rust
 let properties = blob_client.get_properties(None).await?;
-println!("Content-Length: {:?}", properties.content_length);
+// Read the version-specific response header trait; properties is a response, not a content_length field.
+// Do not infer a body/size limit from successful metadata access alone.
 ```
 
 ### Delete Blob
@@ -89,11 +91,11 @@ blob_client.delete(None).await?;
 ## Container Operations
 
 ```rust
-use azure_storage_blob::BlobContainerClient;
+use azure_storage_blob::clients::BlobContainerClient;
+use futures::TryStreamExt;
 
 let container_client = BlobContainerClient::new(
-    "https://<account>.blob.core.windows.net/",
-    "container-name",
+    Url::parse("https://<account>.blob.core.windows.net/container-name")?,
     Some(credential),
     None,
 )?;
@@ -103,15 +105,16 @@ container_client.create(None).await?;
 
 // List blobs
 let mut pager = container_client.list_blobs(None)?;
-while let Some(blob) = pager.try_next().await? {
-    println!("Blob: {}", blob.name);
+while let Some(page) = pager.try_next().await? {
+    let listing = page.into_model()?;
+    // Process this listing page; apply an explicit maximum-page budget.
 }
 ```
 
 ## Best Practices
 
 1. **Use Entra ID auth** — `DeveloperToolsCredential` for dev, `ManagedIdentityCredential` for production
-2. **Specify content length** — required for uploads
+2. **Review overwrite behavior** — the reviewed upload API uses options; if_not_exists prevents unintended replacement
 3. **Use `RequestContent::from()`** — to wrap upload data
 4. **Handle async operations** — use `tokio` runtime
 5. **Check RBAC permissions** — ensure "Storage Blob Data Contributor" role
@@ -121,7 +124,11 @@ while let Some(blob) = pager.try_next().await? {
 For Entra ID auth, assign one of these roles:
 - `Storage Blob Data Reader` — read-only
 - `Storage Blob Data Contributor` — read/write
-- `Storage Blob Data Owner` — full access including RBAC
+- `Storage Blob Data Owner` — blob-data access and supported ownership/ACL management; it does not grant general Azure RBAC role-assignment authority
+
+The example API follows [BlobClient 1.1.0](https://docs.rs/azure_storage_blob/1.1.0/azure_storage_blob/clients/struct.BlobClient.html); earlier releases used different constructor/upload signatures. Use the project’s compatible Azure crate versions rather than mixing them.
+
+The reviewed example set uses `azure_storage_blob 1.1.0` and compatible Azure core/credential crates. Record and commit Cargo.lock; source/API review is not a compiler or live-service test.
 
 ## Reference Links
 
@@ -132,9 +139,10 @@ For Entra ID auth, assign one of these roles:
 | crates.io | https://crates.io/crates/azure_storage_blob |
 
 ## When to Use
-This skill is applicable to execute the workflow or actions described in the overview.
+Use when a Rust application uploads/downloads a specified Azure blob, reads its properties or manages an authorized container.
 
 ## Limitations
-- Use this skill only when the task clearly matches the scope described above.
+- Examples are fragments inside async application code, with compatible pinned Azure crates and the required Tokio/Serde/Futures dependencies; verify the selected version’s API before use. They were reviewed against official source/reference, not compiled or run against a cloud account here.
+- Use an authorized tenant, resource and identity with least privilege. Writes, overwrites, deletes, backup retrieval and account changes require the corresponding scope; cleanup may remove only explicitly identified disposable resources. Bound requests, retries and downloaded bytes, and do not log payloads, credentials or secret values.
 - Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
 - Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

package/bundled-skills/baseline-ui/SKILL.md

@@ -16,7 +16,7 @@ license_source: https://github.com/ibelick/ui-skills/blob/main/LICENSE
 Use this skill when you need quickly deslop UI code by fixing spacing, hierarchy, typography, and small layout issues. Use when the interface needs a fast cleanup or polish pass.
 
 
-Enforces an opinionated UI baseline to prevent AI-generated interface slop.
+Applies an opinionated baseline for a scoped polish pass. Existing product design, accessibility requirements, framework choices and explicit user preferences take precedence; do not migrate the stack or add dependencies just to satisfy this list.
 
 ## How to use
 
@@ -63,7 +63,7 @@ Enforces an opinionated UI baseline to prevent AI-generated interface slop.
 - SHOULD use `ease-out` on entrance
 - NEVER exceed `200ms` for interaction feedback
 - MUST pause looping animations when off-screen
-- SHOULD respect `prefers-reduced-motion`
+- MUST respect `prefers-reduced-motion`
 - NEVER introduce custom easing curves unless explicitly requested
 - SHOULD avoid animating large images or full-screen surfaces
 

package/bundled-skills/bash-scripting/SKILL.md

@@ -22,6 +22,12 @@ Use this workflow when:
 - Developing backup solutions
 - Creating CI/CD scripts
 
+## Scope and execution
+
+Choose the phases that match the user’s task; this document is an index, not an instruction to run every listed skill. Read a selected skill before using it. Respect repository and user constraints. Cloud calls, host configuration, publishing, destructive operations and spending require the applicable authorization; a workflow checklist does not grant it.
+
+The template is a starting point, not a completed script: it does not implement argument parsing or rollback. Validate paths, quote expansions, test in a disposable directory, and make retries bounded and safe for the specific command. Never log credentials or imply strict mode catches every failure.
+
 ## Workflow Phases
 
 ### Phase 1: Script Design
@@ -158,8 +164,10 @@ Use @documentation-templates to document bash script
 #!/usr/bin/env bash
 set -euo pipefail
 
-readonly SCRIPT_NAME=$(basename "$0")
-readonly SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
+SCRIPT_NAME=$(basename -- "$0")
+readonly SCRIPT_NAME
+SCRIPT_DIR=$(cd -- "$(dirname -- "$0")" && pwd)
+readonly SCRIPT_DIR
 
 log() { echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*"; }
 error() { log "ERROR: $*" >&2; exit 1; }

package/bundled-skills/bazel-build-optimization/SKILL.md

@@ -20,7 +20,6 @@ Production patterns for Bazel in large-scale monorepos.
 - Clarify goals, constraints, and required inputs.
 - Apply relevant best practices and validate outcomes.
 - Provide actionable steps and verification.
-- If detailed examples are required, open `resources/implementation-playbook.md`.
 
 ## Use this skill when
 

package/bundled-skills/bdistill-behavioral-xray/SKILL.md

@@ -12,7 +12,7 @@ tools: [claude, cursor, codex, copilot]
 
 # Behavioral X-Ray
 
-Systematically probe an AI model's behavioral patterns and generate a visual report. The AI agent probes *itself* — no API key or external setup needed.
+Systematically probe an AI model's behavioral patterns and generate a visual report. The described workflow probes the host model through its existing session; it still requires the separately installed bdistill package/MCP integration and can consume host-model usage. Do not configure the host automatically just from a request to read this skill.
 
 ## Overview
 
@@ -62,17 +62,17 @@ In any tool with MCP:
 | **tool_use** | When does it call tools vs. answer from knowledge? |
 | **refusal** | Where does it draw safety boundaries? Does it over-refuse? |
 | **formatting** | Lists vs. prose? Code blocks? Length calibration? |
-| **reasoning** | Does it show chain-of-thought? Handle trick questions? |
+| **reasoning** | Does the visible answer provide an appropriate concise explanation and handle trick questions? Do not request, expose or infer hidden chain-of-thought. |
 | **persona** | Identity, tone matching, composure under hostility |
 | **grounding** | Hallucination resistance, fabrication traps, knowledge limits |
 
 ## Output
 
 A styled HTML report showing:
-- Refusal rate, hedge rate, chain-of-thought usage
+- Observed refusal/hedge rates and visible explanation style; no measurement of hidden reasoning
 - Per-dimension breakdown with bar charts
 - Notable response examples with behavioral tags
-- Actionable insights (e.g., "you already show CoT 85% of the time, no need to prompt for it")
+- Actionable insights (e.g., "visible explanations appeared in 25 of 30 recorded responses; this is not a hidden-reasoning measurement")
 
 ## Best Practices
 
@@ -86,6 +86,6 @@ A styled HTML report showing:
 - `@bdistill-knowledge-extraction` - Extract structured domain knowledge from any AI model
 
 ## Limitations
-- Use this skill only when the task clearly matches the scope described above.
+- Self-reported behavior and a 30-question run are exploratory evidence, not an independent benchmark, compliance certification or universal model capability. Keep exact prompts, responses, host/model identity, date and run conditions; compare like-for-like repeated runs.
 - Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
 - Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

package/bundled-skills/bdistill-knowledge-extraction/SKILL.md

@@ -18,7 +18,7 @@ Extract structured, quality-scored domain knowledge from any AI model — in-ses
 
 bdistill turns your AI subscription sessions into a compounding knowledge base. The agent answers targeted domain questions, bdistill structures and quality-scores the responses, and the output accumulates into a searchable, exportable reference dataset.
 
-Adversarial mode challenges the agent's claims — forcing evidence, corrections, and acknowledged limitations — producing validated knowledge entries.
+Adversarial mode challenges the agent's claims — forcing evidence, corrections, and acknowledged limitations — producing model-generated candidates for independent source review; adversarial self-correction is not external validation.
 
 ## When to Use This Skill
 
@@ -65,12 +65,14 @@ Structured reference JSONL — not training data:
   "category": "cardiology",
   "tags": ["mechanistic", "evidence-based"],
   "quality_score": 0.73,
-  "confidence": 1.08,
-  "validated": true,
-  "source_model": "Claude Sonnet 4"
+  "confidence": 0.73,
+  "validated": false,
+  "source_model": "<actual host model recorded at run time>"
 }
 ```
 
+The numeric scores are illustrative, uncalibrated metadata; independent source verification is absent in this example.
+
 ## Tabular ML Data Generation
 
 Generate structured training data for traditional ML models:
@@ -97,7 +99,7 @@ bdistill extract --domain medical --model qwen3:4b
 
 - In-session extraction uses your existing subscription — no additional API keys
 - Local extraction runs entirely on your machine via Ollama
-- No data is sent to external services
+- In-session extraction uses the host provider and its data policy; it is not offline. A genuinely local Ollama endpoint keeps inference local, but downloading models/installing packages uses the network. Verify endpoints and approved data processing before use
 - Output is reference data, not LLM training format
 
 ## Related Skills
@@ -105,6 +107,7 @@ bdistill extract --domain medical --model qwen3:4b
 - `@bdistill-behavioral-xray` - X-ray a model's behavioral patterns
 
 ## Limitations
-- Use this skill only when the task clearly matches the scope described above.
+- Generated medical, legal, financial or security content needs dated independent authoritative evidence and domain review; quality_score/confidence are not clinical/legal accuracy or calibrated probabilities. Do not put personal records into generated corpora or use synthetic labels as real patient outcomes.
+- Installing MCP or downloading models is separate from extraction; use a reviewed environment and respect host/configuration authorization.
 - Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
 - Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

package/bundled-skills/beautiful-prose/SKILL.md

@@ -5,7 +5,6 @@ risk: none
 source: community
 date_added: "2026-09-04"
 ---
-
 # Beautiful Prose (Claude Skill)
 
 A hard-edged writing skill for producing timeless, forceful English prose without modern AI tics.
@@ -194,7 +193,7 @@ Fail the output if any are true:
 
 ## Tests
 
-See `references/test-cases.md`.
+Use the inline good/bad examples and manual lint checklist above. This catalog copy has no automated style test suite.
 
 ## Limitations
 - Use this skill only when the task clearly matches the scope described above.

package/bundled-skills/bevy-ecs-expert/SKILL.md

@@ -23,7 +23,7 @@ A guide to building high-performance game logic using Bevy's data-oriented ECS a
 
 ### 1. Defining Components
 
-Use simple structs for data. Derive `Component` and `Reflect`.
+Use simple structs for data. Import `bevy::prelude::*`; add Reflect only when reflection/inspection is needed. The snippets are alternatives and do not duplicate Player/Velocity definitions in one scope.
 
 ```rust
 #[derive(Component, Reflect, Default)]
@@ -47,8 +47,8 @@ fn movement_system(
     mut query: Query<(&mut Transform, &Velocity), With<Player>>,
 ) {
     for (mut transform, velocity) in &mut query {
-        transform.translation.x += velocity.x * time.delta_seconds();
-        transform.translation.y += velocity.y * time.delta_seconds();
+        transform.translation.x += velocity.x * time.delta_secs();
+        transform.translation.y += velocity.y * time.delta_secs();
     }
 }
 ```
@@ -58,7 +58,7 @@ fn movement_system(
 Use `Resource` for global data (score, game state).
 
 ```rust
-#[derive(Resource)]
+#[derive(Resource, Default)]
 struct GameState {
     score: u32,
 }
@@ -68,6 +68,8 @@ fn score_system(mut game_state: ResMut<GameState>) {
 }
 ```
 
+The toy score_system increments each Update; use gameplay events or an explicit timer for meaningful scoring, rather than implying frame-rate-independent score behavior.
+
 ### 4. Scheduling Systems
 
 Add systems to the `App` builder, defining execution order if needed.
@@ -128,14 +130,14 @@ fn enemy_behavior(
 - ✅ **Do:** Prefer `Res` over `ResMut` when read-only access is sufficient to allow parallel execution.
 - ✅ **Do:** Use `Bundle` to spawn complex entities atomically.
 - ❌ **Don't:** Store heavy logic inside Components; keep them as pure data.
-- ❌ **Don't:** Use `RefCell` or interior mutability inside components; let the ECS handle borrowing.
+- ❌ **Don't:** Use `RefCell` or interior mutability inside components; prefer normal ECS borrowing; any interior-mutability design still needs valid Send/Sync and a clear synchronization reason.
 
 ## Troubleshooting
 
 **Problem:** System panic with "Conflict" error.
-**Solution:** You are likely trying to access the same component mutably in two systems running in parallel. Use `.chain()` to order them or split the logic.
+**Solution:** The scheduler normally orders conflicting systems. Bevy B0001 often concerns incompatible queries inside one system; use disjoint With/Without filters or ParamSet as appropriate. Chaining two systems does not repair conflicting parameters inside a system. See [Bevy B0001](https://bevy.org/learn/errors/b0001/).
 
 ## Limitations
-- Use this skill only when the task clearly matches the scope described above.
+- Pin the project’s Bevy version and check its migration/API guide. Current examples use delta_secs and required components; older Bevy versions may differ. Enemy/Dead are application-owned component markers and player.png is an application asset, not a bundled file. No engine compilation/performance benchmark is claimed here.
 - Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
 - Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.