From 8953628eee48c4b8b54e5937ebf1bfd229e607d2 Mon Sep 17 00:00:00 2001 From: promptadmin Date: Sat, 8 Aug 2026 15:31:36 +0000 Subject: [PATCH 001/101] [upstream-sync] .github/ISSUE_TEMPLATE/bug_report.yml from K-Dense-AI/scientific-agent-skills@991bd993 [unknown] --- .../.github/ISSUE_TEMPLATE/bug_report.yml | 108 ++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 upstream/K-Dense-AI-scientific-agent-skills/catalogue/.github/ISSUE_TEMPLATE/bug_report.yml diff --git a/upstream/K-Dense-AI-scientific-agent-skills/catalogue/.github/ISSUE_TEMPLATE/bug_report.yml b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 00000000..b21dd4ce --- /dev/null +++ b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,108 @@ +--- +title: "Bug Report" +task: "" +lineage_type: import +upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/991bd993/.github/ISSUE_TEMPLATE/bug_report.yml +upstream_sha: 991bd993 +imported_at: 2026-08-08 +prompt_class: unknown +upstream_changes: accepted +author: upstream +validated: false +--- + +name: Bug report +description: A skill or repository tool behaves incorrectly — wrong output, broken script, failing install, or instructions an agent cannot follow. +title: "[Bug]: " +labels: ["bug", "needs-triage"] +body: + - type: markdown + attributes: + value: | + Thanks for reporting this. Please do **not** use this form for security + vulnerabilities — use [private vulnerability reporting](https://github.com/K-Dense-AI/scientific-agent-skills/security/advisories/new) + instead, as described in [SECURITY.md](https://github.com/K-Dense-AI/scientific-agent-skills/blob/main/SECURITY.md). + + - type: dropdown + id: area + attributes: + label: Area + description: Which part of the repository is affected? + options: + - A skill under skills/ + - Repository tooling (scan_skills.py, tests, CI workflows) + - Documentation (README, CONTRIBUTING, AGENTS) + - Not sure + validations: + required: true + + - type: input + id: skill + attributes: + label: Skill name + description: The skill directory name, exactly as it appears under `skills/`. Leave blank if this is not skill-specific. + placeholder: scanpy + validations: + required: false + + - type: textarea + id: what-happened + attributes: + label: What happened + description: What did the skill or tool actually do? + placeholder: The skill's example call to sc.pp.neighbors() fails with a TypeError. + validations: + required: true + + - type: textarea + id: expected + attributes: + label: What you expected instead + validations: + required: true + + - type: textarea + id: reproduce + attributes: + label: Steps to reproduce + description: The smallest sequence that triggers it. Include the prompt you gave the agent, if relevant. + placeholder: | + 1. Load the `scanpy` skill in Claude Code + 2. Ask: "cluster my AnnData object" + 3. Run the code the agent produces + 4. See the error below + validations: + required: true + + - type: textarea + id: logs + attributes: + label: Error output + description: Paste the traceback or scanner output. This is rendered as a code block, so no backticks are needed. + render: shell + validations: + required: false + + - type: textarea + id: environment + attributes: + label: Environment + description: Skill behavior varies by agent host and model, so please tell us where you saw this. + value: | + - Agent host (Claude Code, Cursor, Codex, other): + - Model: + - Repository version or commit: + - Python version: + - Operating system: + validations: + required: true + + - type: checkboxes + id: checks + attributes: + label: Before submitting + options: + - label: I searched existing issues and this is not a duplicate. + required: true + - label: This is not a security vulnerability. (Those go through private reporting.) + required: true -- 2.54.0 From 14dd2afca6d6cad04c487e57f33a7023176f2744 Mon Sep 17 00:00:00 2001 From: promptadmin Date: Sat, 8 Aug 2026 15:31:44 +0000 Subject: [PATCH 002/101] [upstream-sync] .github/ISSUE_TEMPLATE/config.yml from K-Dense-AI/scientific-agent-skills@991bd993 [unknown] --- .../.github/ISSUE_TEMPLATE/config.yml | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 upstream/K-Dense-AI-scientific-agent-skills/catalogue/.github/ISSUE_TEMPLATE/config.yml diff --git a/upstream/K-Dense-AI-scientific-agent-skills/catalogue/.github/ISSUE_TEMPLATE/config.yml b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..e1cdbf46 --- /dev/null +++ b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,27 @@ +--- +title: "Config" +task: "" +lineage_type: import +upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/991bd993/.github/ISSUE_TEMPLATE/config.yml +upstream_sha: 991bd993 +imported_at: 2026-08-08 +prompt_class: unknown +upstream_changes: accepted +author: upstream +validated: false +--- + +blank_issues_enabled: false +contact_links: + - name: Report a security vulnerability + url: https://github.com/K-Dense-AI/scientific-agent-skills/security/advisories/new + about: Do not open a public issue. Use private vulnerability reporting so the report stays confidential until a fix ships. See SECURITY.md. + - name: Contributing guide + url: https://github.com/K-Dense-AI/scientific-agent-skills/blob/main/CONTRIBUTING.md + about: Read this before proposing a skill change — skill format, validation, tests, and the pull request checklist. + - name: Agent Skills specification + url: https://agentskills.io/specification + about: The open specification every skill in this repository follows. + - name: K-Dense documentation + url: https://k-dense.ai + about: Product documentation and general questions about K-Dense. -- 2.54.0 From 2bee12d321c99b6b752ebf2bca85ed55abcc264d Mon Sep 17 00:00:00 2001 From: promptadmin Date: Sat, 8 Aug 2026 15:31:52 +0000 Subject: [PATCH 003/101] [upstream-sync] .github/ISSUE_TEMPLATE/new_skill_request.yml from K-Dense-AI/scientific-agent-skills@991bd993 [unknown] --- .../ISSUE_TEMPLATE/new_skill_request.yml | 103 ++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 upstream/K-Dense-AI-scientific-agent-skills/catalogue/.github/ISSUE_TEMPLATE/new_skill_request.yml diff --git a/upstream/K-Dense-AI-scientific-agent-skills/catalogue/.github/ISSUE_TEMPLATE/new_skill_request.yml b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/.github/ISSUE_TEMPLATE/new_skill_request.yml new file mode 100644 index 00000000..78c4cdac --- /dev/null +++ b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/.github/ISSUE_TEMPLATE/new_skill_request.yml @@ -0,0 +1,103 @@ +--- +title: "New Skill Request" +task: "" +lineage_type: import +upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/991bd993/.github/ISSUE_TEMPLATE/new_skill_request.yml +upstream_sha: 991bd993 +imported_at: 2026-08-08 +prompt_class: unknown +upstream_changes: accepted +author: upstream +validated: false +--- + +name: New skill request +description: Propose a skill for a scientific package, database, platform, workflow, or research method that the library does not cover yet. +title: "[New skill]: " +labels: ["enhancement", "skill-request", "needs-triage"] +body: + - type: markdown + attributes: + value: | + Check the [skill list in the README](https://github.com/K-Dense-AI/scientific-agent-skills#readme) + first — the library already ships a large number of skills. If you plan to + write this skill yourself, [CONTRIBUTING.md](https://github.com/K-Dense-AI/scientific-agent-skills/blob/main/CONTRIBUTING.md) + has the required format and validation steps. + + - type: input + id: name + attributes: + label: Proposed skill name + description: Lowercase letters, numbers, and single hyphens only — this becomes the directory name under `skills/`. + placeholder: alphafold-db + validations: + required: true + + - type: dropdown + id: category + attributes: + label: Category + options: + - Scientific package or library + - Database or public data resource + - Platform, service, or API + - Analysis workflow or research method + - Laboratory instrument or hardware + - Other + validations: + required: true + + - type: textarea + id: what + attributes: + label: What the skill would do + description: What should an agent be able to accomplish with it that it cannot do reliably today? + validations: + required: true + + - type: textarea + id: when + attributes: + label: When an agent should use it + description: The situations that should trigger this skill. This becomes the "when to use" half of the skill description. + validations: + required: true + + - type: textarea + id: docs + attributes: + label: Official documentation and sources + description: Links to the package docs, API reference, publication, or database homepage a skill author would need. + placeholder: | + - Docs: https://... + - API reference: https://... + - Paper: https://doi.org/... + validations: + required: true + + - type: textarea + id: credentials + attributes: + label: Credentials or access requirements + description: Does it need an API key, licence, registration, or institutional access? Name the environment variables if you know them. + validations: + required: false + + - type: dropdown + id: contribute + attributes: + label: Would you like to write this skill? + options: + - "Yes — I plan to open a pull request" + - "Maybe, with some guidance" + - "No, I am requesting it" + validations: + required: true + + - type: checkboxes + id: checks + attributes: + label: Before submitting + options: + - label: I checked the README skill list and this skill does not already exist. + required: true -- 2.54.0 From 4f4315cfce952a14e5e70278194fc58d97ebcf4b Mon Sep 17 00:00:00 2001 From: promptadmin Date: Sat, 8 Aug 2026 15:31:59 +0000 Subject: [PATCH 004/101] [upstream-sync] .github/ISSUE_TEMPLATE/skill_improvement.yml from K-Dense-AI/scientific-agent-skills@991bd993 [unknown] --- .../ISSUE_TEMPLATE/skill_improvement.yml | 81 +++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 upstream/K-Dense-AI-scientific-agent-skills/catalogue/.github/ISSUE_TEMPLATE/skill_improvement.yml diff --git a/upstream/K-Dense-AI-scientific-agent-skills/catalogue/.github/ISSUE_TEMPLATE/skill_improvement.yml b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/.github/ISSUE_TEMPLATE/skill_improvement.yml new file mode 100644 index 00000000..3282b0a5 --- /dev/null +++ b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/.github/ISSUE_TEMPLATE/skill_improvement.yml @@ -0,0 +1,81 @@ +--- +title: "Skill Improvement" +task: "" +lineage_type: import +upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/991bd993/.github/ISSUE_TEMPLATE/skill_improvement.yml +upstream_sha: 991bd993 +imported_at: 2026-08-08 +prompt_class: unknown +upstream_changes: accepted +author: upstream +validated: false +--- + +name: Improve an existing skill +description: An existing skill is outdated, unclear, or incomplete — stale API, missing workflow, weak examples, or a description that triggers at the wrong time. +title: "[Improve]: " +labels: ["enhancement", "needs-triage"] +body: + - type: input + id: skill + attributes: + label: Skill name + description: The skill directory name, exactly as it appears under `skills/`. + placeholder: transformers + validations: + required: true + + - type: dropdown + id: kind + attributes: + label: What needs improving + multiple: true + options: + - Outdated API or deprecated calls + - Missing workflow or capability + - Examples are wrong, untested, or too thin + - Instructions are ambiguous for an agent + - Description triggers too often or not often enough + - Missing or broken references + - Missing tests + - Other + validations: + required: true + + - type: textarea + id: current + attributes: + label: Current behavior + description: What does the skill say or do today? Quote the relevant part of `SKILL.md` or a reference file, with the file path. + validations: + required: true + + - type: textarea + id: proposed + attributes: + label: Proposed change + description: What should it say or do instead? + validations: + required: true + + - type: textarea + id: evidence + attributes: + label: Supporting sources + description: Upstream release notes, migration guides, or docs that show the current content is out of date. + placeholder: | + - Changelog: https://... + - Migration guide: https://... + validations: + required: false + + - type: dropdown + id: contribute + attributes: + label: Would you like to make this change? + options: + - "Yes — I plan to open a pull request" + - "Maybe, with some guidance" + - "No, I am reporting it" + validations: + required: true -- 2.54.0 From a03dc31233553dbae135de095cf0d736daa239c6 Mon Sep 17 00:00:00 2001 From: promptadmin Date: Sat, 8 Aug 2026 15:32:07 +0000 Subject: [PATCH 005/101] [upstream-sync] .github/PULL_REQUEST_TEMPLATE.md from K-Dense-AI/scientific-agent-skills@991bd993 [unknown] --- .../.github/PULL_REQUEST_TEMPLATE.md | 81 +++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 upstream/K-Dense-AI-scientific-agent-skills/catalogue/.github/PULL_REQUEST_TEMPLATE.md diff --git a/upstream/K-Dense-AI-scientific-agent-skills/catalogue/.github/PULL_REQUEST_TEMPLATE.md b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..afbc1b9b --- /dev/null +++ b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,81 @@ +--- +title: "Summary" +task: "" +lineage_type: import +upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/991bd993/.github/PULL_REQUEST_TEMPLATE.md +upstream_sha: 991bd993 +imported_at: 2026-08-08 +prompt_class: unknown +upstream_changes: accepted +author: upstream +validated: false +--- + +# Summary + + + +## Type of change + + + +- [ ] New skill +- [ ] Update to an existing skill +- [ ] Tests +- [ ] Repository tooling or CI +- [ ] Documentation +- [ ] Other: + +## Skills touched + + + +- + +## How this was tested + + + +``` +uv run skills-ref validate ./skills/ +uv run --with pytest python -m pytest tests/ -q +``` + +## Related issues and references + + + +--- + +## Checklist + +Drawn from the [Pull Request Checklist](https://github.com/K-Dense-AI/scientific-agent-skills/blob/main/CONTRIBUTING.md#pull-request-checklist) in CONTRIBUTING.md. Items that do not apply to this PR can be left unchecked with a short note. + +**Skill format** + +- [ ] The skill directory name and the `name` frontmatter match exactly. +- [ ] The skill directory contains only `SKILL.md`, `references/`, `scripts/`, and `assets/` — no `tests/` directory and no `test_*.py` files. +- [ ] `SKILL.md` has valid YAML frontmatter and a Markdown body. +- [ ] Only the six spec-defined top-level fields are present; everything else lives under `metadata`. +- [ ] `metadata` is a block mapping, not single-line JSON, and scalar values are quoted where needed. +- [ ] Any `metadata.openclaw` or `metadata.hermes` block is a nested mapping, not a JSON string. +- [ ] `metadata.version` exists, is quoted, and is bumped if an existing skill changed. +- [ ] The `description` says both what the skill does and when an agent should use it. + +**Validation and tests** + +- [ ] `uv run skills-ref validate ./skills/` passes. +- [ ] Tests live in `tests//`, and any new `scripts/` skill has a `[skills.]` entry in `tests/skill-requirements.toml`. +- [ ] Relevant test suites pass, or the failures are explained below. +- [ ] Security scanner results are clean or explained in this PR. + +**Content and safety** + +- [ ] Examples and scripts were tested, or are clearly marked as illustrative. +- [ ] No secrets, credentials, private data, or unsafe instructions are included. +- [ ] Credentials the skill needs are named in `compatibility` and declared in `metadata.openclaw.envVars`. +- [ ] Relevant official documentation is linked where useful. + +## Notes for reviewers + + -- 2.54.0 From a337b88460d451ef7a0b150fd0d511c484e738ba Mon Sep 17 00:00:00 2001 From: promptadmin Date: Sat, 8 Aug 2026 15:32:15 +0000 Subject: [PATCH 006/101] [upstream-sync] .github/workflows/skill-spec-validation.yml from K-Dense-AI/scientific-agent-skills@991bd993 [prompt] --- .../workflows/skill-spec-validation.yml | 163 ++++++++++++++++++ 1 file changed, 163 insertions(+) create mode 100644 upstream/K-Dense-AI-scientific-agent-skills/.github/workflows/skill-spec-validation.yml diff --git a/upstream/K-Dense-AI-scientific-agent-skills/.github/workflows/skill-spec-validation.yml b/upstream/K-Dense-AI-scientific-agent-skills/.github/workflows/skill-spec-validation.yml new file mode 100644 index 00000000..ad95c8ed --- /dev/null +++ b/upstream/K-Dense-AI-scientific-agent-skills/.github/workflows/skill-spec-validation.yml @@ -0,0 +1,163 @@ +--- +title: "Skill Spec Validation" +task: "" +lineage_type: import +upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/991bd993/.github/workflows/skill-spec-validation.yml +upstream_sha: 991bd993 +imported_at: 2026-08-08 +prompt_class: prompt +upstream_changes: accepted +author: upstream +validated: false +--- + +name: Skill Spec Validation + +on: + pull_request: + paths: + - "skills/**" + - "pyproject.toml" + - "uv.lock" + - ".github/workflows/skill-spec-validation.yml" + push: + branches: + - main + paths: + - "skills/**" + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: skill-spec-validation-${{ github.ref }} + cancel-in-progress: true + +jobs: + validate: + name: Validate skills against the Agent Skills spec + runs-on: ubuntu-latest + timeout-minutes: 15 + + steps: + - name: Checkout + uses: actions/checkout@v6 + + - name: Set up uv + uses: astral-sh/setup-uv@v8.0.0 + with: + enable-cache: true + cache-dependency-glob: uv.lock + python-version: "3.13" + + - name: Install dependencies + run: uv sync --python 3.13 + + # The reference validator from https://agentskills.io/specification. It checks the + # closed set of allowed frontmatter fields, name rules (incl. directory match), + # description/compatibility length limits, and parses frontmatter with strictyaml + # -- which rejects JSON-style flow mappings such as `metadata: {"version": "1.0"}`. + - name: skills-ref validate + run: | + set -uo pipefail + fail=0 + for d in skills/*/; do + if ! out=$(uv run skills-ref validate "$d" 2>&1); then + fail=1 + echo "::error file=${d}SKILL.md::$(echo "$out" | tail -n +2 | tr '\n' ' ')" + echo "FAIL $d" + echo "$out" | sed 's/^/ /' + fi + done + echo "Validated $(ls -d skills/*/ | wc -l) skills." + exit $fail + + # Rules the reference validator does not enforce: this repo's metadata.version + # requirement (see AGENTS.md), plus spec constraints skills-ref accepts but the + # spec text requires -- allowed-tools must be a space-separated string, and + # metadata values must be strings apart from the host-manifest blocks that have + # to stay nested objects (see NESTED_OK below). + - name: Repo and spec rules skills-ref does not check + run: | + uv run --with pyyaml python - <<'PY' + import re + import sys + from pathlib import Path + import yaml + + # Host manifest blocks that must stay nested mappings. OpenClaw's + # resolveOpenClawManifestBlock() requires `typeof candidate === "object"`, so + # encoding these as JSON strings silently disables its gating and credential + # injection. Nested mappings still pass `skills-ref validate`. + NESTED_OK = {"openclaw", "hermes"} + + # Requires the closing delimiter on its own line. A naive split("---") would + # happily re-split at a `---` accidentally glued to the last frontmatter value. + FM_RE = re.compile(r"\A---\n(.*?)\n---\n", re.S) + + errors, warnings = [], [] + for d in sorted(Path("skills").iterdir()): + if not d.is_dir(): + continue + md = d / "SKILL.md" + if not md.exists(): + errors.append(f"{d}: missing SKILL.md") + continue + text = md.read_text() + m_fm = FM_RE.match(text) + if not m_fm: + errors.append( + f"{md}: frontmatter must open with `---` and close with `---` " + f"on its own line" + ) + continue + fm = yaml.safe_load(m_fm.group(1)) + + at = fm.get("allowed-tools") + if at is not None: + if not isinstance(at, str): + errors.append( + f"{md}: allowed-tools must be a space-separated string, " + f"got {type(at).__name__}" + ) + elif "," in at: + errors.append( + f"{md}: allowed-tools must be space-separated, not " + f"comma-separated: {at!r}" + ) + + m = fm.get("metadata") + if not isinstance(m, dict): + errors.append(f"{md}: missing a `metadata` mapping (see AGENTS.md)") + else: + if "version" not in m: + errors.append(f"{md}: metadata.version is required (see AGENTS.md)") + for k, v in m.items(): + if k in NESTED_OK: + if not isinstance(v, dict): + errors.append( + f"{md}: metadata.{k} must stay a nested mapping, got " + f"{type(v).__name__} -- a JSON string silently disables " + f"host gating and credential injection" + ) + continue + if isinstance(v, str): + continue + errors.append( + f"{md}: metadata.{k} must be a string, got {type(v).__name__} " + f"-- quote it (versions and dates especially)" + ) + + lines = text.count("\n") + 1 + if lines > 500: + warnings.append(f"{md}: {lines} lines; the spec recommends under 500") + + for w in warnings: + print(f"::warning file={w.split(':')[0]}::{w}") + for e in errors: + print(f"::error file={e.split(':')[0]}::{e}") + print(f"FAIL {e}") + print(f"\n{len(errors)} error(s), {len(warnings)} warning(s).") + sys.exit(1 if errors else 0) + PY -- 2.54.0 From 3d76dabac6ae23eb1fa10211f93be343451ee3a4 Mon Sep 17 00:00:00 2001 From: promptadmin Date: Sat, 8 Aug 2026 15:32:25 +0000 Subject: [PATCH 007/101] [upstream-sync] .github/workflows/skill-tests.yml from K-Dense-AI/scientific-agent-skills@991bd993 [unknown] --- .../.github/workflows/skill-tests.yml | 116 ++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 upstream/K-Dense-AI-scientific-agent-skills/catalogue/.github/workflows/skill-tests.yml diff --git a/upstream/K-Dense-AI-scientific-agent-skills/catalogue/.github/workflows/skill-tests.yml b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/.github/workflows/skill-tests.yml new file mode 100644 index 00000000..13393b43 --- /dev/null +++ b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/.github/workflows/skill-tests.yml @@ -0,0 +1,116 @@ +--- +title: "Skill Tests" +task: "" +lineage_type: import +upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/991bd993/.github/workflows/skill-tests.yml +upstream_sha: 991bd993 +imported_at: 2026-08-08 +prompt_class: unknown +upstream_changes: accepted +author: upstream +validated: false +--- + +name: Skill Tests + +on: + pull_request: + paths: + - "skills/**" + - "tests/**" + - "pyproject.toml" + - "uv.lock" + - ".github/workflows/skill-tests.yml" + push: + branches: + - main + paths: + - "skills/**" + - "tests/**" + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: skill-tests-${{ github.ref }} + cancel-in-progress: true + +jobs: + contract: + name: Repo-wide contract and coverage guard + runs-on: ubuntu-latest + timeout-minutes: 15 + + steps: + - name: Checkout + uses: actions/checkout@v6 + + - name: Set up uv + uses: astral-sh/setup-uv@v8.0.0 + with: + enable-cache: true + cache-dependency-glob: uv.lock + python-version: "3.13" + + - name: Install dependencies + run: uv sync --python 3.13 + + # tests/_meta checks every skill against the shared structural contract + # (frontmatter, SKILL.md length, local links, scripts parse, no shipped + # bytecode, no hardcoded local paths, ...) and enforces the repo rule that + # a skill shipping scripts/ has a suite under tests/ and an entry in + # tests/skill-requirements.toml. It imports no skill code and needs no + # scientific packages, so it runs in seconds on every pull request. + - name: Structural contract and coverage + run: uv run --python 3.13 python -m pytest tests/_meta -q + + suites: + name: Standard-library-only skill suites + runs-on: ubuntu-latest + timeout-minutes: 30 + needs: contract + + steps: + - name: Checkout + uses: actions/checkout@v6 + + - name: Set up uv + uses: astral-sh/setup-uv@v8.0.0 + with: + enable-cache: true + cache-dependency-glob: uv.lock + python-version: "3.13" + + # The skills whose bundled tooling is standard-library only -- read from + # `packages = []` in tests/skill-requirements.toml, so the list needs no + # separate maintenance. Each still gets a clean throwaway environment. + # + # The full `--isolated` sweep across every skill is deliberately NOT run + # here: it builds ~100 environments including torch, qiskit, and scanpy, + # and several skills need CUDA, a JDK, or a MATLAB install that CI does + # not have. Run it locally or on a schedule: + # python tests/run_all.py --isolated + - name: Select standard-library-only skills + id: select + run: | + set -euo pipefail + SKILLS=$(python3 - <<'PY' + import pathlib, tomllib + manifest = tomllib.loads( + pathlib.Path("tests/skill-requirements.toml").read_text() + ) + names = sorted( + name + for name, entry in manifest["skills"].items() + if not entry.get("packages") and "python" not in entry + and (pathlib.Path("tests") / name).is_dir() + ) + print(" ".join(names)) + PY + ) + echo "Selected: $SKILLS" + echo "skills=$SKILLS" >> "$GITHUB_OUTPUT" + + - name: Run suites, one environment each + run: uv run --python 3.13 python tests/run_all.py --isolated ${{ steps.select.outputs.skills }} -- 2.54.0 From 49206d9ec7210123c9016592f70addbef0080924 Mon Sep 17 00:00:00 2001 From: promptadmin Date: Sat, 8 Aug 2026 15:32:36 +0000 Subject: [PATCH 008/101] [upstream-sync] AGENTS.md from K-Dense-AI/scientific-agent-skills@991bd993 [unknown] --- .../catalogue/AGENTS.md | 391 ++++++++++++++++++ 1 file changed, 391 insertions(+) create mode 100644 upstream/K-Dense-AI-scientific-agent-skills/catalogue/AGENTS.md diff --git a/upstream/K-Dense-AI-scientific-agent-skills/catalogue/AGENTS.md b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/AGENTS.md new file mode 100644 index 00000000..cf7f2fd3 --- /dev/null +++ b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/AGENTS.md @@ -0,0 +1,391 @@ +--- +title: "Repository Guidance" +task: "" +lineage_type: import +upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/991bd993/AGENTS.md +upstream_sha: 991bd993 +imported_at: 2026-08-08 +prompt_class: unknown +upstream_changes: accepted +author: upstream +validated: false +--- + +# Repository Guidance + +This repository is a collection of Agent Skills for science and research. Every skill lives in its +own directory under `skills/` and must conform to the open +[Agent Skills specification](https://agentskills.io/specification). + +Read this file before creating or changing a skill. `CONTRIBUTING.md` covers the same ground at +more length, plus the pull-request process. + +## What belongs here + +**In scope:** a narrow skill for one scientific package, database, platform, or research workflow — +`scanpy`, `depmap`, `benchling-integration`, `experimental-design`. + +**Out of scope**, and routinely declined: + +- General software-engineering or coding-judgment skills — they compete for selection on every task. +- General infrastructure with a scientific example bolted on (a vector database, a cloud SDK) — + accepting one implies carrying every competitor. +- Broad "orchestrator" skills that route to other skills — they overlap every specialist by design. +- A second provider for a service an existing skill already reaches. + +The general-purpose skills that do exist are narrow output-format helpers (`docx`, `pdf`, `pptx`, +`generate-image`, `markdown-mermaid-writing`). They are not precedent for broadening scope. + +## Layout + +```text +skills// +├── SKILL.md # required +├── references/ # optional: long documentation, loaded only when needed +├── scripts/ # optional: executable helpers +└── assets/ # optional: templates and static resources +``` + +Only `SKILL.md` is required. Reference other files with relative paths from the skill root, kept +one level deep. + +**Tests never live under `skills/`.** A skill directory ships only what an agent loads. Checks for a +skill's scripts and structure go in the repository-level suite instead: + +```text +tests// # same name as the skill directory +├── test_scripts.py +└── fixtures/ # optional test data +``` + +**Diagrams never live under `skills/` either.** Every skill has one generated workflow diagram at +`docs/images/.png`, produced by `scripts/generate_skill_image.py` and kept in step with +the skill's documentation — see [Skill diagrams](#skill-diagrams). + +Tests reach their skill through an explicit anchor, never a relative walk: + +```python +SKILL_ROOT = Path(__file__).resolve().parents[2] / "skills" / "" +``` + +## Creating a skill + +1. Create `skills//` — **the directory name is the skill name** and must equal frontmatter + `name`. +2. Write `SKILL.md` from the template below. Start at `metadata.version: "1.0"`. +3. Add `references/`, `scripts/`, or `assets/` only when they earn their place. +4. Run the commands and code you document. Scope claims to the release you actually tested + ("targets stable GeoPandas 1.1.4"), and mark anything untested as illustrative. +5. If the skill ships `scripts/`, put their tests in **`tests//`** — never in the skill + directory. Fixtures go in `tests//fixtures/`. +6. Validate and scan (below). +7. Generate the skill's diagram — a new skill without `docs/images/.png` is incomplete: + + ```bash + uv run python scripts/generate_skill_image.py --skill + ``` + +```markdown +--- +name: skill-name +description: What the skill does and when an agent should use it, including the terms that should trigger it. +license: MIT +compatibility: Requires Python 3.12+ with installed. Needs network access. +metadata: + version: "1.0" + skill-author: Your Name +--- + +# Skill Title + +## When to use + +Use this skill when... + +## Workflow + +1. ... + +## Examples + +... +``` + +## Updating a skill + +1. Read the current `SKILL.md` and its supporting files first. +2. Check upstream docs — APIs move, and the skill may be pinned to an older release. +3. Make the smallest useful change. +4. **Bump `metadata.version` in the same change**: minor for normal improvements (`"1.2"` → + `"1.3"`), major only for a breaking change or substantial redesign (`"1.9"` → `"2.0"`). +5. Re-run any example, command, or script you touched, plus `tests//` if that suite exists. + Suites check that `metadata.version` is present and quoted, not what it equals, so a version bump + never needs a matching test edit. +6. **Regenerate the diagram in the same change** whenever the edit changes what the skill does or + how its workflow runs — the picture is generated from `SKILL.md` and `references/`, so it goes + stale silently. The command overwrites `docs/images/.png` in place: + + ```bash + uv run python scripts/generate_skill_image.py --skill + ``` + + A typo fix, a link repair, or a version bump alone does not need a new image. + +## Frontmatter + +`SKILL.md` starts with YAML frontmatter. **Only these six fields are allowed** — the spec defines a +closed set, and any other top-level key is a validation error: + +| Field | Required | Constraints | +| --- | --- | --- | +| `name` | Yes | 1–64 chars, lowercase letters/digits/hyphens only, no leading, trailing, or consecutive hyphens, and **must equal the directory name**. | +| `description` | Yes | 1–1024 chars. Say what the skill does *and* when to use it, with the keywords that should trigger it. Write it in third person. | +| `license` | No | License name, or a reference to a bundled license file. | +| `compatibility` | No | Max 500 chars. Environment requirements only — omit it if the skill has none. | +| `allowed-tools` | No | A **space-separated string**, e.g. `Read Write Edit Bash`. Not a YAML list, not comma-separated. | +| `metadata` | No | Mapping of string keys to **string** values, except the host manifest blocks below. Required here: `metadata.version`. | + +Put anything else — authorship, upstream versions, review dates, client-specific config — inside +`metadata`, never at the top level. In particular, Hermes' top-level +`required_environment_variables` cannot be used here: it fails the validator and, because +`strictyaml` rejects the whole document, takes `name` and `description` down with it. Declare +credentials in `compatibility` and `metadata.openclaw.envVars` instead. + +### Write block-style YAML, not JSON flow style + +The reference validator parses frontmatter with `strictyaml`, which **rejects JSON-style flow +mappings and sequences**. A flow mapping does not merely fail one check: the whole frontmatter +fails to parse, so `name` and `description` become unreadable and the skill will not register. + +```yaml +# Wrong -- breaks the validator +metadata: {"version": "1.1", "skill-author": "K-Dense Inc."} + +# Right +metadata: + version: "1.1" + skill-author: K-Dense Inc. +``` + +### Quote `metadata` scalars + +Quote values that would otherwise be parsed as a number, boolean, or date — `version: "1.0"`, +`last-reviewed: "2026-07-23"` — so they stay strings as the spec requires. + +### Host manifest blocks stay nested mappings + +`metadata.openclaw` and `metadata.hermes` are the documented exception: keep them as **nested +mappings**, not JSON strings. OpenClaw's `resolveOpenClawManifestBlock()` requires +`typeof candidate === "object"`, so a JSON string silently disables its dependency gating and +credential injection. Nested mappings still pass `skills-ref validate`. + +```yaml +metadata: + version: "1.1" + skill-author: Exa + openclaw: + primaryEnv: EXA_API_KEY + envVars: + - name: EXA_API_KEY + required: true + description: Exa search API key. + hermes: + category: research +``` + +Only skills with external requirements need these blocks; most omit them. A failed `requires` / +`requires_toolsets` gate *hides* the skill from the agent, so gate only on something the skill +genuinely cannot run without. + +## Body and layout + +- Keep `SKILL.md` under 500 lines. CI warns above that. Move long reference material into + `references/` so agents load it only when needed. +- A skill directory ships only what an agent loads. Tests, fixtures, scratch data, and generated + artifacts stay out of it; tests go in `tests//`. +- Give concrete workflows, commands, and worked examples rather than background explanation. +- Name the required packages, system dependencies, credentials, and network access. +- Include the scientific caveats and validation checks that matter. +- Put fragile or repetitive logic in `scripts/` instead of asking the agent to recreate it. +- Never include secrets, API keys, private URLs, or unpublished data. + +## Validate and scan + +```bash +uv sync + +# spec conformance for one skill +uv run skills-ref validate skills/ + +# every skill, the way CI does +for d in skills/*/; do uv run skills-ref validate "$d"; done +``` + +`.github/workflows/skill-spec-validation.yml` runs that on every PR touching `skills/`, plus the +repo rules `skills-ref` does not check: `metadata.version` present, `allowed-tools` a +space-separated string, `metadata` scalars quoted, and a warning past 500 lines. + +Security-scan new or substantially changed skills. Scanning uses +[Cisco AI Defense Skill Scanner](https://github.com/cisco-ai-defense/skill-scanner) — the +`cisco-ai-skill-scanner` package pinned in `pyproject.toml`, which detects prompt injection, data +exfiltration, and malicious code patterns in Agent Skills. Its README documents the rule IDs and +CLI flags; consult it when a finding's rule is unfamiliar. + +`.github/workflows/pr-skill-scan.yml` runs the repo wrapper for changed skills on every PR and +posts a sticky comment, failing on HIGH or above: + +```bash +# needs SKILL_SCANNER_LLM_API_KEY (see .env) +uv run python scan_pr_skills.py skills/ + +# or the upstream CLI directly, without the repo wrapper +uv run skill-scanner scan skills/ --use-behavioral +``` + +**Verify a finding against the code before "fixing" it.** Known systematic false positives: +`BEHAVIOR_*_EXFILTRATION` and `BEHAVIOR_ENV_VAR_HARVESTING` on any skill that reads its own API key +and calls its own service; `MDBLOCK_PYTHON_SUBPROCESS` on any `subprocess` snippet, including the +safe argument-list form; and `*_EVAL_EXEC` on substrings inside ordinary identifiers (`retrieval`, +`executor`) or on `model.eval()`. Findings sometimes cite files a skill does not contain — check +against `find skills/ -type f` before acting. + +If the skill has tests in `tests//`, run them: + +```bash +uv run --with pytest python -m pytest tests/ -q + +# every skill's suite, one process each, after the repo-wide guard +uv run --with pytest python tests/run_all.py +``` + +**One skill per pytest process.** Skills' `scripts/` directories own plain top-level module names — +32 of them ship a `scripts/_common.py` — so collecting two skills into one interpreter resolves +`_common` to whichever skill imported first and silently tests the wrong files. `tests/conftest.py` +refuses such a session; `tests/run_all.py` forks per skill. + +### The repo-wide guard + +```bash +uv run --with pytest python -m pytest tests/_meta -q +``` + +`tests/_meta` is the fastest useful signal in the repo: pure standard library, no scientific +packages, a couple of seconds. It runs the shared structural contract against **every** skill and +fails if a skill ships `scripts/` without a suite under `tests//` or an entry in +`tests/skill-requirements.toml`. `.github/workflows/skill-tests.yml` runs it on every pull request, +so a skill with untested scripts cannot land. A full run of `tests/run_all.py` starts with it. + +It is not one of the per-skill processes because it deliberately spans all of them at once — safe +because it never imports skill code, only parses it. + +### The shared contract + +`tests/_contract/` holds the assertions every skill shares, so a per-skill suite contains only what +is actually specific to that skill. `tests/conftest.py` registers it as the importable module +`skill_contract`: + +```python +import skill_contract + +# every argparse script answers --help; skips when its packages are absent, +# runs for real under --isolated +CliHelpTests = skill_contract.cli.help_test_case(SKILL_ROOT) + +# for library-style scripts with an `if __name__ == "__main__"` worked example +DemoBlockTests = skill_contract.cli.demo_test_case(SKILL_ROOT, ("doe_designs.py",)) +``` + +- `structure` — frontmatter conformance, the 500-line limit, no tests or bytecode under `skills/`, + local links resolve, scripts parse, no `eval`/`exec`/`os.system`, no standard-library shadowing, + no hardcoded local paths, shell scripts valid. Run repo-wide by `tests/_meta`; do not duplicate + these in a per-skill suite. +- `cli` — the `--help` and demo-block cases above. +- `office` / `schematic` — behaviour for files several skills ship byte-identical copies of (the + OOXML tree under docx/pptx/xlsx; the AI schematic generator under five skills). `tests/_meta` + separately fails if those copies drift apart, so fix them together. + +### One environment per skill + +The project environment deliberately does not carry the skills' scientific packages. Their upstream +pins are mutually exclusive — `opentrons` needs `numpy<2`, `esm` caps `transformers` below the +version the `transformers` skill targets, `geniml` and `spikeinterface` pin `zarr<3` against the +`zarr-python` skill's 3.x, `bioservices` caps `lxml<6` against `matchms`, and `pytdc`, `molfeat`, +`deepchem`, `histolab`, `vaex`, and `ete3` each need an interpreter older than 3.13. Installing them +together forces every one of those skills to the losing side of a version fight. + +So `--isolated` builds a throwaway `uv` environment per skill instead, from +[`tests/skill-requirements.toml`](tests/skill-requirements.toml): + +```bash +python tests/run_all.py --isolated # every suite, one env each +python tests/run_all.py --isolated scanpy qiskit # just these +``` + +Each entry lists the packages that skill documents, plus an optional `python` when the skill cannot +run on the default interpreter; uv downloads that interpreter on demand. Packages that cannot be +installed at all — a GitHub-only SDK, a conda-forge-only library, a CUDA build — are recorded under +`[unavailable]` with the reason, and the runner prints them so the gap shows up in test output. + +Adding a skill with `scripts/` means adding its `[skills.]` entry — `tests/_meta` fails +without one. Use `packages = []` for skills whose bundled tooling is standard-library only; they +still get a clean environment, and CI runs exactly that set on every pull request. uv caches wheels +globally, so repeat runs create each environment in milliseconds. + +The full `--isolated` sweep is not run in CI: it builds one environment per skill, several of which +need a CUDA toolchain, a JDK, or a local MATLAB install. Run it before a release, or whenever you +touch the shared contract. + +## Skill diagrams + +Every skill carries one generated workflow diagram at `docs/images/.png`. Creating a +skill means creating its image; changing what a skill does means regenerating it. The image is not +optional decoration — it is derived from the documentation, so an out-of-date one misrepresents the +skill. + +`scripts/generate_skill_image.py` is local repository tooling, standard library only, and runs in +two stages on one `OPENROUTER_API_KEY` (environment variable, repository `.env`, or `--api-key`): +a text model reads `SKILL.md` plus everything under `references/` and a manifest of `scripts/` and +`assets/`, distils it into a description of one diagram, then an image model draws it. Because it +reads the whole skill, run it **after** the documentation is final, not before. + +```bash +# one skill -> docs/images/.png, replacing any existing image +uv run python scripts/generate_skill_image.py --skill + +# see which files feed the reader, and where the image lands — no API calls, nothing billed +uv run python scripts/generate_skill_image.py --skill --dry-run + +# read the skill and print the diagram prompt without drawing it +uv run python scripts/generate_skill_image.py --skill --prompt-only + +# several skills in one batch +uv run python scripts/generate_skill_image.py --skill + +# backfill everything missing an image, six at a time +uv run python scripts/generate_skill_image.py --all --skip-existing -j 6 +``` + +Look at the result before committing it. Image models misspell labels and occasionally point an +arrow at the wrong card; regenerate rather than ship a diagram whose text is wrong. `--quality low` +makes iteration cheap while checking composition, but commit a `high` render. Both the art direction +and the reader's instructions live at the top of the script — change them there rather than +hand-tuning one skill's prompt, so the set stays visually consistent. + +## Before opening a PR + +- Directory name and frontmatter `name` match exactly. +- No `tests/` directory and no `test_*.py` anywhere under `skills//` — tests belong in + `tests//`. +- Only the six spec-defined top-level fields; everything else under `metadata`. +- `metadata.version` exists, is quoted, and is bumped if you changed an existing skill. +- `metadata` is a block mapping; `openclaw` / `hermes` blocks are nested mappings. +- `uv run skills-ref validate skills/` passes. +- `uv run --with pytest python -m pytest tests/_meta -q` passes — this is what CI blocks on, and it + catches a missing suite, a missing `skill-requirements.toml` entry, a broken local link, and a + leaked local path. +- If the skill ships `scripts/`: a suite exists at `tests//`, a `[skills.]` entry exists + in `tests/skill-requirements.toml`, and `python tests/run_all.py --isolated ` passes. +- `docs/images/.png` exists, and was regenerated if the change altered what the skill does. + Its labels are spelled correctly and its arrows point where they should. +- Examples and scripts are tested, or clearly marked illustrative. +- No secrets or private data; scan results clean or explained in the PR. -- 2.54.0 From 758dd72a1ccf51a0cbf77bced1b1165b965462b5 Mon Sep 17 00:00:00 2001 From: promptadmin Date: Sat, 8 Aug 2026 15:32:48 +0000 Subject: [PATCH 009/101] [upstream-sync] CLAUDE.md from K-Dense-AI/scientific-agent-skills@991bd993 [unknown] --- .../catalogue/CLAUDE.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 upstream/K-Dense-AI-scientific-agent-skills/catalogue/CLAUDE.md diff --git a/upstream/K-Dense-AI-scientific-agent-skills/catalogue/CLAUDE.md b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/CLAUDE.md new file mode 100644 index 00000000..d5219617 --- /dev/null +++ b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/CLAUDE.md @@ -0,0 +1,16 @@ +--- +title: "CLAUDE.md" +task: "" +lineage_type: import +upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/991bd993/CLAUDE.md +upstream_sha: 991bd993 +imported_at: 2026-08-08 +prompt_class: unknown +upstream_changes: accepted +author: upstream +validated: false +--- + +# CLAUDE.md + +Repository guidance for this project lives in [AGENTS.md](AGENTS.md). Read it and follow it. -- 2.54.0 From cb96c9edc3f4f45cf1133ca50164478aaed502af Mon Sep 17 00:00:00 2001 From: promptadmin Date: Sat, 8 Aug 2026 15:33:01 +0000 Subject: [PATCH 010/101] [upstream-sync] CODE_OF_CONDUCT.md from K-Dense-AI/scientific-agent-skills@991bd993 [catalogue] --- .../catalogue/CODE_OF_CONDUCT.md | 148 ++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 upstream/K-Dense-AI-scientific-agent-skills/catalogue/CODE_OF_CONDUCT.md diff --git a/upstream/K-Dense-AI-scientific-agent-skills/catalogue/CODE_OF_CONDUCT.md b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..4ba0cffd --- /dev/null +++ b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/CODE_OF_CONDUCT.md @@ -0,0 +1,148 @@ +--- +title: "Contributor Covenant Code of Conduct" +task: "" +lineage_type: import +upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/991bd993/CODE_OF_CONDUCT.md +upstream_sha: 991bd993 +imported_at: 2026-08-08 +prompt_class: catalogue +upstream_changes: accepted +author: upstream +validated: false +--- + +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of + any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, + without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official email address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +[contact@k-dense.ai](mailto:contact@k-dense.ai). +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +Note that this address is for conduct reports. Security vulnerabilities follow a +separate, confidential process — see [SECURITY.md](SECURITY.md). + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][mozilla coc]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][faq]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[mozilla coc]: https://github.com/mozilla/inclusion +[faq]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations -- 2.54.0 From 87c37191f6da4833ea95feea7dc7ac01168da4b0 Mon Sep 17 00:00:00 2001 From: promptadmin Date: Sat, 8 Aug 2026 15:33:13 +0000 Subject: [PATCH 011/101] [upstream-sync] docs/security-report.json from K-Dense-AI/scientific-agent-skills@991bd993 [catalogue] --- .../catalogue/docs/security-report.json | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 upstream/K-Dense-AI-scientific-agent-skills/catalogue/docs/security-report.json diff --git a/upstream/K-Dense-AI-scientific-agent-skills/catalogue/docs/security-report.json b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/docs/security-report.json new file mode 100644 index 00000000..f9ff1a0a --- /dev/null +++ b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/docs/security-report.json @@ -0,0 +1,13 @@ +--- +title: "Security Report" +task: "" +lineage_type: import +upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/991bd993/docs/security-report.json +upstream_sha: 991bd993 +imported_at: 2026-08-08 +prompt_class: catalogue +upstream_changes: accepted +author: upstream +validated: false +--- + -- 2.54.0 From edd6c68982a689131501d16e34dc4b829aa04a45 Mon Sep 17 00:00:00 2001 From: promptadmin Date: Sat, 8 Aug 2026 15:33:23 +0000 Subject: [PATCH 012/101] [upstream-sync] docs/security-triage.md from K-Dense-AI/scientific-agent-skills@991bd993 [catalogue] --- .../catalogue/docs/security-triage.md | 174 ++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 upstream/K-Dense-AI-scientific-agent-skills/catalogue/docs/security-triage.md diff --git a/upstream/K-Dense-AI-scientific-agent-skills/catalogue/docs/security-triage.md b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/docs/security-triage.md new file mode 100644 index 00000000..f3bdf7b2 --- /dev/null +++ b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/docs/security-triage.md @@ -0,0 +1,174 @@ +--- +title: "Security Scan Triage" +task: "" +lineage_type: import +upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/991bd993/docs/security-triage.md +upstream_sha: 991bd993 +imported_at: 2026-08-08 +prompt_class: catalogue +upstream_changes: accepted +author: upstream +validated: false +--- + +# Security Scan Triage + +Verdicts on findings from [`docs/security-report.md`](security-report.md). The report is published +automatically with no pre-publication plausibility check, so a finding there is a prompt to review a +skill, not a determination about it. This file records which findings were verified, what was fixed, +and which classes are systematic false positives — so the same 40 CRITICAL/HIGH items are not +re-investigated from scratch every week. + +**Triaged against:** scan of 2026-07-27 10:38 UTC (scanner 2.0.12, model claude-opus-5, 154 skills, +817 findings: 33 CRITICAL, 8 HIGH, 222 MEDIUM, 554 LOW). + +Re-run any check below yourself; each one is cheap and decides the finding on its own. + +--- + +## Fixed + +These were real. Each fix keeps the skill's documented behavior intact. + +| Skill | Finding | What was actually wrong | Fix | +|-------|---------|------------------------|-----| +| `xlsx`, `docx`, `pptx` | `LLM_COMMAND_INJECTION` — runtime C compilation and LD_PRELOAD injection | `scripts/office/soffice.py` built its AF_UNIX shim at a fixed `/tmp/lo_socket_shim.so` and reused whatever was already there if the path merely existed. On a shared host, any local user could pre-plant a shared object there and have it `LD_PRELOAD`ed into every subsequent `soffice` run. The `.c` source was written to an equally predictable path before compilation. | Shim is built in a `tempfile.mkdtemp()` directory — unpredictable name, created `0700`, owned by the caller — memoized per process and removed at exit. No on-disk reuse across runs. | +| `imaging-data-commons` | `LLM_SUPPLY_CHAIN_ATTACK` — autonomous install with `--break-system-packages` | `SKILL.md` told the agent to run a version check **first** that shelled out to `pip3 install --break-system-packages` with no user confirmation, overriding a distribution safeguard unattended. Six other places recommended unpinned `pip install --upgrade idc-index`. | The startup block now only reports the version mismatch and prints a suggested command for the user to approve. All install guidance pinned to `idc-index==0.11.14` in a virtual environment. | +| `pacsomatic` | `LLM_COMMAND_INJECTION` — `--module-load` written unquoted into a generated launch script | Every other value in `write_launch_script()` passes through `shlex.quote()`; `args.module_load` alone was appended raw, so caller-supplied text became arbitrary shell in a script later executed by `bash`/`bsub`/`sbatch`/`qsub`. | `normalize_module_load()` validates the argument at input time: segments split on `&&`/`;`, each must start with `module` and contain no shell metacharacters, then re-emitted quoted. Every documented form (`module load nextflow/23.10.0`, `module purge && module load …`) still works. | +| `autoskill` | `LLM_DATA_EXFILTRATION` — arbitrary config-controlled endpoint for screen-derived data | `foundry.endpoint` from `config.yaml` was passed straight to `httpx.Client` with no scheme or host check, so summaries derived from screen-capture OCR plus an API key header could go to any URL, including plaintext `http://`. | `check_remote_endpoint()` rejects non-HTTP(S) schemes and plaintext HTTP to non-loopback hosts, and prints the destination host to stderr before any off-machine call. The default local LM Studio backend on `localhost:1234` is unaffected. | +| `hugging-science` | `LLM_PROMPT_INJECTION` — remote catalog rendered verbatim into agent context | `fetch_catalog.py` printed titles, descriptions, tags and URLs fetched from `huggingscience.co` with no framing or sanitization, so whoever controls or spoofs that host could place imperative prose or a runnable code block in a description field. | Output carries an explicit untrusted-data banner naming the source URL; entry text is defanged (code fences neutralized, bare `---` separators dropped); URLs outside `huggingface.co`/`hf.co`/`huggingscience.co` are labelled `[off-catalog host]`, with exact-or-subdomain matching so `evil-huggingface.co` does not pass. | +| `dhdna-profiler` | `LLM_DATA_EXFILTRATION` — profiling third parties and conversation history without consent | Independent of the phantom-script claims in the same finding (see below), this was real in the skill text: Self-Profile Mode mined conversation history silently, and nothing bounded profiling of people who are not in the conversation. | Added a Consent and Scope section: ask before reading back through conversation history, label third-party profiles as speculative inference, decline profiling that feeds hiring/clinical/disciplinary/credit decisions, keep profiles in-session. | +| `liteparse` | `LLM_SKILL_DISCOVERY_ABUSE` — activation-priority manipulation | The `description` instructed activation "even when the user does not name liteparse" and to "Prefer over MarkItDown" and "prefer over the pdf skill" — preemption directives that shadow sibling document skills. | Description rewritten to state capabilities factually. Parser-selection guidance already lived in `references/choosing_a_parser.md` and the in-body routing table, so nothing was lost. | + +--- + +## False positives + +### All 40 CRITICAL and HIGH findings + +Every CRITICAL and HIGH in the 2026-07-27 report falls into one of four classes below. None +survived verification. + +**`BEHAVIOR_EVAL_SUBPROCESS` (CRITICAL ×4)** — claims `eval`/`exec` combined with `subprocess` in +`pacsomatic`, `research-lookup`, `scientific-slides`, `xlsx`. There are **zero** `eval`/`exec`/ +`compile` call sites in the entire repository. The rule matches the *substring* `eval`/`exec` inside +ordinary identifiers that co-occur with `import subprocess` — `retrieval`, `evaluate`, `executor`, +`executable`. `scientific-slides/scripts/validate_presentation.py` and `xlsx/scripts/recalc.py` +contain neither substring at all. + +```bash +# AST walk over every skill script: no eval/exec/compile, no os.system/os.popen, +# no shell=True, no env=os.environ.copy(), no iteration over os.environ. +python3 - <<'PY' +import ast, pathlib +def full(n): + if isinstance(n, ast.Name): return n.id + if isinstance(n, ast.Attribute): return f"{full(n.value)}.{n.attr}".lstrip(".") + return "" +risky = {"os.system","os.popen","eval","exec","compile","subprocess.getoutput","os.execv"} +hits = [] +for p in sorted(pathlib.Path("skills").rglob("*.py")): + try: t = ast.parse(p.read_text(encoding="utf-8", errors="replace")) + except SyntaxError: continue + for n in ast.walk(t): + if isinstance(n, ast.Call): + if full(n.func) in risky: hits.append((p, n.lineno, full(n.func))) + for kw in n.keywords or []: + if kw.arg == "shell" and getattr(kw.value, "value", None) is True: + hits.append((p, n.lineno, "shell=True")) + if kw.arg == "env" and "os.environ" in ast.unparse(kw.value) and ".copy()" in ast.unparse(kw.value): + hits.append((p, n.lineno, "env=os.environ.copy()")) + if isinstance(n, ast.For) and "os.environ" in ast.unparse(n.iter): + hits.append((p, n.lineno, "iterates os.environ")) +print(hits or "clean") +PY +``` + +**`BEHAVIOR_ENV_VAR_EXFILTRATION` / `BEHAVIOR_CROSSFILE_ENV_VAR_EXFILTRATION` / +`BEHAVIOR_CROSSFILE_EXFILTRATION_CHAIN` (CRITICAL ×29)** — fire on "reads an env var + makes a +network call" anywhere in one package. In every flagged skill the variable read is the API key for +the service the skill exists to call: + +| Skill | Env var read | Destination | +|-------|--------------|-------------| +| `autoskill` | `ANTHROPIC_API_KEY`, `FOUNDRY_API_KEY`, `SCREENPIPE_TOKEN` | `api.anthropic.com`, configured foundry endpoint, `localhost` | +| `citation-management` | `NCBI_API_KEY`, `NCBI_EMAIL`, `OPENROUTER_API_KEY` | `eutils.ncbi.nlm.nih.gov`, `openrouter.ai` | +| `research-lookup` | `OPENROUTER_API_KEY`, `PARALLEL_API_KEY` | `openrouter.ai`, `api.parallel.ai` | +| `infographics`, `latex-posters`, `literature-review`, `scientific-schematics`, `scientific-slides` | `OPENROUTER_API_KEY` | `openrouter.ai` | + +That is service authentication, which [`SECURITY.md`](../SECURITY.md) places out of scope as "the +inherent capability of skills." The scanner's own LLM pass agreed in writing on an earlier run: +"standard API-key-based service authentication, not exfiltration." + +**`MDBLOCK_PYTHON_EVAL_EXEC` (HIGH ×4)** — `geomaster/references/machine-learning.md:207,435` and +`modal/references/functions.md:82` are PyTorch `model.eval()`; `histolab/references/ +filters_preprocessing.md:487` is the OpenCV constant `cv2.CV_64F`. The `modal` and `histolab` lines +already carry inline comments saying exactly this, from an earlier triage; the rule ignores them. + +**`LLM_DATA_EXFILTRATION` / `LLM_UNAUTHORIZED_TOOL_USE` (HIGH ×3, all `dhdna-profiler`)** — rest +entirely on a claimed inventory of "8 Python scripts" performing "env var reads and network calls." +`dhdna-profiler` contains two files, both Markdown. The findings also cite `BEHAVIOR_*` static +results that appear nowhere in that skill's own findings list, i.e. the LLM analyzer was fed another +skill's static output. (The separate consent concern in the same finding was real and is fixed +above.) + +### Confabulated file inventories + +The scanner reported Python and shell files in skills that ship only Markdown. Any finding whose +premise is "undisclosed bundled code" in these skills is void: + +| Skill | Scanner claimed | Actual | +|-------|-----------------|--------| +| `dhdna-profiler` | 8 Python + 12 Markdown (21 files) | 2 files, both `.md` | +| `seaborn` | 7 Python files | 8 files, all `.md` | +| `scikit-bio` | 2 Python + 1 bash | 2 files, both `.md` | +| `umap-learn` | 2 Python files | 2 files, both `.md` | +| `what-if-oracle` | 2 Python + 1 bash (8 files) | 2 files, both `.md` | + +```bash +for s in dhdna-profiler scikit-bio seaborn umap-learn what-if-oracle; do + printf "%-18s py=%s sh=%s md=%s\n" "$s" \ + "$(find skills/$s -name '*.py' | wc -l | tr -d ' ')" \ + "$(find skills/$s -name '*.sh' | wc -l | tr -d ' ')" \ + "$(find skills/$s -name '*.md' | wc -l | tr -d ' ')" +done +``` + +Note the arithmetic: `seaborn`'s "7 Python files" and `dhdna-profiler`'s "8 Python + 12 Markdown" +track those skills' Markdown counts, so the analyzer appears to be mis-typing files rather than +inventing them wholesale. + +### Other + +**`liteparse` — `LLM_SUPPLY_CHAIN_ATTACK`**, "possibly non-existent version `liteparse==2.0.0`, +cites a future PyPI release dated May 2026." The package is real, published by Logan Markewich +(run-llama, `github.com/run-llama/liteparse`), and `2.0.0` was uploaded 2026-05-25 — matching the +skill's claim. The scanner could not verify a date past its knowledge cutoff. + +```bash +curl -s https://pypi.org/pypi/liteparse/json | python3 -c \ + "import json,sys; d=json.load(sys.stdin); print(d['info']['author'], '2.0.0' in d['releases'], d['releases']['2.0.0'][0]['upload_time'])" +``` + +**`BEHAVIOR_ENV_VAR_HARVESTING` (MEDIUM ×24)** — "script iterates through environment variables." +What it matches is the hardened form introduced by an earlier triage: `{name: os.environ[name] for +name in FORWARDED_ENV_VARS if name in os.environ}`, an explicit allowlist that exists specifically +so a subprocess does *not* inherit the caller's secrets. The rule fires on the fix. + +**`MDBLOCK_PYTHON_HTTP_POST` (×27), `MDBLOCK_PYTHON_SUBPROCESS` (×18)** — fire on any HTTP POST or +`subprocess` call shown in a `SKILL.md` code block, including the safe argument-list form the +scanner recommends elsewhere. A skill that documents calling an API necessarily documents an HTTP +call. + +**`hugging-science` — `LLM_COMMAND_INJECTION`** on `trust_remote_code=True` guidance. Not fixed +because it is already handled as the finding itself acknowledges: `SKILL.md:117` requires the agent +to ask the user before setting the flag, naming the repo, and states that catalog presence "is not a +vetting signal." The underlying capability belongs to `transformers`, not to this skill. + +--- + +## Reporting + +If you think a verdict here is wrong, open an issue with the skill name, the rule ID, and the check +that contradicts it. See [`SECURITY.md`](../SECURITY.md) for the private channel for genuine +vulnerabilities. -- 2.54.0 From fd3de230ba55f4265deb440616b9b462d8e6ccaf Mon Sep 17 00:00:00 2001 From: promptadmin Date: Sat, 8 Aug 2026 15:33:33 +0000 Subject: [PATCH 013/101] [upstream-sync] skills/analytical-method-validation/SKILL.md from K-Dense-AI/scientific-agent-skills@991bd993 [catalogue] --- .../analytical-method-validation/SKILL.md | 305 ++++++++++++++++++ 1 file changed, 305 insertions(+) create mode 100644 upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/SKILL.md diff --git a/upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/SKILL.md b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/SKILL.md new file mode 100644 index 00000000..8ec8f023 --- /dev/null +++ b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/SKILL.md @@ -0,0 +1,305 @@ +--- +lineage_type: import +upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/991bd993/skills/analytical-method-validation/SKILL.md +upstream_sha: 991bd993 +imported_at: 2026-08-08 +prompt_class: catalogue +upstream_changes: accepted +name: analytical-method-validation +description: Plan, execute, and document validation, verification, and transfer of analytical procedures under the governing framework - ICH Q2(R2) and Q14, USP <1220>/<1225>/<1226>, ICH M10 bioanalytical, CLSI EP, or ISO/IEC 17025. Use for HPLC, LC-MS/MS, GC, CE, ICP-MS, dissolution, qNMR, qPCR, NIR, and ligand binding or cell-based assays whenever the question is whether a procedure is fit for its intended purpose. Triggers include "method validation", "analytical method validation", "AMV", "validation protocol", "acceptance criteria", "linearity", "reportable range", "accuracy and precision", "repeatability", "intermediate precision", "recovery", "LOD", "LOQ", "detection limit", "quantitation limit", "specificity", "robustness", "method transfer", "method comparison", "Deming", "Passing-Bablok", "Bland-Altman", "equivalence testing", "OOS investigation", "ICH Q2", "Q2(R2)", "Q14", "USP 1225", "ICH M10", "incurred sample reanalysis", "ISR", "CLSI EP", and any request to show that an assay works. +license: MIT +compatibility: Requires Python 3.11+. Scripts use only the standard library - no numpy, scipy, or network access. Statistical distributions are computed from first principles so results are reproducible in any conforming interpreter. +allowed-tools: Read Write Edit Bash +metadata: + version: "1.0" + skill-author: K-Dense Inc. + last-reviewed: "2026-07-27" +--- + +# Analytical Method Validation + +## When to use + +Any time the question is whether an analytical procedure is fit for its intended purpose: +designing a validation study, evaluating validation data, verifying a compendial procedure, +transferring a procedure to another laboratory or instrument, or defending any of these in a +report. + +## The two rules + +**1. Establish which framework governs before designing anything.** The same assay validates +differently under ICH Q2(R2), USP <1225>, ICH M10, CLSI EP, and ISO/IEC 17025. They differ in +which characteristics are required, how the studies are laid out, and whether numeric acceptance +criteria are supplied at all. Blending them produces a protocol that satisfies none of them. + +**2. State acceptance criteria before collecting data.** Criteria chosen after seeing results are +not acceptance criteria, and deciding them post hoc is a standing audit finding. ICH Q2(R2) +deliberately supplies almost no numeric criteria — they have to come from the specification, the +analytical target profile (ICH Q14 section 3), or development data. ICH M10 is the exception: it +supplies explicit numbers, and they differ between chromatographic assays and ligand binding +assays. + +## Scope + +This skill plans studies, computes the statistics correctly, and structures the documentation. It +does **not** decide that a procedure is validated, release a batch, accept or reject a run, close +an investigation, or substitute for the analyst, the technical reviewer, the quality unit, or the +regulator. Every script reports; none of them concludes. + +## Copyright boundary + +ICH guidelines are published openly and licensed for reuse with acknowledgement, so their +requirements are encoded directly in this skill. **USP general chapters, CLSI EP documents, and +ISO standards are copyrighted and paywalled.** For those, this skill supplies the designation, +scope, and where to obtain an authorised copy — never the text, never invented thresholds. Do not +ask an agent to retrieve, transcribe, or reconstruct their content. If a number matters and it +lives in a paywalled document, read it from the authorised copy. + +## Frameworks + +```bash +cd skills/analytical-method-validation/scripts +python3 plan_validation.py --list-frameworks +``` + +| Key | Governs | Numeric criteria supplied | +| --- | --- | --- | +| `ich-q2r2` | Release and stability testing of drug substances and products | Almost none — you derive them | +| `ich-m10` | Bioanalytical concentration measurement (PK, TK, BE) | Yes, and they differ by modality | +| `usp-1220` | Compendial procedure lifecycle, three stages | Paywalled | +| `usp-1225` / `usp-1226` | Validation / verification of compendial procedures | Paywalled | +| `clsi` | Clinical laboratory measurement procedures (EP series) | Paywalled | +| `iso-17025` | Lab-developed and modified methods under accreditation | No — "to the extent necessary" | + +**Q2(R2) replaced Q2(R1) in November 2023 and restructured the characteristics.** Range is now +the parent characteristic (section 3.2), containing *response* (linearity) and *validation of +lower range limits* (DL/QL). Accuracy and precision are section 3.3 and may be evaluated in +combination against a single criterion. Robustness is treated as a development activity and +cross-refers to ICH Q14. Multivariate procedures are addressed explicitly (2.5 and 3.2.2.3), and +Annex 2 adds worked examples for techniques Q2(R1) never covered — quantitative ¹H-NMR, NIR, +quantitative LC/MS, qPCR, biological assays, and particle size. A Q2(R1)-shaped protocol — a flat +list of linearity, range, accuracy, precision, specificity, LOD, LOQ, robustness — is out of date. +Note also the error correction dated 30 November 2023 to Table 5 and Tables 6–11. + +## Scripts + +```bash +cd skills/analytical-method-validation/scripts +``` + +| Script | Question answered | +| --- | --- | +| `plan_validation.py` | Which framework, which characteristics, what study layout, what protocol? | +| `check_response.py` | Does the calibration model actually hold across the range? | +| `check_accuracy_precision.py` | What is the recovery, and how much of the variability is between days? | +| `check_detection_limits.py` | What are DL and QL by each allowed approach, and do they serve the reporting threshold? | +| `check_bioanalytical_run.py` | Does this run meet ICH M10 for its modality? | +| `compare_methods.py` | Are two procedures equivalent, at a pre-stated margin? | + +All take `--format table|tsv|json`. Provenance, guideline citations, and caveats go to stderr; +data goes to stdout, so `> out.tsv` keeps them separate. Exit code is `0` for no findings, `1` +when findings were raised, `2` for bad input — so any of them can gate a workflow. + +## Workflow + +### 1. Fix the framework and the required characteristics + +```bash +python3 plan_validation.py --framework ich-q2r2 --attribute assay --technique hplc --range-use assay +``` + +Q2(R2) Table 1 decides what is required from the *measured attribute*, not from the technique. For +an assay: specificity, response, accuracy, repeatability, intermediate precision. For a limit +test: specificity and DL only. For an identity test: specificity alone. Attributes accepted include +`assay`, `impurity` (quantitative), `impurity-limit`, and `identity`. + +Reportable range comes from the specification. Q2(R2) Table 2 gives worked examples — 80–120% of +declared content for an assay, 70–130% for content uniformity, reporting threshold to 120% of the +specification for an impurity. + +### 2. Generate the protocol and fill in the criteria + +```bash +python3 plan_validation.py --framework ich-q2r2 --attribute impurity --protocol > protocol.md +``` + +Every bracketed field is a decision to make and record *before* data collection. The protocol +skeleton deliberately refuses to pre-fill acceptance criteria for Q2(R2) work, because there is no +defensible default. + +### 3. Evaluate the response + +```bash +python3 check_response.py -i calibration.csv --max-back-calc-error 2 +``` + +Input is `level,response`, one row per injection; repeated rows at the same level are replicates, +and supplying them is what makes the linearity test possible. + +Real output from a curve that a coefficient of determination would wave through: + +``` +statistic value +distinct levels 5 +slope 166.6000 +intercept 2495.0000 +intercept CI includes 0 no +coefficient of determination (r2) 0.9830 +lack-of-fit F 469.5294 +lack-of-fit p 1.5139e-06 +runs test p 0.0492 + +level n mean_response mean_back_calculated relative_error_pct +50.0000 2 10075.0000 45.4982 -9.0036 +75.0000 2 15150.0000 75.9604 1.2805 +100.0000 2 20050.0000 105.3721 5.3721 +125.0000 2 24050.0000 129.3818 3.5054 +150.0000 2 26450.0000 143.7875 -4.1417 +``` + +r² = 0.983 and the model is unusable: −9.0% back-calculated error at the bottom of the range, +lack-of-fit p = 1.5 × 10⁻⁶, non-random residual signs. **r² is not evidence of linearity** — it +rises with range and is nearly insensitive to curvature. The lack-of-fit F test against pure error +and the residual pattern are the evidence, which is why Q2(R2) 3.2.2.1 asks for an analysis of the +deviation of points from the line rather than a correlation coefficient alone. + +Add `--weight 1/x2` for a wide-range curve. The script flags heteroscedasticity when the residual +variance in the top third of the range exceeds the bottom third by more than 10×, because an +unweighted fit then biases exactly the low end where a reporting threshold lives. + +### 4. Evaluate accuracy and precision + +```bash +python3 check_accuracy_precision.py -i ap.csv --accuracy-limit 2 --rsd-limit 1.0 --design-check assay +``` + +Input is `level,measured,group`, where `group` is the intermediate-precision factor — day, analyst, +or instrument. + +``` +level component sd rsd_pct df ci90_low_sd ci90_high_sd +100 repeatability (within group) 0.0707 0.0707 3 0.0438 0.2065 +100 between-group 1.6515 1.6515 2 n/a n/a +100 intermediate precision (total) 1.6530 1.6530 2.0037 0.9554 7.2821 +``` + +Repeatability of 0.07% RSD looks superb; intermediate precision is 1.65%, twenty-three times +larger, because the variability lives entirely between days. Reporting the within-day figure as +the procedure's precision would understate routine performance by more than an order of magnitude. +This is why the script fits a one-way random-effects model rather than pooling. + +Two traps the script handles for you: + +- **Precision is estimated within each level, never pooled across levels.** Pooling 80/100/120% + results into one standard deviation turns the range itself into apparent imprecision. The script + reports per level, plus a level-independent view as percent of nominal. +- **`--require-ci-within-limit`** enforces that the whole confidence interval sits inside the + limit, not just the mean. Q2(R2) 3.3.1.4 asks for the interval to be *compatible with* the + criterion; a mean that scrapes inside on six replicates has not demonstrated much. + +### 5. Establish DL and QL, and confirm them + +```bash +python3 check_detection_limits.py --calibration lowcal.csv --blanks blanks.csv \ + --confirm-ql 0.05 --confirm-data ql_check.csv --reporting-threshold 0.05 +``` + +``` +approach sigma slope DL QL +sd-and-slope (sigma = residual SD of regression) 7.2816 5033.3490 0.0048 0.0145 +sd-and-slope (sigma = SD of y-intercept) 4.3303 5033.3490 0.0028 0.0086 +sd-and-slope (sigma = SD of 8 blanks) 3.7702 5033.3490 0.0025 0.0075 +``` + +The same data give QL estimates spanning 1.9×, purely from the choice of σ. Q2(R2) 3.2.3.5 +therefore requires the limit **and the approach used to determine it** to be reported, and an +estimated limit to be confirmed with samples at or near it. For an impurity procedure the QL must +be at or below the reporting threshold. Reaching for `3.3σ/slope` reflexively, reporting one number +with no named approach, and never confirming it are three separate findings. + +### 6. Bioanalytical runs under ICH M10 + +```bash +python3 check_bioanalytical_run.py --modality chromatographic --run run1.csv +python3 check_bioanalytical_run.py --modality lba --isr isr.csv +python3 check_bioanalytical_run.py --modality lba --criteria +``` + +`--modality` is mandatory and has no default, because the criteria genuinely differ: + +| | Chromatographic | Ligand binding assay | +| --- | --- | --- | +| Calibration tolerance | ±15%, ±20% at LLOQ | ±20%, ±25% at LLOQ and ULOQ | +| Accuracy / precision | ±15% / ≤15% CV (±20% / ≤20% at LLOQ) | ±20% / ≤20% CV (±25% / ≤25% at LLOQ and ULOQ) | +| A&P design | 4 QC levels, 5 replicates/run, ≥3 runs over ≥2 days | 5 QC levels, 3 replicates/run, ≥6 runs over ≥2 days | +| Total error | no such criterion | ≤30%, ≤40% at LLOQ and ULOQ | +| ISR agreement | ±20% for ≥2/3 of repeats | ±30% for ≥2/3 of repeats | + +Applying the ±15% chromatographic numbers to a ligand binding assay, or importing the LBA total-error +criterion into a chromatographic method, are both common and both wrong. + +The run check enforces the per-level rule that gets missed: at least 2/3 of *all* QCs **and** at +least 50% at *each* level. A run can pass the overall fraction while a single level fails +completely. + +``` +finding: QC level high: 0/2 within tolerance (0%); M10 requires at least 50% at each level +``` + +### 7. Transfer and method comparison + +```bash +python3 compare_methods.py -i paired.csv --margin 2 --relative --slope-tolerance 0.05 +``` + +``` +mean difference (%) 1.4646 +TOST margin 2.0000 +TOST p-value 1.0528e-13 +90% CI (TOST) 1.44127 to 1.48797 +equivalent at stated margin yes +--- for contrast only --- +paired t-test p (NOT equivalence) 0.0000 +OLS slope (biased here) 1.0396 +Deming slope 1.0398 +Passing-Bablok slope 1.0351 +``` + +Two errors this replaces: + +- **"p > 0.05, no significant difference, therefore the methods are equivalent."** Failing to + detect a difference is not evidence of equivalence, and on a small transfer dataset that outcome + is close to guaranteed. TOST tests the hypothesis that matters — that the true difference lies + inside a pre-stated margin. Here the t test says the difference is highly significant *and* TOST + says the methods are equivalent at ±2%; both are true, and only one answers the question. +- **Ordinary least squares for method comparison.** OLS assumes the reference values carry no + error, which is false when comparing two procedures, and biases the slope toward zero. Deming + (with a stated error-variance ratio) and Passing–Bablok (non-parametric, outlier-resistant) are + the appropriate regressions and are reported side by side with OLS for contrast. + +The script also flags proportional bias — when the difference trends with concentration, a single +mean bias and its limits of agreement are misleading regardless of how tight they look. + +## What this skill exists to prevent + +1. Validating against ICH Q2(R1)'s structure three years after Q2(R2) replaced it. +2. Acceptance criteria written after the data were seen. +3. r² presented as evidence of linearity. +4. Repeatability reported as the procedure's precision, with the between-day component invisible. +5. One DL/QL number with no named approach and no confirmation. +6. Chromatographic M10 criteria applied to a ligand binding assay, or the reverse. +7. A t test's non-significance presented as equivalence at a method transfer. + +## References + +- `references/framework-selection.md` — which framework governs, and the questions that decide it +- `references/ich-q2r2.md` — structure, Table 1 and Table 2, per-characteristic recommended data +- `references/ich-m10-bioanalytical.md` — the full chromatographic and LBA criteria side by side +- `references/compendial-and-clsi.md` — USP, CLSI and ISO designations, scope, and how to cite them +- `references/statistics.md` — the statistical methods, why each one, and the common errors +- `references/source-ledger.md` — provenance and research dates for every claim in this skill + +## Assets + +- `assets/validation-protocol-template.md` — protocol structure with criteria stated up front +- `assets/validation-report-template.md` — report structure with raw-data traceability -- 2.54.0 From d82de50b203a02813d8e033e0c5333a5e979fe8c Mon Sep 17 00:00:00 2001 From: promptadmin Date: Sat, 8 Aug 2026 15:33:43 +0000 Subject: [PATCH 014/101] [upstream-sync] skills/analytical-method-validation/assets/validation-protocol-template.md from K-Dense-AI/scientific-agent-skills@991bd993 [unknown] --- .../assets/validation-protocol-template.md | 119 ++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/assets/validation-protocol-template.md diff --git a/upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/assets/validation-protocol-template.md b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/assets/validation-protocol-template.md new file mode 100644 index 00000000..191270f5 --- /dev/null +++ b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/assets/validation-protocol-template.md @@ -0,0 +1,119 @@ +--- +title: "Analytical Procedure Validation Protocol" +task: "" +lineage_type: import +upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/991bd993/skills/analytical-method-validation/assets/validation-protocol-template.md +upstream_sha: 991bd993 +imported_at: 2026-08-08 +prompt_class: unknown +upstream_changes: accepted +author: upstream +validated: false +--- + +# Analytical Procedure Validation Protocol + +> Every bracketed field is a decision to make and record **before** data collection. +> `plan_validation.py --protocol` generates a framework-specific version of this document with the +> required characteristics already listed. + +| Field | Value | +| --- | --- | +| Protocol number / version | [ ] | +| Analytical procedure identifier and version | [ ] | +| Product / analyte / matrix | [ ] | +| Measured quality attribute | [ ] assay / impurity (quantitative) / impurity (limit) / identity / other | +| Governing framework and section | [ ] | +| Regional expectation confirmed with | [ ] | +| Related development report (ICH Q14) | [ ] | +| Author / date | [ ] | +| Technical reviewer / date | [ ] | +| Quality unit approval / date | [ ] | + +## 1. Intended purpose and analytical target profile + +- Measurand and reporting unit: [ ] +- Decision the result supports: [ ] release / stability / in-process / clinical / other +- Specification or reporting limits served: [ ] +- Required reportable range, derived from the specification: [ ] +- Performance characteristics and criteria (the ATP): [ ] + +## 2. Pre-stated acceptance criteria + +State a numeric criterion and its justification for every characteristic to be validated. A +criterion with no justification traceable to the specification, the ATP, or development data is not +defensible. + +| Characteristic | Criterion | Justification | Framework reference | +| --- | --- | --- | --- | +| Specificity / selectivity | [ ] | [ ] | [ ] | +| Response (calibration model) | [ ] | [ ] | [ ] | +| Lower range limit (DL / QL) | [ ] | [ ] | [ ] | +| Accuracy | [ ] | [ ] | [ ] | +| Repeatability | [ ] | [ ] | [ ] | +| Intermediate precision | [ ] | [ ] | [ ] | +| Combined accuracy and precision, if used | [ ] | [ ] | [ ] | + +- Interval to be reported alongside accuracy and precision: [ ] confidence level [ ] +- Does the criterion apply to the point estimate or to the whole interval? [ ] + +## 3. Study design + +| Characteristic | Levels | Replicates | Runs / days / analysts / instruments | +| --- | --- | --- | --- | +| Response | [ ] (minimum 5 for ICH Q2(R2)) | [ ] | [ ] | +| Accuracy | [ ] | [ ] | [ ] | +| Repeatability | [ ] | [ ] | [ ] | +| Intermediate precision | [ ] | [ ] | [ ] | +| Lower range limit | [ ] | [ ] | [ ] | + +- Replicate count matches the routine reportable result: [ ] yes / [ ] justified deviation: [ ] +- Calibration model and weighting, fixed in advance: [ ] unweighted / 1/x / 1/x² / non-linear / multivariate +- Randomisation and run order: [ ] +- Prior knowledge or development data used in place of a test, with justification: [ ] + +## 4. Materials + +| Item | Identity / grade | Lot | Assigned value and uncertainty | Expiry | +| --- | --- | --- | --- | --- | +| Reference material | [ ] | [ ] | [ ] | [ ] | +| Impurity standards | [ ] | [ ] | [ ] | [ ] | +| Blank / placebo matrix | [ ] | [ ] | — | [ ] | + +## 5. Sample and solution handling + +- Preparation procedure and dilution scheme: [ ] +- Solution stability window to be demonstrated: [ ] +- Storage conditions: [ ] + +## 6. Specificity and stability-indicating properties + +- Interferences to be challenged: [ ] +- Forced degradation conditions, if a stability-indicating claim is made: [ ] +- Orthogonal procedure, if used, and its accuracy: [ ] + +## 7. Robustness (normally development, ICH Q14) + +| Parameter | Nominal | Range varied | Effect assessed on | +| --- | --- | --- | --- | +| [ ] | [ ] | [ ] | [ ] | + +## 8. Statistical treatment + +- Software, version, and how calculations are verified: [ ] +- Handling of outliers, stated in advance: [ ] +- Scripts to be used and their output retained as records: [ ] + +## 9. Deviations and data integrity + +- Deviation identification, assessment and approval route: [ ] +- All results will be reported, including out-of-criteria values: [ ] confirmed +- Raw data location, audit trail, and review: [ ] + +## 10. Approvals + +| Role | Name | Signature | Date | +| --- | --- | --- | --- | +| Author | | | | +| Technical reviewer | | | | +| Quality unit | | | | -- 2.54.0 From ab40c507487d9fd9f93a7125e2321b5e3e75444c Mon Sep 17 00:00:00 2001 From: promptadmin Date: Sat, 8 Aug 2026 15:33:55 +0000 Subject: [PATCH 015/101] [upstream-sync] skills/analytical-method-validation/assets/validation-report-template.md from K-Dense-AI/scientific-agent-skills@991bd993 [unknown] --- .../assets/validation-report-template.md | 129 ++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/assets/validation-report-template.md diff --git a/upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/assets/validation-report-template.md b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/assets/validation-report-template.md new file mode 100644 index 00000000..1059c782 --- /dev/null +++ b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/assets/validation-report-template.md @@ -0,0 +1,129 @@ +--- +title: "Analytical Procedure Validation Report" +task: "" +lineage_type: import +upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/991bd993/skills/analytical-method-validation/assets/validation-report-template.md +upstream_sha: 991bd993 +imported_at: 2026-08-08 +prompt_class: unknown +upstream_changes: accepted +author: upstream +validated: false +--- + +# Analytical Procedure Validation Report + +> Reports the outcome against criteria stated in the approved protocol. If a criterion here differs +> from the protocol, that is a deviation to be documented, not an edit to be made. + +| Field | Value | +| --- | --- | +| Report number / version | [ ] | +| Protocol number / version executed | [ ] | +| Analytical procedure identifier and version | [ ] | +| Governing framework | [ ] | +| Execution dates | [ ] | +| Analysts and instruments | [ ] | +| Author / date | [ ] | +| Technical reviewer / date | [ ] | +| Quality unit approval / date | [ ] | + +## 1. Summary of outcome + +| Characteristic | Criterion (from protocol) | Result | Interval reported | Met | +| --- | --- | --- | --- | --- | +| Specificity / selectivity | [ ] | [ ] | — | [ ] | +| Response | [ ] | [ ] | [ ] | [ ] | +| Lower range limit (DL / QL) | [ ] | [ ] | — | [ ] | +| Accuracy | [ ] | [ ] | [ ] | [ ] | +| Repeatability | [ ] | [ ] | [ ] | [ ] | +| Intermediate precision | [ ] | [ ] | [ ] | [ ] | + +- Validated reportable range: [ ] +- Statement of fitness for the intended purpose, and who is making it: [ ] + +## 2. Response + +- Levels and replicates actually run: [ ] +- Calibration model and weighting: [ ] +- Slope, intercept, and their confidence intervals: [ ] +- Coefficient of determination: [ ] +- **Analysis of deviation from the regression line** (residual plot, lack-of-fit test, back-calculated + relative error per level): [ ] + +## 3. Accuracy + +| Level | n | Mean recovery (%) | Bias (%) | Confidence interval | Met | +| --- | --- | --- | --- | --- | --- | +| [ ] | [ ] | [ ] | [ ] | [ ] | [ ] | + +- Approach used: [ ] reference material / spiking / orthogonal comparison +- For impurities, basis of determination: [ ] w/w / area % + +## 4. Precision + +| Level | Component | SD | %RSD | df | Interval | Met | +| --- | --- | --- | --- | --- | --- | --- | +| [ ] | repeatability | [ ] | [ ] | [ ] | [ ] | [ ] | +| [ ] | between-group | [ ] | [ ] | [ ] | — | — | +| [ ] | intermediate precision | [ ] | [ ] | [ ] | [ ] | [ ] | + +- Intermediate precision factors varied: [ ] days / analysts / instruments / environment +- Reproducibility, if performed: [ ] + +## 5. Lower range limits + +- DL, and **the approach used to determine it**: [ ] +- QL, and **the approach used to determine it**: [ ] +- Confirmation of the estimated limit with samples at or near it: [ ] +- For impurity procedures, QL relative to the reporting threshold: [ ] + +## 6. Specificity and stability-indicating properties + +- Interference results: [ ] +- Forced degradation results and peak purity / mass balance: [ ] +- Relative response factors, and any correction factor applied: [ ] + +## 7. Robustness + +| Parameter | Range varied | Effect on the reportable result | Conclusion | +| --- | --- | --- | --- | +| [ ] | [ ] | [ ] | [ ] | + +- Solution stability demonstrated over: [ ] + +## 8. Deviations + +| # | Description | Assessment of impact | Disposition | Approved by | +| --- | --- | --- | --- | --- | +| [ ] | [ ] | [ ] | [ ] | [ ] | + +- Out-of-criteria individual results, and whether they were included in the reported statistics: [ ] + +## 9. Raw data traceability + +Every reported number must be traceable to a retained record. A report whose numbers cannot be +reproduced from the raw data is the finding that costs the most to remediate. + +| Reported item | Raw data location | Instrument / system | Acquisition date | Reviewed by | +| --- | --- | --- | --- | --- | +| [ ] | [ ] | [ ] | [ ] | [ ] | + +- Software and version used for calculations: [ ] +- Calculation verification method: [ ] +- Script outputs retained as records: [ ] + +## 10. Conclusion and lifecycle + +- Conclusion against the ATP / intended purpose: [ ] +- Conditions or limitations on use: [ ] +- Ongoing performance monitoring planned: [ ] +- Revalidation triggers identified: [ ] + +## 11. Approvals + +| Role | Name | Signature | Date | +| --- | --- | --- | --- | +| Author | | | | +| Technical reviewer | | | | +| Quality unit | | | | -- 2.54.0 From 7ba26c1744f38d677dc581c51b338d5d45cf19c7 Mon Sep 17 00:00:00 2001 From: promptadmin Date: Sat, 8 Aug 2026 15:34:08 +0000 Subject: [PATCH 016/101] [upstream-sync] skills/analytical-method-validation/references/compendial-and-clsi.md from K-Dense-AI/scientific-agent-skills@991bd993 [unknown] --- .../references/compendial-and-clsi.md | 109 ++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/references/compendial-and-clsi.md diff --git a/upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/references/compendial-and-clsi.md b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/references/compendial-and-clsi.md new file mode 100644 index 00000000..d54016d5 --- /dev/null +++ b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/references/compendial-and-clsi.md @@ -0,0 +1,109 @@ +--- +title: "Compendial, CLSI, and ISO Sources (No Standard Text)" +task: "" +lineage_type: import +upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/991bd993/skills/analytical-method-validation/references/compendial-and-clsi.md +upstream_sha: 991bd993 +imported_at: 2026-08-08 +prompt_class: unknown +upstream_changes: accepted +author: upstream +validated: false +--- + +# Compendial, CLSI, and ISO Sources (No Standard Text) + +Research basis: **2026-07-27**. This reference identifies documents, their scope, and where to obtain +them. **It does not reproduce their requirements, thresholds, or study designs**, because they are +copyrighted and paywalled. + +## Copyright boundary + +USP–NF general chapters, CLSI documents, and ISO/IEC standards are copyrighted works sold by their +publishers. Do not ask an agent to retrieve, transcribe, summarise clause-by-clause, reconstruct, or +store their text. Vendor application notes and training decks that quote them are equally +constrained, and a paraphrase that carries the same numbers is still a reproduction of the +substantive content. + +The practical consequence: **when a numeric criterion or a study design lives in one of these +documents, read it from the authorised copy.** An agent asked for "the USP <621> tailing factor +limit" or "the CLSI EP15 number of days" will produce a plausible number. Plausible is not the same +as correct, and the difference is discovered at audit. + +Record publisher, title, designation, edition, amendments, authorised location, access date, and +review date in the laboratory's controlled source register. + +## USP–NF general chapters + +| Chapter | Title | Scope | +| --- | --- | --- | +| `<1220>` | Analytical Procedure Life Cycle | Three-stage lifecycle: procedure design (Stage 1), performance qualification (Stage 2), ongoing performance verification (Stage 3), organised around an analytical target profile. Official 1 May 2022 (incorporated into USP–NF 2022 Issue 1 on 1 Nov 2021). Integrates the concepts previously spread across `<1224>`, `<1225>`, and `<1226>`. | +| `<1225>` | Validation of Compendial Procedures | Validation of non-compendial procedures, and of compendial procedures used outside their stated scope. Stage 2 activity under `<1220>`. | +| `<1226>` | Verification of Compendial Procedures | Assessment of selected performance characteristics showing a compendial procedure works under actual conditions of use. **Verification is not revalidation** and does not repeat the full validation. | +| `<1224>` | Transfer of Analytical Procedures | Transfer between laboratories. | +| `<1010>` | Analytical Data — Interpretation and Treatment | Statistical treatment of analytical data. | +| `<621>` | Chromatography | System suitability and chromatographic operating parameters, including the extent to which a compendial procedure may be adjusted without triggering revalidation. | +| `<711>` / `<1092>` | Dissolution / The Dissolution Procedure | Dissolution testing and development/validation of the procedure. | + +Obtain from the USP–NF (). Regional pharmacopoeias — Ph. Eur., JP, ChP — +carry their own general chapters; check which pharmacopoeia the specification cites, because +adjustment allowances and system suitability requirements differ between them. + +**The `<1226>` decision.** Verification applies when using a compendial procedure as written and +within its scope. Two situations push you back to `<1225>` validation: using the procedure outside +its stated scope (a different matrix, a different dosage form, a concentration range it does not +cover), or modifying it beyond the adjustments the relevant chapter permits. Getting this wrong in +either direction is expensive — unnecessary full validation, or an unsupported claim of verification. + +## CLSI EP series + +Designations and titles below were taken from clsi.org listings and secondary sources on the +research date. **Editions change; confirm the current edition on before designing +a study.** Marked `[confirm]` where the edition was not read from the publisher directly. + +| Designation | Subject | Note | +| --- | --- | --- | +| EP05 | Evaluation of precision of quantitative measurement procedures | Establishment of precision; the multi-day/multi-run designs. `[confirm edition]` | +| EP06 | Evaluation of linearity of quantitative measurement procedures | 2nd edition reported. `[confirm edition]` | +| EP07 | Interference testing in clinical chemistry | Screening, quantifying and confirming interferents; verifying manufacturer interference claims. 3rd edition reported. `[confirm edition]` | +| EP09 | Measurement procedure comparison and bias estimation using patient samples | The method-comparison document. 3rd edition reported. `[confirm edition]` | +| EP15 | User verification of precision and estimation of bias | The short study a laboratory runs to verify a manufacturer's claims. 3rd edition reported. `[confirm edition]` | +| EP17 | Evaluation of detection capability | Limit of blank, limit of detection, limit of quantitation; verification of manufacturer claims. `[confirm edition]` | +| EP25 | Evaluation of stability of in vitro diagnostic reagents | `[confirm edition]` | +| EP28 | Defining, establishing, and verifying reference intervals | Formerly designated C28. An implementation guide (EP28IG) also exists. `[confirm edition]` | + +**Vocabulary.** CLSI distinguishes *limit of blank*, *limit of detection*, and *limit of quantitation* +as three separate quantities with separate protocols. This is not the same taxonomy as ICH Q2(R2)'s +detection limit and quantitation limit, and the two should not be translated into each other +casually — the underlying definitions and the experiments differ. + +**Verification versus establishment.** For an FDA-cleared or CE-marked assay used as intended, a +laboratory *verifies* the manufacturer's performance claims — a bounded study. For a +laboratory-developed test, or an assay used off-label, the laboratory *establishes* performance, +which is a much larger exercise. Under CLIA the distinction has direct regulatory consequences and +also depends on test complexity. Determine which applies before designing anything. + +## ISO standards + +| Standard | Relevance | +| --- | --- | +| ISO/IEC 17025:2017 | Clause 7.2 selection, verification and validation of methods; clause 7.6 measurement uncertainty. Validation "to the extent necessary" for the intended application — no characteristic list, no numeric criteria. | +| ISO 15189 | Medical laboratories: quality and competence. The clinical-laboratory counterpart to 17025. | +| ISO 21748 / ISO 5725 series | Using repeatability, reproducibility and trueness estimates in measurement uncertainty; accuracy of measurement methods. | + +Obtain from ISO () or a national member body. A laboratory is **accredited** to +ISO/IEC 17025 by an accreditation body — it is not "17025 certified", and writing "certified" is a +substantive error assessors notice. + +For accreditation readiness, the quality manual, and the surrounding management system, use this +repository's `iso-standards-readiness` skill. This skill stays at the level of the individual +procedure. + +## Environmental, food, and forensic method systems + +Where a prescribed method system governs — a published EPA method, an AOAC Official Method, a +standard method for water or food analysis — the validation and quality-control requirements are +written into the method or the programme, and they take precedence. Do not substitute a +pharmaceutical framework. Common differences: matrix spike and duplicate requirements per batch, +prescribed calibration-verification frequencies, method detection limit procedures that differ from +both ICH and CLSI, and mandatory participation in proficiency testing schemes. -- 2.54.0 From a954e37a6dc7b76658c6968b3bef9eedd0f3eb37 Mon Sep 17 00:00:00 2001 From: promptadmin Date: Sat, 8 Aug 2026 15:34:20 +0000 Subject: [PATCH 017/101] [upstream-sync] skills/analytical-method-validation/references/framework-selection.md from K-Dense-AI/scientific-agent-skills@991bd993 [unknown] --- .../references/framework-selection.md | 100 ++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/references/framework-selection.md diff --git a/upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/references/framework-selection.md b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/references/framework-selection.md new file mode 100644 index 00000000..8880cd06 --- /dev/null +++ b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/references/framework-selection.md @@ -0,0 +1,100 @@ +--- +title: "Which Framework Governs" +task: "" +lineage_type: import +upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/991bd993/skills/analytical-method-validation/references/framework-selection.md +upstream_sha: 991bd993 +imported_at: 2026-08-08 +prompt_class: unknown +upstream_changes: accepted +author: upstream +validated: false +--- + +# Which Framework Governs + +Research basis: **2026-07-27**. Confirm every date and edition against the official source before +relying on it; see `source-ledger.md`. + +Framework selection is the first decision and the one most often skipped. Getting it wrong +invalidates the protocol regardless of how well the studies are executed, because each framework +requires a different set of characteristics, a different study layout, and a different treatment of +acceptance criteria. + +## The deciding questions, in order + +**1. Is the measurand a drug concentration in a biological matrix, supporting a nonclinical or +clinical study?** +→ **ICH M10.** This covers pharmacokinetics, toxicokinetics, and bioequivalence. M10 supplies +explicit numeric criteria, and they differ between chromatographic assays and ligand binding +assays. Q2(R2) does not govern here. + +**2. Is it a quality attribute of a drug substance or drug product — assay, potency, impurity, +identity, dissolution, content uniformity?** +→ **ICH Q2(R2)** for validation, with **ICH Q14** for development, robustness, the analytical +target profile, and lifecycle change management. If the procedure is compendial and being used as +written, see question 3 first. + +**3. Is the procedure a compendial (pharmacopoeial) procedure?** +→ **USP <1226> verification** if it is used as written and within its stated scope. Verification +assesses selected characteristics to show the procedure works under actual conditions of use; it is +not revalidation and does not repeat the full study. → **USP <1225> validation** if the procedure +is non-compendial, or compendial but used outside its scope. Both sit inside the **USP <1220>** +three-stage lifecycle. Regional pharmacopoeias (Ph. Eur., JP) have their own general chapters — +check which pharmacopoeia the specification cites. + +**4. Is it a clinical laboratory measurement procedure reporting patient results?** +→ **CLSI EP series**, inside a CLIA/CAP or ISO 15189 quality system. The vocabulary differs from +pharmaceutical work: *verification* of a manufacturer's claims for an FDA-cleared assay is a much +smaller exercise than *establishment* of performance for a laboratory-developed test, and the +distinction is regulatory, not stylistic. + +**5. Is the laboratory accredited to ISO/IEC 17025 and the method non-standard, laboratory-developed, +or a modified standard method?** +→ **ISO/IEC 17025 clause 7.2.2** requires validation as extensive as necessary to meet the needs of +the intended application, plus measurement uncertainty under clause 7.6. It sets no characteristic +list and no numeric criteria; the laboratory justifies both. + +**6. Is it an environmental, food, or forensic method under a prescribed method system?** +→ The method system governs (for example a published EPA method, an AOAC Official Method, or a +regulator's prescribed procedure), usually with its own validation and QC requirements written into +the method itself. Do not substitute a pharmaceutical framework. + +## More than one can apply + +Common and legitimate. A contract laboratory accredited to ISO/IEC 17025 running a compendial assay +for a pharmaceutical client satisfies <1226> for the procedure and 17025 clause 7.2 for the +accreditation scope, with the client's specification supplying the criteria. Record which framework +each requirement traces to, so a later change can be assessed against the right one. + +## Do not blend them + +The failure mode is a protocol that mixes Q2(R1)-era characteristic names, an M10 numeric tolerance +imported because it was memorable, and a CLSI study layout. It satisfies none of the three and is +hard to defend because no single source can be cited for any of it. If a requirement is in the +protocol, name the framework and section it comes from. + +## Where the numbers come from + +| Framework | Numeric acceptance criteria | +| --- | --- | +| ICH Q2(R2) | Almost none. Derive from the specification, the ATP, or development data, and justify. | +| ICH Q14 | None. It supplies the ATP concept and the development/robustness framework. | +| ICH M10 | Explicit, and modality-dependent. Use them as written. | +| USP <1225>/<1226>/<1220> | Consult the authorised text. | +| CLSI EP | Consult the authorised text; many EP documents supply study designs rather than limits. | +| ISO/IEC 17025 | None. The laboratory sets and justifies them. | + +Q2(R2)'s reticence is deliberate: a criterion that is not tied to what the result is used for is +arbitrary. An assay releasing product against a 95.0–105.0% specification needs different precision +than one supporting a 70–130% content-uniformity limit. Deriving the criterion from the decision the +result supports is the substance of the exercise, not paperwork around it. + +## Related skills in this repository + +- `iso-standards-readiness` — the surrounding quality system (ISO/IEC 17025, ISO 15189 + accreditation readiness, quality manual, CAPA). That skill operates at the laboratory level; this + one operates at the level of a single procedure. +- `statistical-analysis`, `statistical-power` — general inference and study sizing. +- `uncertainty-and-units` — unit handling and measurement uncertainty propagation, which ISO/IEC + 17025 clause 7.6 requires alongside validation. -- 2.54.0 From 4c78e0c77602394bf278e6d8e838bd9b318105bc Mon Sep 17 00:00:00 2001 From: promptadmin Date: Sat, 8 Aug 2026 15:34:31 +0000 Subject: [PATCH 018/101] [upstream-sync] skills/analytical-method-validation/references/ich-m10-bioanalytical.md from K-Dense-AI/scientific-agent-skills@991bd993 [unknown] --- .../references/ich-m10-bioanalytical.md | 136 ++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/references/ich-m10-bioanalytical.md diff --git a/upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/references/ich-m10-bioanalytical.md b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/references/ich-m10-bioanalytical.md new file mode 100644 index 00000000..8d377e9e --- /dev/null +++ b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/references/ich-m10-bioanalytical.md @@ -0,0 +1,136 @@ +--- +title: "ICH M10 — Bioanalytical Criteria, by Modality" +task: "" +lineage_type: import +upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/991bd993/skills/analytical-method-validation/references/ich-m10-bioanalytical.md +upstream_sha: 991bd993 +imported_at: 2026-08-08 +prompt_class: unknown +upstream_changes: accepted +author: upstream +validated: false +--- + +# ICH M10 — Bioanalytical Criteria, by Modality + +Research basis: **2026-07-27**, read from the ICH Harmonised Guideline *Bioanalytical Method +Validation and Study Sample Analysis M10*, Step 4 dated 24 May 2022. ICH licenses its documents for +reuse with acknowledgement. Confirm the current text and your region's implementation at +. + +M10 harmonised what had been separate FDA and EMA bioanalytical guidance for studies in its scope: +methods quantifying drug and metabolite concentrations in biological matrices supporting nonclinical +and clinical studies, plus the analysis of study samples. + +## The distinction that matters most + +**Chromatographic assays (section 3) and ligand binding assays (section 4) have different numeric +criteria throughout.** They are not stylistic variants of one set. Applying chromatographic +tolerances to an LBA is the most common error in this area, and importing the LBA total-error +criterion into a chromatographic method is its mirror image. + +| | Chromatographic | Ligand binding assay | +| --- | --- | --- | +| Calibration levels (minimum) | 6, including LLOQ | 6, including LLOQ | +| Calibration standard tolerance | ±15% | ±20% | +| … at LLOQ | ±20% | ±25% | +| … at ULOQ | ±15% | ±25% | +| Calibration standards that must pass | ≥75% | ≥75%, excluding anchor points | +| Accuracy | ±15% | ±20% | +| … at limits | ±20% at LLOQ | ±25% at LLOQ **and** ULOQ | +| Precision (%CV) | ≤15% | ≤20% | +| … at limits | ≤20% at LLOQ | ≤25% at LLOQ **and** ULOQ | +| A&P QC levels | minimum 4 | 5 (LLOQ, low, medium, high, ULOQ) | +| A&P replicates per level per run | ≥5 (within-run) | ≥3 | +| A&P runs | ≥3 runs over ≥2 days | ≥6 runs over ≥2 days | +| **Total error** | **no such criterion** | **≤30%; ≤40% at LLOQ and ULOQ** | +| Routine run QC tolerance | ±15% | ±20% | +| Routine run QC pass rule | ≥2/3 of all QCs **and** ≥50% at each level | same rule, ±20% | +| Dilution integrity | mean within ±15% | mean within ±20% | +| Stability | mean at each QC level within ±15% | mean within ±20% | +| ISR agreement | within ±20% for ≥2/3 of repeats | within ±30% for ≥2/3 of repeats | +| Selectivity sources/lots | ≥6 individual sources | ≥6 individual sources | +| Carry-over in blank | ≤20% of LLOQ analyte response and ≤5% of IS response | per guideline | + +Verify any figure against the guideline before using it in a protocol; regional implementation and +subsequent revisions can change the picture. + +## Chromatographic QC placement (section 3) + +Accuracy and precision validation QCs at a minimum of **four** concentration levels: + +- the **LLOQ** +- **low QC** — within three times the LLOQ +- **medium QC** — around 30–50% of the calibration curve range +- **high QC** — at least 75% of the ULOQ + +For runs that are not accuracy-and-precision runs, low, medium and high QCs may be analysed in +duplicate; these plus the calibration standards form the basis for accepting or rejecting the run. + +Calibration standards and QCs should be prepared from **separate stock solutions**, to avoid a bias +that is not a property of the analytical performance. If a single stock must serve both, verify the +accuracy and stability of that stock. A single source of blank matrix may be used if it is free of +interference and matrix effects. + +Calibration curves for accuracy and precision assessment should use freshly spiked standards in at +least one run; if other runs use frozen standards, demonstrate their stability. + +## Reporting obligations that catch people out + +**Report everything.** Validation data and the determination of accuracy and precision must include +*all* results obtained, including individual QCs outside the acceptance criteria — except cases where +errors are obvious and documented. Silently dropping an out-of-criteria QC is a data integrity +problem, not a rounding decision. + +**Within-run accuracy and precision are reported per run.** If the within-run criteria are not met in +every run, calculate an overall estimate of within-run accuracy and precision for each QC level. +Between-run (intermediate) accuracy and precision combine data from all runs. + +**Trend within a run.** It is recommended to demonstrate accuracy and precision over at least one run +sized like a prospective study-sample run, so time-dependent drift is visible. + +## Incurred sample reanalysis (section 5) + +ISR repeats the analysis of a subset of study samples in separate runs, to verify that measured +concentrations in real samples are reproducible. It is not a substitute for QCs — QCs are spiked, +incurred samples are not, and only incurred samples can reveal metabolite back-conversion, protein +binding effects, or matrix instability. + +- The extent depends on the analyte and the samples and should be justified. +- Objective criteria for choosing the subset should be **predefined**; selecting samples around + Cmax and the elimination phase is recommended. +- **Do not pool samples** — pooling masks anomalous findings. +- ISR samples and QCs are processed and analysed in the same manner as the original analysis. +- Percent difference is `(repeat value - initial value) / mean value x 100` -- assessed + against the **mean of the two**, not against the initial value. +- Repeats are performed within the analyte's stability window, but **not on the same day** + as the original analysis. +- Acceptance: within ±20% for at least 2/3 of repeats (chromatographic), or within ±30% for at least + 2/3 (LBA). + +For nonclinical studies in scope, ISR should in general be performed; the guideline notes incurred +samples need only be included if available, so inclusion was not felt to be mandatory in every case. +Confirm the situations requiring ISR against the guideline text for your study type. + +## Study sample reanalysis is a separate thing + +ISR is a method-reliability check. *Reanalysis of study samples* for a reportable-value decision is +different, and the reasons for reanalysis, the number of replicates, and the criteria for selecting +the value to report must be **predefined in the protocol, study plan, or SOP before study sample +analysis begins.** Deciding after the fact which of two values to report is the classic finding. + +## Partial and cross validation + +M10 addresses partial validation (a change to a validated method — matrix, anticoagulant, species, +instrument, or a range change) and cross validation (comparing data from two methods or two +laboratories contributing to the same study). Both are scoped by the change and the risk; consult +the guideline for what each requires. For a cross validation between sites or methods, the +statistics in `compare_methods.py` — equivalence testing against a pre-stated margin, and a +regression that allows error in both measurements — are the appropriate treatment. + +## Biomarkers and other contexts + +M10's scope centres on drug and metabolite concentration measurement. Biomarker assays, immunogenicity +assays, and diagnostic measurements are addressed differently or fall outside scope; do not assume the +concentration-assay criteria transfer. Where a biomarker assay supports a regulatory decision, the +fit-for-purpose framework and the applicable regional guidance govern the extent of validation. -- 2.54.0 From c401daf4a067887e1807a139ce764aae50679802 Mon Sep 17 00:00:00 2001 From: promptadmin Date: Sat, 8 Aug 2026 15:34:43 +0000 Subject: [PATCH 019/101] [upstream-sync] skills/analytical-method-validation/references/ich-q2r2.md from K-Dense-AI/scientific-agent-skills@991bd993 [unknown] --- .../references/ich-q2r2.md | 242 ++++++++++++++++++ 1 file changed, 242 insertions(+) create mode 100644 upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/references/ich-q2r2.md diff --git a/upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/references/ich-q2r2.md b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/references/ich-q2r2.md new file mode 100644 index 00000000..a53f1f7f --- /dev/null +++ b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/references/ich-q2r2.md @@ -0,0 +1,242 @@ +--- +title: "ICH Q2(R2) — Structure and Recommended Data" +task: "" +lineage_type: import +upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/991bd993/skills/analytical-method-validation/references/ich-q2r2.md +upstream_sha: 991bd993 +imported_at: 2026-08-08 +prompt_class: unknown +upstream_changes: accepted +author: upstream +validated: false +--- + +# ICH Q2(R2) — Structure and Recommended Data + +Research basis: **2026-07-27**, read from the ICH Harmonised Guideline *Validation of Analytical +Procedures Q2(R2)*, Final Version adopted 1 November 2023, with the error correction dated +30 November 2023. ICH licenses its documents for reuse with acknowledgement, so requirements are +summarised here directly. Confirm the current text and your region's implementation date at +. + +## Document history that matters + +| Version | Date | Note | +| --- | --- | --- | +| Q2A | Oct 1994 | Text | +| Q2B | Nov 1996 | Methodology | +| Q2(R1) | Nov 2005 | Q2B merged into the parent guideline | +| Q2(R2) | 1 Nov 2023 | Complete revision, aligned with the new Q14 | +| Q2(R2) correction | 30 Nov 2023 | Table 5 reportable-range linearity formulae; Tables 6–11 | + +If a protocol cites "ICH Q2(R1)" or lists characteristics in the R1 order, it is working from the +superseded structure. The error correction is easy to miss and applies to the dissolution example +and to Annex 2 Tables 6–11. + +## The restructure + +Q2(R1) presented a flat list. Q2(R2) groups methodology under section 3 by performance +characteristic: + +``` +3.1 Specificity/Selectivity + 3.1.1 General considerations (absence of interference, orthogonal comparison, + technology-inherent justification) +3.2 Range <-- parent characteristic + 3.2.2 Response + 3.2.2.1 Linear response <-- what R1 called "linearity" + 3.2.2.2 Non-linear response + 3.2.2.3 Multivariate calibration + 3.2.3 Validation of lower range limits <-- what R1 called LOD and LOQ +3.3 Accuracy and Precision + 3.3.1 Accuracy + 3.3.2 Precision (repeatability, intermediate precision, reproducibility) + 3.3.3 Combined approaches for accuracy and precision <-- new +3.4 Robustness --> largely a development activity, see ICH Q14 +``` + +Section 2 carries the general considerations, including two concepts absent from R1: **reportable +range** (2.3) and **considerations for multivariate analytical procedures** (2.5). + +## Table 1 — which tests for which measured attribute + +Required tests follow the *measured quality attribute*, not the instrument. + +| Characteristic | Identity | Impurity: quantitative | Impurity: limit test | Assay (content/potency) | +| --- | --- | --- | --- | --- | +| Specificity test | yes | yes | yes | yes | +| Response (calibration model) | no | yes | no | yes | +| Lower range limit | no | QL† | DL | no | +| Accuracy test | no | yes | no | yes | +| Repeatability test | no | yes | no | yes | +| Intermediate precision test | no | yes‡ | no | yes‡ | + +† In some complex cases DL may also be evaluated. +‡ Not required independently where reproducibility has been performed and intermediate precision +can be derived from that dataset. + +Further notes from Table 1: other quantitative measurements follow the impurity scheme when the +range limit is close to DL/QL, and the assay scheme when it is not. Some characteristics may be +substituted by technology-inherent justification for physicochemical properties. Lack of specificity +in one procedure should be compensated by one or more supporting procedures unless justified. + +## Table 2 — reportable range examples + +The reportable range derives from the specification and must include the upper and lower +specification or reporting limits. Other ranges are acceptable if justified; at low amounts a wider +upper range may be more practical. + +| Use | Low end | High end | +| --- | --- | --- | +| Assay of a product | 80% of declared content, or 80% of the lower specification limit | 120% of declared content, or 120% of the upper specification limit | +| Potency | lowest specification limit −20% | highest specification limit +20% | +| Content uniformity | 70% of declared content | 130% of declared content | +| Dissolution, IR, one point | Q − 45% of the lowest strength specification | per specification | +| Dissolution, IR, multi-point | lower limit as justified, or QL | 130% of declared content of the highest strength | +| Dissolution, modified release | lower limit as justified, or QL | per specification | +| Impurity | reporting threshold | 120% of the specification limit | +| Purity (area %) | 80% of the lower specification limit | upper specification limit, or 100% | + +Where assay and impurity run as a single test with one standard, linearity must be shown both at the +impurity reporting level and up to 120% of the assay specification limit. + +**Reportable range vs working range.** The reportable range is the interval of *reported results*. +A working range is what is presented to the instrument, and may differ because of dilution or other +sample preparation. They can be identical. Mathematical calculation normally links the two. + +## Recommended data, by characteristic + +**Specificity (3.1).** Demonstrate absence of relevant interference, or compare against an +orthogonal procedure, or justify from the technology. For a stability-indicating claim (2.4), +include samples containing relevant degradation products: spiked with target analytes and known +interferences, stressed physically and chemically, and aged or stress-stored product samples. + +**Response — linear (3.2.2.1).** Evaluate across the range. **A minimum of five concentrations, +appropriately distributed, is recommended.** Report the plot, the correlation coefficient or +coefficient of determination, the y-intercept, the slope, and *an analysis of the deviation of the +actual data points from the regression line* — for a linear response, assess the impact of any +non-random pattern in the residual plot. Data may be transformed (for example logarithmically) if +necessary. Other approaches require justification. + +**Response — non-linear (3.2.2.2).** Some procedures are legitimately non-linear; immunoassays and +cell-based assays commonly give an S-shaped curve, typically modelled with four- or five-parameter +logistic functions. For these, **linearity of the concentration–response relationship is not +required.** Assess the model by non-linear regression, and evaluate whether results are proportional +to the true values across the range. + +**Response — multivariate (3.2.2.3).** Algorithms may be linear or non-linear. Accuracy depends on +the distribution of calibration samples across the range and on the reference procedure's error. +Assess how the residuals change across the calibration range, graphically. + +**Lower range limits (3.2.3).** Four approaches: + +| Approach | DL | QL | +| --- | --- | --- | +| Visual evaluation (3.2.3.1) | lowest reliably detected | lowest reliably quantitated | +| Signal-to-noise (3.2.3.2) | S/N 3:1 generally acceptable | S/N at least 10:1 | +| SD of response and slope (3.2.3.3) | 3.3σ / S | 10σ / S | +| Accuracy and precision at the limit (3.2.3.4) | — | validated directly, not estimated | + +σ may come from the SD of blank responses, the residual SD of the regression line, or the SD of +y-intercepts of regression lines. S is the calibration slope. Signal-to-noise applies only where +there is baseline noise, and the noise region should sit around where the peak would appear. + +Reporting (3.2.3.5): give the limit **and the approach used**. An estimated limit should then be +validated by analysing a suitable number of samples at or near it. **For impurity tests the QL must +be at or below the reporting threshold.** Where the QL is well below the reporting limit — roughly +ten times lower — the confirmatory validation may be omitted with justification. + +**Accuracy (3.3.1).** Establish across the reportable range under regular test conditions, including +the sample matrix and the described preparation steps. Three routes: comparison against a reference +material of known purity, a spiking study into matrix, or comparison against an orthogonal +procedure. Accuracy can be inferred once precision, response within the range, and specificity are +established. + +Recommended data (3.3.1.4): an appropriate number of determinations and levels across the reportable +range — **for example 3 concentrations × 3 replicates of the full procedure.** Report as mean percent +recovery of a known added amount, or as the difference between the mean and the accepted true value, +**together with an appropriate 100(1−α)% confidence interval** or justified alternative interval. The +observed interval should be compatible with the accuracy criterion. For impurities, state whether +the determination is weight/weight or area percent. For quantitative multivariate procedures use +RMSEP, compared against an acceptable RMSEC. + +**Precision (3.3.2).** Use authentic homogeneous samples, or artificially prepared ones if +unavailable. + +- *Repeatability (3.3.2.1)*: **a minimum of 9 determinations covering the reportable range** (for + example 3 concentrations × 3 replicates), **or a minimum of 6 determinations at 100% of the test + concentration.** +- *Intermediate precision (3.3.2.2)*: establish the effects of random events — typically different + days, environmental conditions, analysts, and equipment. **Studying these effects individually is + not necessary**, and design of experiments is encouraged. The extent should be justified from + development understanding and risk assessment (ICH Q14). +- *Reproducibility (3.3.2.3)*: an inter-laboratory trial. **Usually not required for a regulatory + submission**, but consider it for pharmacopoeial standardisation or multi-site procedures. + +Recommended data (3.3.2.4): report the standard deviation, the relative standard deviation, and an +appropriate 100(1−α)% confidence interval. + +**Combined accuracy and precision (3.3.3).** Instead of separate criteria, assess total impact +against a single combined criterion, using a prediction interval, a tolerance interval, or a +confidence interval. Report the combined value, describe the approach, and supply the individual +results as supplemental information where they help justify suitability. + +**Robustness (3.4).** Deliberate variation of procedure parameters, plus stability of sample +preparations and reagents over the duration of the procedure. Considered during development; may be +submitted as development data case-by-case or made available on request. See ICH Q14 section 5. + +## Lifecycle, transfer, and prior knowledge + +Section 2.1 permits suitable development data (ICH Q14) to form part of the validation data, and +allows abbreviated validation testing for an established platform procedure used for a new purpose, +with scientific justification. A validation protocol must exist before the study, stating the +intended purpose, the characteristics to be validated, and the associated criteria; where prior +knowledge is used, justify it. Results are summarised in a validation report. + +The experimental design should reflect the number of replicates used in routine analysis to generate +a reportable result, unless a different number is justified. + +Section 2.2 covers change: partial or full revalidation may be needed, decided on science and risk, +and scoped to the characteristics the change affects. **Transfer** to another laboratory calls for +partial or full revalidation and/or comparative analysis of representative samples; not performing +transfer experiments requires justification. **Co-validation** across multiple sites can demonstrate +the criteria are met and can simultaneously satisfy transfer at the participating sites. + +## Annex 2 — illustrative technique examples + +Non-mandatory worked examples, useful as a starting point for the robustness parameter list: + +| Table | Technique | +| --- | --- | +| 3 | Quantitative separation techniques (HPLC, GC, CE) for impurities or assay, and relative-area quantitation | +| 4 | Elemental impurities by ICP-OES or ICP-MS | +| 5 | Dissolution with HPLC as product performance test (corrected 30 Nov 2023) | +| 6 | Quantitative ¹H-NMR for assay of a drug substance | +| 7 | Biological assays | +| 8 | Quantitative PCR | +| 9 | Particle size measurement | +| 10 | NIR analytical procedure | +| 11 | Quantitative LC/MS | + +From Table 3, a detail worth carrying forward: **relative response factors.** Where the analyte +responds differently from the reference material, calculate the RRF from the appropriate ratio of +responses under final procedure conditions and document it. **If the RRF falls outside 0.8–1.2, +apply a correction factor.** Where an impurity is overestimated, omitting the correction may be +acceptable. + +## Multivariate procedures (2.5) + +Results come from a model relating many input variables to the property of interest. Validate in two +phases: + +1. **Model development** — calibration plus internal testing. Test data may be a separate set or + part of the calibration set used rotationally, and are used to estimate performance and tune + parameters such as the number of PLS latent variables. See ICH Q14. +2. **Model validation** — an independent validation set. For identification libraries, analyse + challenge samples *not* represented in the library to demonstrate discriminative ability. + +Samples need reference values or categories, normally from a validated or pharmacopoeial reference +procedure whose performance **equals or exceeds** the expected performance of the multivariate +procedure. Reference measurement and multivariate data collection should be on the same samples +within a period short enough to assure sample and measurement stability. Describe any correlation or +unit conversion, and any assumptions. -- 2.54.0 From 60013b3f85c658d62925242d9ebf01dedf52dfd3 Mon Sep 17 00:00:00 2001 From: promptadmin Date: Sat, 8 Aug 2026 15:34:54 +0000 Subject: [PATCH 020/101] [upstream-sync] skills/analytical-method-validation/references/source-ledger.md from K-Dense-AI/scientific-agent-skills@991bd993 [unknown] --- .../references/source-ledger.md | 138 ++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/references/source-ledger.md diff --git a/upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/references/source-ledger.md b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/references/source-ledger.md new file mode 100644 index 00000000..3dcb0bb8 --- /dev/null +++ b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/references/source-ledger.md @@ -0,0 +1,138 @@ +--- +title: "Official Source Ledger" +task: "" +lineage_type: import +upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/991bd993/skills/analytical-method-validation/references/source-ledger.md +upstream_sha: 991bd993 +imported_at: 2026-08-08 +prompt_class: unknown +upstream_changes: accepted +author: upstream +validated: false +--- + +# Official Source Ledger + +**Research date: 2026-07-27.** Every framework claim in this skill traces to an entry below. +Re-check each source before operational use — guidelines are revised, editions change, and regional +implementation dates differ from adoption dates. + +This ledger is a version baseline. It is not legal advice, an applicability determination, or a +substitute for a controlled copy held under the laboratory's document control. + +## Documents read directly + +These were downloaded and read as full text on the research date, so the requirements encoded in +`scripts/_catalog.py` and summarised in `references/ich-q2r2.md` and +`references/ich-m10-bioanalytical.md` come from the primary source rather than from secondary +summaries. + +### ICH Q2(R2) Validation of Analytical Procedures + +- Source read: +- Verified metadata: Final Version, adopted by the ICH Assembly Regulatory Members under Step 4 on + **1 November 2023**. Step 2 endorsement 24 March 2022. Supersedes Q2(R1) (November 2005). +- Verified detail: an **error correction dated 30 November 2023** covers Table 5 (dissolution with + HPLC, reportable range linearity formulae, page 25) and Tables 6–11 (pages 26–32). +- Content taken: section structure; Table 1 (tests by measured attribute); Table 2 (reportable range + examples); recommended data for specificity, response, lower range limits, accuracy, precision, + and robustness; sections 2.1–2.5; Annex 1 and Annex 2 table inventory; the relative response factor + 0.8–1.2 rule from Annex 2 Table 3. +- Licence: ICH permits use, reproduction, adaptation and distribution under a public licence provided + ICH's copyright is acknowledged. Acknowledged here and in `scripts/_catalog.py`. +- Limitation: **adoption is not implementation.** Confirm the date from which your regional regulator + expects Q2(R2) with that regulator. + +### ICH M10 Bioanalytical Method Validation and Study Sample Analysis + +- Source read: +- Verified metadata: Step 4, dated **24 May 2022**. +- Content taken: chromatographic criteria (section 3) — calibration levels and tolerances, QC + placement at four levels with the low/medium/high definitions, within-run and between-run accuracy + and precision design and criteria, routine-run QC pass rules, carry-over, selectivity source count, + dilution integrity, stability; ligand binding assay criteria (section 4) — calibration tolerances + including anchor point exclusion, five QC levels, run and replicate structure, accuracy and + precision criteria at LLOQ and ULOQ, and the total error criterion; incurred sample reanalysis + (section 5) including the percent-difference basis and the pass fractions. +- Verified distinction: the **total error criterion (≤30%, ≤40% at LLOQ and ULOQ) appears for ligand + binding assays**. No equivalent criterion was found for chromatographic assays. +- Licence: as for Q2(R2). +- Limitation: regional implementation dates differ. Confirm with the regional regulator. + +### ICH Q14 Analytical Procedure Development + +- Source read: +- Content taken: section structure; the minimal versus enhanced approaches (section 2.1); the + analytical target profile (section 3) and that its formal documentation and submission is + **optional**; robustness and parameter ranges (section 5); established conditions (section 6.1); + lifecycle management and post-approval change (section 7); multivariate procedures (section 8). +- Adopted alongside Q2(R2) by the ICH Assembly in the same session. +- Licence: as for Q2(R2). + +## Documents identified but not read (paywalled) + +Designation, title, and scope only. **No requirement, threshold, or study design from any of these is +reproduced anywhere in this skill.** Where a numeric criterion is needed, read it from an authorised +copy. + +### USP–NF general chapters + +- Official pages: `<1220>` ; + `<1225>` ; + `<1226>` +- Verified metadata for `<1220>`: incorporated into USP–NF 2022 Issue 1 on **1 November 2021**, + **official 1 May 2022**. It brings the concepts of `<1224>`, `<1225>` and `<1226>` into a single + three-stage lifecycle. `<1225>` covers validation, particularly Stage 2 activities under `<1220>`; + `<1226>` covers verification of compendial procedures. +- Provenance limitation: this metadata came from **secondary sources** (publisher notices and trade + press) rather than from the USP–NF text, which is behind subscription. Marked + **[confirm in USP–NF]**. Confirm the current official text, revision, and any subsequent change. +- Chapters referenced by designation only, not read: `<1224>`, `<1010>`, `<621>`, `<711>`, `<1092>`. + +### CLSI EP series + +- Publisher: +- Designations and subjects recorded in `references/compendial-and-clsi.md`: EP05, EP06, EP07, EP09, + EP15, EP17, EP25, EP28 (formerly C28), plus the EP17IG and EP28IG implementation guides. +- Provenance limitation: designations, titles and edition numbers were taken from **clsi.org product + listings and secondary sources** on the research date, not read from the documents. Every edition + number carries **[confirm edition]** in the reference file. Editions change; verify on clsi.org + before designing a study. + +### ISO standards + +- ISO/IEC 17025:2017 — . Edition 3; supersedes the 2005 + edition. Relevant clauses: 7.2 (selection, verification and validation of methods), 7.6 + (measurement uncertainty). Not read; identified by catalogue metadata. +- ISO 15189, ISO 21748, ISO 5725 series — referenced by designation and scope only. +- Provenance limitation: ISO catalogue pages have historically refused automated access. Confirm + edition and status on iso.org or with a national member body. **[confirm on iso.org]** +- See this repository's `iso-standards-readiness` skill and its own source ledger for the + accreditation-level treatment of these standards. + +## Statistical methods + +The statistical procedures in `references/statistics.md` and `scripts/_common.py` are standard +published methods, not requirements of any framework: + +- Incomplete beta and gamma function implementations follow the standard continued-fraction and series + algorithms; the t, chi-square and F distributions are derived from them. +- Lack-of-fit F test against pure error: standard regression ANOVA. +- Wald–Wolfowitz runs test: standard non-parametric test of randomness in a sequence of signs. +- One-way random-effects variance components with the standard unbalanced expected-mean-square + coefficient; Satterthwaite approximation for effective degrees of freedom of the total. +- Deming regression with jackknife standard errors; Passing–Bablok with the rank-based slope interval. +- Bland–Altman bias and limits of agreement. +- Two one-sided tests (TOST) for equivalence. + +Implementations are verified against published quantiles and hand-checkable cases in +`tests/analytical-method-validation/test_scripts.py`. Where a framework prescribes a specific +statistical treatment, the framework governs — these are the general-purpose tools. + +## What is deliberately absent + +- No numeric acceptance criteria are supplied for ICH Q2(R2) work. The guideline does not set them and + neither does this skill; they come from the specification, the analytical target profile, or + development data. +- No text, table, threshold, or study design from any USP, CLSI, or ISO document. +- No claim that a procedure is validated, a run acceptable, or an investigation closed. -- 2.54.0 From 2ba58733e17459189fef75f7e29a4cf28ada9033 Mon Sep 17 00:00:00 2001 From: promptadmin Date: Sat, 8 Aug 2026 15:35:04 +0000 Subject: [PATCH 021/101] [upstream-sync] skills/analytical-method-validation/references/statistics.md from K-Dense-AI/scientific-agent-skills@991bd993 [unknown] --- .../references/statistics.md | 222 ++++++++++++++++++ 1 file changed, 222 insertions(+) create mode 100644 upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/references/statistics.md diff --git a/upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/references/statistics.md b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/references/statistics.md new file mode 100644 index 00000000..1d264e7e --- /dev/null +++ b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/analytical-method-validation/references/statistics.md @@ -0,0 +1,222 @@ +--- +title: "The Statistics, and Why Each One" +task: "" +lineage_type: import +upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/991bd993/skills/analytical-method-validation/references/statistics.md +upstream_sha: 991bd993 +imported_at: 2026-08-08 +prompt_class: unknown +upstream_changes: accepted +author: upstream +validated: false +--- + +# The Statistics, and Why Each One + +Every method in this file is implemented in `scripts/_common.py` using only the standard library. +Distribution functions are computed from the regularised incomplete beta and gamma functions, and the +implementations are checked against published quantiles in `tests/analytical-method-validation/`. + +## Calibration response + +### r² is not evidence of linearity + +The coefficient of determination measures how much of the variance in response the model explains. It +rises with the width of the calibration range and is nearly insensitive to curvature. A quadratic +response measured over a decade of concentration routinely gives r² > 0.99 while the back-calculated +result at the bottom of the range is 10% wrong. + +ICH Q2(R2) 3.2.2.1 asks for r or r², the slope, the intercept, the plot, **and an analysis of the +deviation of the actual data points from the regression line**. The last item is the one that +detects a bad model. Report r² because the guideline asks for it, not because it demonstrates +anything. + +### Lack-of-fit F test + +The correct test of a linear calibration model, and it requires replicates at some levels. + +Partition the residual sum of squares into **pure error** (scatter among replicates at the same +level, which no model can explain) and **lack of fit** (systematic deviation of level means from the +line): + +``` +F = MS_lack-of-fit / MS_pure-error, df = (k - 2, n - k) +``` + +for `k` distinct levels and `n` total points. A significant F says the straight line fails to +describe the data beyond what replicate scatter explains. Without replicates the partition is +impossible and no linearity test exists — which is a good reason to replicate at least one level, and +a reason `check_response.py` says so explicitly when it cannot run the test. + +### Residual pattern: runs test + +Curvature makes residual signs cluster: all negative at the ends and positive in the middle, or the +reverse. The Wald–Wolfowitz runs test counts sign changes and compares against the number expected +if signs were random. Too few runs is evidence of systematic misfit. It complements the F test and +works when replicates are absent, though it needs at least eight points with both signs present. + +### Heteroscedasticity and weighting + +Chromatographic response variance usually scales with concentration. Unweighted least squares +minimises absolute squared residuals, so the high-concentration points — which have the largest +absolute residuals — dominate the fit. The result is a curve that is accurate at the top of the range +and biased at the bottom, which is exactly where an impurity reporting threshold or an LLOQ sits. + +`check_response.py` compares residual variance in the top and bottom thirds of the range. A ratio +above roughly 10× with an unweighted fit is flagged; `1/x` or `1/x²` weighting is the usual remedy. +State the weighting in the protocol before validation — switching to weighting after seeing the data +to make the low end pass is not a statistical decision. + +### Back-calculated relative error + +The practical criterion: invert the fitted line, compute the concentration each response implies, +and compare against nominal at each level. This is what the procedure will actually report, and it +exposes a bad model in units an analyst and an assessor both understand. Bioanalytical work has +required it for decades; it belongs in small-molecule QC validation too. + +## Precision + +### Estimate within each level, never pooled across levels + +Pooling results from 80%, 100% and 120% levels into one standard deviation makes the range itself +appear as imprecision. The number produced is meaningless and always too large. +`check_accuracy_precision.py` estimates precision within each level, and separately provides a +level-independent view by converting to percent of nominal first. + +### Repeatability and intermediate precision are different quantities + +A one-way random-effects model on the intermediate-precision factor — day, analyst, or instrument: + +``` +observation = grand mean + group effect + residual +``` + +with `MS_within` and `MS_between` from the ANOVA table: + +``` +s²_repeatability = MS_within +s²_between = max(0, (MS_between - MS_within) / n_effective) +s²_intermediate = s²_repeatability + s²_between +``` + +For a balanced design `n_effective` is the replicates per group; unbalanced designs use the standard +expected-mean-square coefficient, which the script reports when it applies. + +The between-group variance is truncated at zero because a negative variance estimate is not +meaningful — it means the data cannot distinguish the groups. The script says so when it happens +rather than silently reporting zero. + +Why this matters: a procedure can show 0.07% RSD within a day and 1.65% RSD across days. The +within-day figure is real, and reporting it as the procedure's precision understates routine +performance by more than twenty-fold. Q2(R2) 3.3.2.2 exists precisely because the between-day +component is the one that bites in routine use. + +### Confidence intervals on a standard deviation + +A precision estimate from six or nine determinations is imprecise, and Q2(R2) 3.3.2.4 asks for an +interval alongside it. For a variance with `ν` degrees of freedom: + +``` +s · sqrt(ν / χ²_{1-α/2, ν}) < σ < s · sqrt(ν / χ²_{α/2, ν}) +``` + +These intervals are wide, and that is the point. With ν = 5 the upper bound is roughly twice the +point estimate. An RSD that lands just inside a limit on six replicates has not demonstrated that the +procedure meets the limit. For the total (intermediate) SD, which is a sum of variance components, +the effective degrees of freedom come from the Satterthwaite approximation. + +## Accuracy + +Report mean percent recovery, or the difference from the accepted true value, **with a confidence +interval** — Q2(R2) 3.3.1.4 is explicit, and a bare mean is not sufficient. The interval is +`mean ± t_{1-α/2, n-1} · s/√n` at each level. + +The stricter reading, available as `--require-ci-within-limit`, asks that the whole interval sit +inside the acceptance limit rather than just the point estimate. Q2(R2) says the observed interval +should be *compatible with* the criterion. Which reading applies is a decision to make and justify in +the protocol, before the data exist. + +### Combined accuracy and precision + +Q2(R2) 3.3.3 permits a single combined criterion assessed with a prediction interval, a tolerance +interval, or a confidence interval, instead of separate accuracy and precision criteria. This is +often the more honest framing — what matters is whether a future reportable result will be close +enough to the truth, which is a tolerance-interval question. If you use it, describe the approach and +supply the individual results as supporting information. + +## Detection and quantitation limits + +The `3.3σ/S` and `10σ/S` formulae are estimates whose value depends entirely on which σ you choose. +On the same calibration data, σ from the residual SD of the regression, from the SD of the +y-intercept, and from the SD of blank responses commonly give limits spanning a factor of two or +more. None is wrong; they answer slightly different questions. + +Consequences for practice: + +- Report the limit **and the approach**, per Q2(R2) 3.2.3.5. A number alone is not reportable. +- Confirm an estimated limit with real determinations at or near it. `3.2.3.4` allows skipping the + estimate entirely and validating the QL directly by accuracy and precision, which is cleaner. +- For impurity procedures, the QL must be at or below the reporting threshold. +- Signal-to-noise scaling assumes noise is constant with concentration. It usually is not; confirm at + the resulting level. +- CLSI's limit of blank / limit of detection / limit of quantitation are defined differently again, + with their own protocols. Do not translate between the schemes casually. + +## Method comparison and transfer + +### Ordinary least squares is the wrong regression here + +OLS assumes the x values are known without error. In a method comparison both procedures have +measurement error, and ignoring the error in x biases the slope toward zero — a regression-dilution +effect that manufactures apparent proportional bias where none exists. + +**Deming regression** accounts for error in both variables given `λ`, the ratio of error variances. +With `λ = 1` (equal precision) it reduces to orthogonal regression. Standard errors here come from a +jackknife, which avoids distributional assumptions about the slope. + +**Passing–Bablok** is non-parametric: the slope is a shifted median of all pairwise slopes, with a +rank-based confidence interval. It assumes no distribution, tolerates outliers, and is the usual +choice in clinical method comparison. Its confidence intervals are wider, honestly reflecting what +the data support. + +Report both. Agreement between them is reassuring; disagreement points to outliers or to a +distributional problem worth understanding before concluding anything. + +### Bland–Altman answers a different question + +Regression asks whether the relationship is proportional. Bland–Altman asks how far apart two +procedures are on the same sample: mean difference (bias) and limits of agreement at +`bias ± 1.96·SD`. Both matter, and neither substitutes for the other. + +Two cautions. The limits of agreement are themselves estimates with confidence intervals, which are +wide for small n — the script reports the half-width. And if the difference trends with +concentration, a single mean bias and its limits are misleading no matter how tight they look; the +script tests for that trend and flags it. + +### Equivalence: TOST, not a t test + +The default reflex at a transfer is a two-sample or paired t test, and `p > 0.05` written up as "no +significant difference, methods equivalent". This inverts the logic. A non-significant result means +the data were insufficient to detect a difference — and on a transfer dataset of ten or twenty +samples, that outcome is close to guaranteed regardless of whether the procedures agree. The test +rewards small studies. + +**Two one-sided tests** invert the hypotheses to match the question. Given a pre-stated margin `δ`, +test both `H01: difference ≤ -δ` and `H02: difference ≥ +δ`. Rejecting both concludes equivalence. +Operationally: the `(1-2α)` confidence interval on the difference must lie entirely inside `±δ`. + +A worked contrast from `compare_methods.py`: a transfer with a consistent +1.46% bias gives a paired +t-test p-value below 0.0001 — a highly significant difference — while TOST establishes equivalence at +a ±2% margin. Both are correct. The difference is real and it is small enough not to matter. Only +TOST answers the question the transfer actually asks. + +The margin must be pre-stated, from the specification or the analytical target profile. A margin +chosen after seeing the data is not an acceptance criterion, and this is the single most common way +equivalence testing gets misused. + +## What none of this does + +These are computations. They do not establish that a procedure is fit for purpose. That conclusion +requires the intended purpose, the specification, product and process knowledge, the laboratory's +history with the technique, and the judgement of people who are accountable for it. A script that +reported "validated" would be lying about what it can know. -- 2.54.0 From d2382f2d529d59ff0219f892385c5ed949ffcb24 Mon Sep 17 00:00:00 2001 From: promptadmin Date: Sat, 8 Aug 2026 15:35:13 +0000 Subject: [PATCH 022/101] [upstream-sync] skills/benchling-integration/references/core_capabilities.md from K-Dense-AI/scientific-agent-skills@991bd993 [unknown] --- .../references/core_capabilities.md | 368 ++++++++++++++++++ 1 file changed, 368 insertions(+) create mode 100644 upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/benchling-integration/references/core_capabilities.md diff --git a/upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/benchling-integration/references/core_capabilities.md b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/benchling-integration/references/core_capabilities.md new file mode 100644 index 00000000..51717400 --- /dev/null +++ b/upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/benchling-integration/references/core_capabilities.md @@ -0,0 +1,368 @@ +--- +title: "Core Capabilities" +task: "" +lineage_type: import +upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/991bd993/skills/benchling-integration/references/core_capabilities.md +upstream_sha: 991bd993 +imported_at: 2026-08-08 +prompt_class: unknown +upstream_changes: accepted +author: upstream +validated: false +--- + +# Core Capabilities + +The seven capability areas in full, with code: authentication and setup, registry and +entity management, inventory management, notebook and documentation, workflows and +automation, events and integration, and the data warehouse and analytics. + +## Core Capabilities + +### 1. Authentication & Setup + +**Python SDK installation:** + +```bash +uv pip install "benchling-sdk==1.25.0" +``` + +Preview builds (alpha; not for production): + +```bash +uv pip install "benchling-sdk" --prerelease allow +``` + +**Environment variables (scoped reads only):** + +Read only the named keys you need — never dump or iterate over the full environment: + +```python +import os + +tenant_url = os.environ.get("BENCHLING_TENANT_URL") # e.g. https://your-tenant.benchling.com +api_key = os.environ.get("BENCHLING_API_KEY") + +if not tenant_url or not api_key: + raise ValueError("Set BENCHLING_TENANT_URL and BENCHLING_API_KEY") +``` + +Obtain an API key from **Profile Settings** in Benchling. For OAuth apps, use the [Developer Console](https://docs.benchling.com/docs/getting-started-benchling-apps) and store `BENCHLING_CLIENT_ID` / `BENCHLING_CLIENT_SECRET` separately. + +**Authentication methods:** + +API key (scripts and personal automation): + +```python +from benchling_sdk.benchling import Benchling +from benchling_sdk.auth.api_key_auth import ApiKeyAuth + +benchling = Benchling( + url=tenant_url, + auth_method=ApiKeyAuth(api_key), +) +``` + +OAuth client credentials (multi-user apps and production integrations): + +```python +from benchling_sdk.benchling import Benchling +from benchling_sdk.auth.client_credentials_oauth2 import ClientCredentialsOAuth2 + +benchling = Benchling( + url=tenant_url, + auth_method=ClientCredentialsOAuth2( + client_id=os.environ["BENCHLING_CLIENT_ID"], + client_secret=os.environ["BENCHLING_CLIENT_SECRET"], + ), +) +``` + +**Key points:** +- All API requests require HTTPS; network calls must target your tenant URL only +- Authentication permissions mirror UI permissions +- Verify credentials with `benchling.users.get_me()` before bulk operations + +For detailed authentication information including OIDC and security best practices, refer to `references/authentication.md`. + +### 2. Registry & Entity Management + +Registry entities include DNA sequences, RNA sequences, AA sequences, custom entities, and mixtures. The SDK provides typed classes for creating and managing these entities. + +**Creating DNA Sequences:** +```python +from benchling_sdk.models import DnaSequenceCreate + +sequence = benchling.dna_sequences.create( + DnaSequenceCreate( + name="My Plasmid", + bases="ATCGATCG", + is_circular=True, + folder_id="fld_abc123", + schema_id="ts_abc123", # optional + fields=benchling.models.fields({"gene_name": "GFP"}) + ) +) +``` + +**Registry Registration:** + +To register an entity directly upon creation: +```python +sequence = benchling.dna_sequences.create( + DnaSequenceCreate( + name="My Plasmid", + bases="ATCGATCG", + is_circular=True, + folder_id="fld_abc123", + entity_registry_id="src_abc123", # Registry to register in + naming_strategy="NEW_IDS" # or "IDS_FROM_NAMES" + ) +) +``` + +**Important:** Use either `entity_registry_id` OR `naming_strategy`, never both. + +**Updating Entities:** +```python +from benchling_sdk.models import DnaSequenceUpdate + +updated = benchling.dna_sequences.update( + sequence_id="seq_abc123", + dna_sequence=DnaSequenceUpdate( + name="Updated Plasmid Name", + fields=benchling.models.fields({"gene_name": "mCherry"}) + ) +) +``` + +Unspecified fields remain unchanged, allowing partial updates. + +**Listing and Pagination:** +```python +# List all DNA sequences (returns a generator) +sequences = benchling.dna_sequences.list() +for page in sequences: + for seq in page: + print(f"{seq.name} ({seq.id})") + +# Check total count +total = sequences.estimated_count() +``` + +**Key Operations:** +- Create: `benchling..create()` +- Read: `benchling..get_by_id(id)` or `.list()` +- Update: `benchling..update(id, update_object)` +- Archive: `benchling..archive(id)` + +Entity types: `dna_sequences`, `rna_sequences`, `aa_sequences`, `custom_entities`, `mixtures` + +For comprehensive SDK reference and advanced patterns, refer to `references/sdk_reference.md`. + +### 3. Inventory Management + +Manage physical samples, containers, boxes, and locations within the Benchling inventory system. + +**Creating Containers:** +```python +from benchling_sdk.models import ContainerCreate + +container = benchling.containers.create( + ContainerCreate( + name="Sample Tube 001", + schema_id="cont_schema_abc123", + parent_storage_id="box_abc123", # optional + fields=benchling.models.fields({"concentration": "100 ng/μL"}) + ) +) +``` + +**Managing Boxes:** +```python +from benchling_sdk.models import BoxCreate + +box = benchling.boxes.create( + BoxCreate( + name="Freezer Box A1", + schema_id="box_schema_abc123", + parent_storage_id="loc_abc123" + ) +) +``` + +**Transferring Items:** +```python +# Transfer a container to a new location +transfer = benchling.containers.transfer( + container_id="cont_abc123", + destination_id="box_xyz789" +) +``` + +**Key Inventory Operations:** +- Create containers, boxes, locations, plates +- Update inventory item properties +- Transfer items between locations +- Check in/out items +- Batch operations for bulk transfers + +### 4. Notebook & Documentation + +Interact with electronic lab notebook (ELN) entries, protocols, and templates. + +**Creating Notebook Entries:** +```python +from benchling_sdk.models import EntryCreate + +entry = benchling.entries.create( + EntryCreate( + name="Experiment 2025-10-20", + folder_id="fld_abc123", + schema_id="entry_schema_abc123", + fields=benchling.models.fields({"objective": "Test gene expression"}) + ) +) +``` + +**Linking Entities to Entries:** +```python +# Add references to entities in an entry +entry_link = benchling.entry_links.create( + entry_id="entry_abc123", + entity_id="seq_xyz789" +) +``` + +**Key Notebook Operations:** +- Create and update lab notebook entries +- Manage entry templates +- Link entities and results to entries +- Export entries for documentation + +### 5. Workflows & Automation + +Automate laboratory processes using Benchling's workflow system. + +**Creating Workflow Tasks:** +```python +from benchling_sdk.models import WorkflowTaskCreate + +task = benchling.workflow_tasks.create( + WorkflowTaskCreate( + name="PCR Amplification", + workflow_id="wf_abc123", + assignee_id="user_abc123", + fields=benchling.models.fields({"template": "seq_abc123"}) + ) +) +``` + +**Updating Task Status:** +```python +from benchling_sdk.models import WorkflowTaskUpdate + +updated_task = benchling.workflow_tasks.update( + task_id="task_abc123", + workflow_task=WorkflowTaskUpdate( + status_id="status_complete_abc123" + ) +) +``` + +**Asynchronous Operations:** + +Some operations are asynchronous and return tasks. The SDK default `max_wait_seconds` for polling is **600 seconds** (since SDK 1.11.0): + +```python +from benchling_sdk.helpers.tasks import wait_for_task + +result = wait_for_task( + benchling, + task_id="task_abc123", + interval_wait_seconds=2, + max_wait_seconds=300, # override for long-running serverless handlers +) +``` + +**Key Workflow Operations:** +- Create and manage workflow tasks +- Update task statuses and assignments +- Execute bulk operations asynchronously +- Monitor task progress + +### 6. Events & Integration + +Subscribe to Benchling changes via **AWS EventBridge** (customer-owned bus) or **Webhooks** (recommended for new Benchling Apps). EventBridge delivers hydrated v2 API objects; webhooks use thinner payloads. + +**Common EventBridge `detail-type` values:** +- `v2.dnaSequence.created`, `v2.dnaSequence.updated` +- `v2.entity.registered` +- `v2.entry.created`, `v2.entry.updated` +- `v2.workflowTask.updated.status` +- `v2.request.created` + +**Minimal EventBridge rule** (filter request creation by schema name): + +```json +{ + "detail-type": ["v2.request.created"], + "detail": { + "schema": { + "name": ["Validated Request"] + } + } +} +``` + +**Lambda handler skeleton:** + +```python +def handler(event, context): + detail_type = event["detail-type"] + detail = event["detail"] + + if detail.get("deprecated"): + # Alert — migrate before Benchling removes this event type + pass + + if detail.get("excludedProperties"): + # Payload exceeded 256 KB; re-fetch via detail["request"]["apiURL"] + pass + + if detail_type == "v2.request.created": + request_id = (detail.get("request") or {}).get("id") + # Re-fetch authoritative state — events can be late or out of order + # request = benchling.requests.get_by_id(request_id) + return {"request_id": request_id} + + return {"status": "ignored", "detail_type": detail_type} +``` + +**Setup flow:** +1. Tenant admin creates a subscription at `https://your-tenant.benchling.com/event-subscriptions` +2. Associate the AWS partner event source with a dedicated event bus immediately (within ~12 days) +3. Create rules + targets (Lambda, SQS, SNS) and grant invoke permissions +4. Validate with a CloudWatch Logs rule, then trigger a matching Benchling action + +**Recovery:** EventBridge deliveries are not replayed. Use the [List Events API](https://benchling.com/api/reference#/Events/listEvents) for events up to ~2 weeks old after outages. + +For payload schema, CloudFormation templates, SDK list/recovery examples, and validation steps, see `references/eventbridge.md`. + +### 7. Data Warehouse & Analytics + +Query historical Benchling data using SQL through the Data Warehouse. + +**Access Method:** +The Benchling Data Warehouse provides SQL access to Benchling data for analytics and reporting. Connect using standard SQL clients with provided credentials. + +**Common Queries:** +- Aggregate experimental results +- Analyze inventory trends +- Generate compliance reports +- Export data for external analysis + +**Integration with Analysis Tools:** +- Jupyter notebooks for interactive analysis +- BI tools (Tableau, Looker, PowerBI) +- Custom dashboards -- 2.54.0 From 82a1993d65f8d90e7043450acf7b161692bfec95 Mon Sep 17 00:00:00 2001 From: promptadmin Date: Sat, 8 Aug 2026 15:35:20 +0000 Subject: [PATCH 023/101] [upstream-sync] skills/bids/references/core_workflows.md from K-Dense-AI/scientific-agent-skills@991bd993 [prompt] --- .../skills/bids/references/core_workflows.md | 565 ++++++++++++++++++ 1 file changed, 565 insertions(+) create mode 100644 upstream/K-Dense-AI-scientific-agent-skills/skills/bids/references/core_workflows.md diff --git a/upstream/K-Dense-AI-scientific-agent-skills/skills/bids/references/core_workflows.md b/upstream/K-Dense-AI-scientific-agent-skills/skills/bids/references/core_workflows.md new file mode 100644 index 00000000..5891c647 --- /dev/null +++ b/upstream/K-Dense-AI-scientific-agent-skills/skills/bids/references/core_workflows.md @@ -0,0 +1,565 @@ +--- +title: "BIDS Core Workflows" +task: "" +lineage_type: import +upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/991bd993/skills/bids/references/core_workflows.md +upstream_sha: 991bd993 +imported_at: 2026-08-08 +prompt_class: prompt +upstream_changes: accepted +author: upstream +validated: false +--- + +# BIDS Core Workflows + +The twelve workflow areas in full, with worked code and commands: directory structure, +`dataset_description.json`, querying with PyBIDS, validation (PyPI wrapper, Deno, legacy +Node, and `.bidsignore`), entities and file naming, DICOM-to-BIDS conversion with +HeuDiConv and dcm2bids, metadata sidecars, events files, the participants file, +derivatives, advanced PyBIDS usage, and running BIDS-Apps. + +## Core Workflows + +### 1. BIDS Directory Structure + +A minimal BIDS dataset follows this layout: + +``` +my_dataset/ + dataset_description.json # Required: name, BIDSVersion, etc. + participants.tsv # Recommended: subject-level phenotypic data + participants.json # Recommended: column descriptions + README # Recommended: dataset documentation + CHANGES # Recommended: version history + .bidsignore # Optional: patterns to exclude from validation + sub-01/ + anat/ + sub-01_T1w.nii.gz + sub-01_T1w.json # Sidecar metadata + func/ + sub-01_task-rest_bold.nii.gz + sub-01_task-rest_bold.json + sub-01_task-rest_events.tsv # Event timing for task fMRI + sub-01_task-rest_events.json + dwi/ + sub-01_dwi.nii.gz + sub-01_dwi.json + sub-01_dwi.bvec + sub-01_dwi.bval + fmap/ + sub-01_phasediff.nii.gz + sub-01_phasediff.json + sub-01_magnitude1.nii.gz + perf/ + sub-01_asl.nii.gz + sub-01_asl.json + sub-01/ + ses-pre/ + anat/ + sub-01_ses-pre_T1w.nii.gz + func/ + sub-01_ses-pre_task-nback_bold.nii.gz + ses-post/ + ... +``` + +**Key points:** +- Every NIfTI file should have a corresponding `.json` sidecar +- File names encode entities: `sub-