opencode-skills-collection 3.0.44 → 3.0.46

package/bundled-skills/fsi-compliance-checker/mas-trm.md

@@ -0,0 +1,99 @@
+# MAS Technology Risk Management (TRM) Guidelines — Engineering Control Reference
+
+Engineering-relevant expectations from the Monetary Authority of Singapore's TRM Guidelines (January 2021), organized for change triage. Section numbers follow the official guidelines. The TRM Guidelines apply to all MAS-regulated financial institutions; they are principles-based guidelines (not prescriptive rules), so findings should be framed as "expectation gaps", and the institution's own TRM-aligned policies take precedence where stricter.
+
+Related instruments to flag when relevant (not summarized here): MAS Notices on Cyber Hygiene (legally binding baseline), Outsourcing Guidelines, and the MAS AI model risk management information paper for AI/ML systems.
+
+## Contents
+
+1. [Software development & DevOps (§6)](#1-software-development--devops-6)
+2. [IT resilience & availability (§8)](#2-it-resilience--availability-8)
+3. [Access control (§9)](#3-access-control-9)
+4. [Cryptography (§10)](#4-cryptography-10)
+5. [Data & infrastructure security (§11)](#5-data--infrastructure-security-11)
+6. [Cyber operations & monitoring (§12-13)](#6-cyber-operations--monitoring-12-13)
+7. [Online financial services (§14)](#7-online-financial-services-14)
+8. [Quick triage table](#8-quick-triage-table)
+
+## 1. Software Development & DevOps (§6)
+
+| Ref | Expectation (summary) | Engineering check |
+|-----|----------------------|-------------------|
+| 6.1 | Secure-by-design SDLC: security requirements defined at the start, not bolted on | Security stories/threat model exist for the feature |
+| 6.2 | Secure coding standards; code review (peer or automated) before deployment | Review gates; standards documented and enforced |
+| 6.3 | Source code security: access to repositories controlled; code integrity protected | Repo permissions, branch protection, signed commits where applicable |
+| 6.4 | Security testing: vulnerability assessment before production launch and after major changes; penetration testing for internet-facing systems | SAST/DAST in pipeline; pen-test cadence for public systems |
+| 6.5 | Separate environments for development, testing, production; production data not used in non-production without protection | Environment isolation; data masking for test data |
+| 6.6 | Change management: assessed, tested, approved before production; emergency change procedures with retrospective approval | CI/CD approval gates, change records, rollback plans |
+| 6.7 | End-of-life/unsupported software identified and risk-managed | Dependency and runtime version currency |
+| — | DevOps note: §6 expectations apply to pipeline automation itself — the pipeline is a production system (access control, audit, segregation of duties in deployment approval) | Who can approve+deploy; pipeline credentials |
+
+## 2. IT Resilience & Availability (§8)
+
+| Ref | Expectation (summary) | Engineering check |
+|-----|----------------------|-------------------|
+| 8.2 | Availability targets defined; critical systems' RTO ≤ 4 hours and RPO defined per MAS Notice expectations | Architecture supports the institution's stated RTO/RPO |
+| 8.3 | Single points of failure identified and addressed for critical systems | Redundancy in new components; multi-AZ/multi-site where critical |
+| 8.4 | DR plans tested at least annually; recovery procedures current | New components included in DR runbooks |
+| 8.5 | Capacity management: monitor and plan for demand | Load assumptions documented for new services |
+
+## 3. Access Control (§9)
+
+| Ref | Expectation (summary) | Engineering check |
+|-----|----------------------|-------------------|
+| 9.1 | Least privilege and need-to-have for all access; access reviewed periodically | New roles/permissions minimal; review process covers them |
+| 9.2 | Strong authentication for privileged access; MFA expected for critical system administration | Admin paths MFA-protected |
+| 9.3 | Privileged access managed: just-in-time where possible, activities logged and reviewed | Break-glass procedures, session recording/audit for admin ops |
+| 9.4 | Segregation of duties: no single person develops, approves, and deploys to production unchecked | Pipeline approval separation |
+| 9.5 | Remote access secured (MFA, encrypted channels, device posture) | VPN/zero-trust requirements for any new remote path |
+
+## 4. Cryptography (§10)
+
+| Ref | Expectation (summary) | Engineering check |
+|-----|----------------------|-------------------|
+| 10.1 | Strong, industry-accepted algorithms and key lengths; no deprecated crypto | No MD5/SHA-1 for security, no TLS <1.2, AES-128+ |
+| 10.2 | Key lifecycle management: generation, distribution, storage, rotation, revocation, destruction | KMS/HSM usage; no keys in code, config files, or tickets |
+| 10.3 | Cryptographic key compromise procedures | Key rotation runbook covers new keys |
+
+## 5. Data & Infrastructure Security (§11)
+
+| Ref | Expectation (summary) | Engineering check |
+|-----|----------------------|-------------------|
+| 11.1 | Data security throughout lifecycle: at rest, in transit, in use; data loss prevention strategy | Encryption defaults on new stores; egress paths controlled |
+| 11.2 | Network security: segmentation, defense in depth; critical systems in secured zones | New services placed in correct zones; no flattening of segmentation |
+| 11.3 | Endpoint and server hardening per standards | Base images hardened; IaC matches hardening baselines |
+| 11.4 | Virtualization/container security: hypervisor and orchestration hardening | K8s RBAC, pod security, image provenance |
+| 11.5 | Cloud: institution remains responsible; due diligence, data residency, exit strategy, and MAS Outsourcing Guidelines apply | New cloud services assessed; data residency for Singapore customer data confirmed |
+
+## 6. Cyber Operations & Monitoring (§12-13)
+
+| Ref | Expectation (summary) | Engineering check |
+|-----|----------------------|-------------------|
+| 12.1 | Security event logging across systems; logs protected and retained per policy | New components emit security events to central SIEM |
+| 12.2 | Continuous monitoring and correlation; anomaly detection for critical systems | Alert rules accompany new security-relevant functionality |
+| 13.1 | Cyber incident response plan; roles defined; MAS notification obligations for relevant incidents (as required by notices — commonly understood as within 1 hour for severe incidents) | New failure modes mapped to incident severity matrix |
+| 13.2 | Post-incident review and remediation tracking | Incident learnings feed backlog |
+
+## 7. Online Financial Services (§14)
+
+| Ref | Expectation (summary) | Engineering check |
+|-----|----------------------|-------------------|
+| 14.1 | Strong customer authentication: MFA for login to online financial services and for high-risk transactions | Customer auth flows; step-up auth for transfers/payee changes |
+| 14.2 | Transaction signing/confirmation for high-risk transactions; out-of-band notification to customers | Transaction flows notify customers of significant actions |
+| 14.3 | Session management: timeout, re-authentication for sensitive actions, protection against hijacking | Session config on customer-facing changes |
+| 14.4 | Fraud monitoring and customer education surfaces | New transaction types covered by fraud rules |
+| — | Anti-scam expectations (post-2022 MAS/ABS measures): kill switch, cooling-off for new payees/devices, transaction limits | Payment feature changes checked against these measures |
+
+## 8. Quick Triage Table
+
+| Change type | Check first |
+|-------------|-------------|
+| New feature touching customer money | §14.1-14.2, §6.1, threat model |
+| Auth/session change | §9.x, §14.1, §14.3 |
+| New data store / data flow | §11.1, §11.5 (residency), §10.1 |
+| New cloud service | §11.5 + Outsourcing Guidelines flag |
+| CI/CD or repo change | §6.3, §6.6, §9.4 |
+| Infra/network change | §11.2, §8.3 |
+| New logging/monitoring | §12.1-12.2 |
+| Incident-relevant failure mode | §13.1 severity mapping |
+| AI/ML model in decisioning | Flag MAS AI information paper review |

package/bundled-skills/fsi-compliance-checker/pci-dss.md

@@ -0,0 +1,89 @@
+# PCI-DSS v4.0 — Engineering Control Reference
+
+Engineering-relevant controls from PCI-DSS v4.0, organized by what a code/architecture change typically touches. Control numbers follow the official standard (PCI Security Standards Council). This is a working summary for triage, not the standard itself — for formal scoping consult the full standard and a QSA.
+
+**Key v4.0 dates:** v4.0 became mandatory March 2024; the ~50 future-dated requirements (marked FD below) became mandatory **31 March 2025** — they are now in force.
+
+## Contents
+
+1. [Cardholder data handling (Req 3, 4)](#1-cardholder-data-handling)
+2. [Authentication & access (Req 7, 8)](#2-authentication--access)
+3. [Secure development (Req 6)](#3-secure-development)
+4. [Logging & monitoring (Req 10)](#4-logging--monitoring)
+5. [Network & segmentation (Req 1)](#5-network--segmentation)
+6. [Payment page / client-side (Req 6.4.3, 11.6.1)](#6-payment-page--client-side)
+7. [Quick triage table](#7-quick-triage-table)
+
+## 1. Cardholder Data Handling
+
+| Control | Requirement (summary) | Engineering check |
+|---------|----------------------|-------------------|
+| 3.2.1 | Account data storage kept to minimum: retention/disposal policies covering all storage locations | New stores/caches must update the data-flow inventory; retention defined |
+| 3.3.1 | Don't store sensitive authentication data (CVV/CVC, full track, PIN) after authorization — ever, even encrypted | grep for CVV/CVC fields in models, logs, caches, analytics events |
+| 3.4.1 | Mask PAN when displayed (BIN + last 4 max visible) | UI components, receipts, admin screens, support tooling |
+| 3.5.1 | Render PAN unreadable anywhere stored (strong crypto, truncation, tokens) | DB columns, backups, object storage, message queues, data lakes |
+| 3.6 / 3.7 | Key management: documented procedures, key rotation, split knowledge for manual operations | KMS usage, key rotation schedules, no keys in code/config |
+| 4.2.1 | Strong cryptography for PAN over open/public networks; no fallback to insecure versions | TLS 1.2+ enforced, cert validation not disabled, no PAN over email/chat |
+
+## 2. Authentication & Access
+
+| Control | Requirement (summary) | Engineering check |
+|---------|----------------------|-------------------|
+| 7.2.1 | Access by least privilege, need-to-know, defined roles | New endpoints/services declare required roles; no wildcard IAM |
+| 8.3.6 (FD) | Passwords minimum 12 characters with complexity | Password validators, policy configs |
+| 8.3.9 | Password change every 90 days OR dynamic risk analysis OR MFA-always | Session/auth design |
+| 8.4.2 (FD) | MFA for ALL access into the CDE (not just admins) | Auth flows for any CDE-touching application access |
+| 8.6.1-8.6.3 (FD) | Interactive use of system/service accounts restricted; their passwords managed and rotated | Service account credentials in pipelines, cron jobs |
+| 8.2.2 | No shared/group accounts except documented exceptional circumstances | Service design, break-glass procedures |
+
+## 3. Secure Development
+
+| Control | Requirement (summary) | Engineering check |
+|---------|----------------------|-------------------|
+| 6.2.1 | Software developed per secure SDLC, security throughout | Threat modeling, security stories, review gates exist |
+| 6.2.4 | Engineering techniques preventing common attack classes (injection, XSS, etc.) | Parameterized queries, output encoding, input validation at boundaries |
+| 6.3.1 | Security vulnerabilities identified and ranked (CVSS or equivalent) | Scanner integration, triage workflow |
+| 6.3.2 (FD) | Inventory of bespoke and custom software, and third-party components (SBOM-like) | Dependency manifests current; new deps recorded |
+| 6.3.3 | Critical/high patches within one month | Dependency update cadence |
+| 6.4.1/6.4.2 | Public-facing web apps protected (WAF in blocking mode per 6.4.2 FD) | New public endpoints behind WAF |
+| 6.5.1-6.5.6 | Change management: documented, tested, approved; separation of dev/test from prod; no prod data in test; no test accounts/data left in prod before release | CI/CD gates, seed data hygiene, environment separation |
+
+## 4. Logging & Monitoring
+
+| Control | Requirement (summary) | Engineering check |
+|---------|----------------------|-------------------|
+| 10.2.1 | Audit logs capture: individual user access to cardholder data, admin actions, auth attempts (success/failure), log access, security event types | Audit events emitted for these actions with user identity |
+| 10.2.1.2 | All actions by accounts with admin access logged | Admin tooling, support backdoors |
+| 10.3.1-10.3.4 | Logs protected from modification, access limited, integrity monitored | Append-only/immutable log storage, restricted access |
+| 10.4.1 (FD: automated) | Daily review of security events — automated mechanisms required in v4.0 | Alerting rules exist for new security-relevant events |
+| — | **Never log:** full PAN, CVV, passwords, full track data | grep logging statements in payment/auth paths |
+
+## 5. Network & Segmentation
+
+| Control | Requirement (summary) | Engineering check |
+|---------|----------------------|-------------------|
+| 1.2.5 / 1.2.6 | All services/ports/protocols identified, approved, with security features defined | New listeners/ports documented and justified |
+| 1.3.1 / 1.3.2 | Inbound and outbound CDE traffic restricted to necessary only | Security group / firewall changes reviewed against data flows |
+| 1.4.4 | Stored cardholder data not directly accessible from untrusted networks | No DB with card data reachable from public subnets |
+
+## 6. Payment Page / Client-Side
+
+The two controls that catch most modern e-commerce teams (both FD, mandatory since 31 Mar 2025):
+
+| Control | Requirement (summary) | Engineering check |
+|---------|----------------------|-------------------|
+| 6.4.3 | All payment-page scripts: inventoried, authorized, integrity-assured (e.g. SRI/CSP) | Script inventory for checkout pages; CSP headers; no unvetted tags |
+| 11.6.1 | Change/tamper detection on payment pages, alerting on unauthorized modification | Monitoring on checkout page headers and script changes |
+
+## 7. Quick Triage Table
+
+| Change type | Check first |
+|-------------|-------------|
+| New logging | 3.3.1, never-log list (§4) |
+| New data store/cache | 3.5.1, 3.2.1, 1.4.4 |
+| Auth/session change | 8.3.x, 8.4.2, 10.2.1 |
+| New dependency | 6.3.2, 6.3.3 |
+| New public endpoint | 6.4.1/6.4.2, 1.2.x |
+| Checkout/payment UI | 6.4.3, 11.6.1, 3.4.1 |
+| CI/CD change | 6.5.1-6.5.6, 8.6.x |
+| Infra/network change | 1.2.x, 1.3.x |

package/bundled-skills/not-a-vibe-coder/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: not-a-vibe-coder
+description: Turns vague prompts into 8 structured planning files for brand new projects. DO NOT use on existing codebases.
+risk: critical
+---
+
+# Not-a-Vibe-Coder
+
+A skill that turns any project idea — no matter how vague — into 8 living planning
+documents that act as the project's persistent memory across a long context window.
+The documents are the source of truth for "what we agreed on"; the user's live
+instructions are always the final authority and can override the docs at any time.
+
+## Core Principles (never violate these)
+
+1. **User command > files > AI assumptions.** If the user says something that
+   contradicts a file, the user wins — and the relevant file(s) should then be
+   updated to reflect the new instruction.
+2. **No silent additions.** Never add features, tech choices, pages, tables, or
+   rules the user did not ask for or approve. If something seems missing, ask —
+   don't assume. Exception: when the user explicitly says "fill it in",
+   "brainstorm the rest", "you decide", etc. — see Phase 3.
+3. **Design.md is special.** NEVER fill Design.md with your own taste. Always ask
+   the user for style direction (e.g. minimal, playful, corporate, dark mode,
+   neumorphic, etc.) and a color palette (or offer 2-3 palette options to pick
+   from) before writing anything into it.
+4. **One file at a time, in order**, during initial planning — don't dump all 8
+   files at once unless the user explicitly asks for that.
+5. **Tracker.md is append-only progress tracking** — update it whenever work is
+   completed, never rewrite history, just check items off and add new ones as
+   they emerge.
+6. **Mid-project changes ripple.** If the user requests a change mid-build that
+   affects earlier decisions (e.g. "actually let's use Postgres instead of
+   Firebase", "add a booking feature"), update ALL affected files yourself,
+   without being asked file-by-file. Then summarize what changed.
+7. **Read before you write.** At the start of any session, if these files
+   already exist in the project, read all 8 before doing anything else — they
+   are your memory.
+
+## The 8 Files
+
+| File | Purpose |
+|---|---|
+| PRD.md | What the app does, features, goals, user requirements |
+| TechSpec.md | Architecture, tech stack, APIs, database choices |
+| AppFlow.md | User flows and navigation |
+| Design.md | UI/UX guidelines, layout, style, color palette |
+| Schema.md | Database tables, relationships, data models |
+| ImplementationPlan.md | Step-by-step development roadmap |
+| Tracker.md | Completed work, pending tasks, progress |
+| Rules.md | Coding standards, constraints, project rules |
+
+## Workflow
+
+### Phase 0 — Detect intent
+
+- ONLY for brand new projects. If project has existing code files, ABORT and do not use this skill.
+- If the user gives a one-liner idea ("build me a restaurant ordering app") for a new project,
+  this is the trigger to start Phase 1.
+- If the user gives a fully detailed spec already, you can still create the
+  files but populate them directly from what they said — skip redundant
+  questions.
+
+### Phase 1 — PRD.md first
+
+This is the foundation. Everything else depends on it.
+
+- Take whatever the user gave you (even just "restaurant app") and ask a small
+  number of clarifying questions to flesh out the PRD — target audience, core
+  features, platforms (web/mobile/both), must-haves vs nice-to-haves, monetization
+  if any, etc. Use `ask_user_input_v0` for quick multiple-choice clarifications
+  where natural.
+- The user can also choose to skip Q&A and just write directly into PRD.md
+  themselves — if they say "I'll fill it in", create a skeleton PRD.md with
+  section headers and placeholders, and wait for them.
+- Do not invent features. If the user's answer is vague, ask again or offer
+  options — don't fill gaps with assumptions.
+- Once the PRD feels solid, write PRD.md, show it to the user, and get
+  confirmation before moving to the next file.
+
+### Phase 2 — Remaining files, one by one (except Design.md)
+
+In this order: TechSpec.md → AppFlow.md → Schema.md → ImplementationPlan.md →
+Rules.md → Tracker.md → Design.md (last, see Phase 2.5).
+
+For each file:
+- Propose a draft based on the PRD and any prior files, OR ask the user
+  questions if there's a real decision to make (e.g. "Should this use
+  PostgreSQL or a simpler option like SQLite/Firebase?").
+- Show the draft, ask for confirmation or edits.
+- Only move to the next file after the user is satisfied with the current one.
+
+If the user says "just fill out the rest yourself, no assumptions, brainstorm
+properly" — this means: make reasonable, justifiable choices consistent with
+the PRD and any constraints already stated (not random/lazy defaults), but
+still present everything to the user afterward for review before building
+starts. "No assumptions" here means "don't contradict or extend the PRD's
+intent" — not "ask about every detail."
+
+### Phase 2.5 — Design.md (always interactive)
+
+Never write Design.md without asking the user:
+- Overall style direction (e.g. minimal / modern / playful / corporate / retro /
+  brutalist / glassmorphism / dark-first) — offer `ask_user_input_v0` choices
+  if helpful.
+- Color palette — either ask for specific colors/hex codes, or offer 2-3
+  palette options matching their chosen style and let them pick.
+- Typography preferences, spacing density, any reference sites/apps they like.
+
+Only after this input is gathered do you write Design.md.
+
+### Phase 3 — Final review
+
+- Once all 8 files are drafted, present a short summary of the whole plan and
+  ask the user to review everything (especially Rules.md — ask if they want to
+  add any constraints, e.g. "no external libraries", "TypeScript only",
+  "must work offline", etc.).
+- Explicitly ask: "Anything to change before I start building?"
+
+### Phase 4 — Build
+
+- Once the user confirms, begin implementation following ImplementationPlan.md
+  step by step.
+- As each step/task is completed, mark it done in Tracker.md (check it off,
+  add a short note/date if useful).
+- Never deviate from ImplementationPlan.md, Rules.md, TechSpec.md, or Schema.md
+  without explicit user instruction.
+- If the user gives a new instruction mid-build that isn't in the files:
+  follow it immediately (user command is final), AND update the relevant
+  file(s) afterward so the docs stay in sync. Briefly tell the user which
+  files you updated and why.
+
+## Quick Reference: Decision Rules
+
+- Ambiguous feature request → ask, don't assume.
+- User explicitly says "you decide" / "brainstorm it" → make a reasoned,
+  PRD-consistent choice, document it, present for review — don't silently bake
+  it in.
+- Conflict between user's current message and a file → user wins; then sync
+  the file.
+- Design.md → always ask style + colors first, no exceptions.
+- Any completed task → update Tracker.md immediately.
+- Mid-project pivot → update all affected files proactively, summarize changes.
+
+## Limitations
+- Only works for new projects. Will fail if run on existing codebases.
+- Relies heavily on accurate user input during the initial PRD generation.

package/bundled-skills/papers-skill/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: papers-skill
+description: "Skill for academic research workflows: search Semantic Scholar (200M+ papers), inspect citations, download arXiv PDFs, and extract PDF text. Bundles a self-contained Python CLI."
+category: research
+risk: safe
+source: community
+source_repo: xwmxcz/papers-skill
+source_type: community
+date_added: "2026-06-11"
+author: xwmxcz
+tags: [research, academic, papers, citations, arxiv, semantic-scholar, pdf]
+tools: [claude-code, antigravity, cursor, gemini-cli, codex-cli, opencode]
+license: "MIT"
+license_source: "https://github.com/xwmxcz/papers-skill/blob/main/LICENSE"
+---
+
+# Papers Skill
+
+## Overview
+
+Papers Skill turns a coding agent into a literature-research assistant. It
+orchestrates a bundled Python CLI (`scripts/papers.py`) that hits the free
+Semantic Scholar and arXiv APIs, downloads arXiv PDFs, and extracts text with
+PyMuPDF. The agent decides which subcommand to invoke and how to combine
+results into a literature scan, a deep read of one paper, an impact analysis,
+or a reading list.
+
+This skill is the Skill-mode port of the
+[papers-mcp](https://github.com/xwmxcz/papers-mcp) MCP server by the same
+author. Both projects share the same feature set; this one ships as a
+Claude Code plugin so it can be installed with a single command and needs no
+long-running MCP process.
+
+## When to Use This Skill
+
+- Use when the user asks to search academic papers by topic, author, or venue.
+- Use when the user names a specific paper (by DOI, arXiv ID, or title) and
+  wants metadata, the abstract, the TL;DR, or its reference list.
+- Use when the user wants to find work that **cites** a known paper (impact
+  analysis, follow-up tracking).
+- Use when the user wants to download an arXiv PDF and have it summarized.
+- Use when the user asks to build a reading list around a topic.
+
+## Do Not Use This Skill When
+
+- The user wants paywalled non-arXiv full text. This skill cannot bypass
+  publisher paywalls; it can only fetch arXiv PDFs and metadata everywhere.
+- The user wants OCR over scanned PDFs. PyMuPDF extracts embedded text only;
+  scanned image-PDFs return the fallback message and need a separate OCR step.
+- The user wants real-time citation alerts or RSS-style watching. This skill
+  is request-driven.
+
+## How It Works
+
+### Step 1: Verify dependencies
+
+Three Python packages are required. The skill should check once per session,
+using the **same interpreter** to import-check and install so the dependency
+check and install target stay in sync:
+
+```bash
+python -c "import httpx, arxiv, fitz" 2>&1 || python -m pip install httpx arxiv PyMuPDF
+```
+
+If `python` is not on PATH, fall back to `py` (Windows launcher) or the
+absolute interpreter path — and remember to invoke pip via the same
+interpreter, e.g. `py -m pip install httpx arxiv PyMuPDF`.
+
+### Step 2: Invoke the bundled CLI
+
+The script lives at `${CLAUDE_PLUGIN_ROOT}/skills/papers-skill/scripts/papers.py`
+and is bundled with this skill (no separate install needed). Always quote the
+path so it survives spaces.
+
+```bash
+python "${CLAUDE_PLUGIN_ROOT}/skills/papers-skill/scripts/papers.py" <subcommand> [args]
+```
+
+### Step 3: Pick the right subcommand
+
+| Subcommand | Purpose | Example |
+|---|---|---|
+| `search <query> [--limit N]` | Semantic Scholar search, max 20 | `search "diffusion models" --limit 5` |
+| `detail <paper_id>` | Full metadata, TL;DR, top references | `detail 10.48550/arXiv.2310.06825` |
+| `citations <paper_id> [--limit N]` | Papers citing this one, max 20 | `citations <id> --limit 15` |
+| `arxiv <query> [--max-results N]` | arXiv preprint search, max 10 | `arxiv "RLHF" --max-results 5` |
+| `download <arxiv_id> [--save-dir D]` | Save PDF locally | `download 2310.06825 --save-dir ./pdfs` |
+| `read <pdf_path> [--max-pages N]` | Extract PDF text via PyMuPDF | `read ./pdfs/foo.pdf --max-pages 20` |
+
+`detail` and `citations` auto-detect the ID type: DOIs starting with `10.`
+are used as-is, bare numeric IDs of 10+ digits are treated as arXiv IDs, and
+long hex strings are treated as Semantic Scholar `paperId`s.
+
+## Examples
+
+### Example 1: Literature scan on a topic
+
+```bash
+python "${CLAUDE_PLUGIN_ROOT}/skills/papers-skill/scripts/papers.py" search "retrieval augmented generation" --limit 10
+```
+
+Present results as a ranked table with **# | Title | Year | Citations | ID**,
+then ask the user which papers to dig into.
+
+### Example 2: Deep-read one paper
+
+```bash
+# 1. Confirm match
+python "${CLAUDE_PLUGIN_ROOT}/skills/papers-skill/scripts/papers.py" detail 2005.11401
+# 2. Download
+python "${CLAUDE_PLUGIN_ROOT}/skills/papers-skill/scripts/papers.py" download 2005.11401 --save-dir ./pdfs
+# 3. Extract abstract + intro + conclusion
+python "${CLAUDE_PLUGIN_ROOT}/skills/papers-skill/scripts/papers.py" read ./pdfs/2005.11401v4.RAG.pdf --max-pages 10
+```
+
+Summarize as: **problem · method · key result · limitations**.
+
+### Example 3: Impact analysis on an anchor paper
+
+```bash
+python "${CLAUDE_PLUGIN_ROOT}/skills/papers-skill/scripts/papers.py" detail 10.48550/arXiv.2005.11401
+python "${CLAUDE_PLUGIN_ROOT}/skills/papers-skill/scripts/papers.py" citations 10.48550/arXiv.2005.11401 --limit 20
+```
+
+Cluster the citing papers by year/theme and highlight the most-cited
+follow-ups.
+
+## Best Practices
+
+- ✅ Always call `detail` before `download` to confirm the paper matches user
+  intent. Skipping this leads to wrong PDFs being fetched.
+- ✅ Include the paper ID alongside every title in your output so the user
+  can re-query precisely.
+- ✅ Cite as `[FirstAuthor et al., Year] *Title* (cites: N)`.
+- ✅ For PDFs you download, always report the absolute save path.
+- ❌ Don't crawl. The script auto-retries 429s with exponential backoff;
+  don't pile on parallel queries.
+- ❌ Don't raise `--max-pages` to 100+ without warning the user — it can
+  consume a large amount of context.
+
+## Limitations
+
+- The skill cannot fetch full text from paywalled publishers (Elsevier,
+  Springer, Wiley, etc.). It can only read open arXiv PDFs.
+- PyMuPDF extracts embedded text only. Scanned image-PDFs return the
+  fallback message `PDF无法提取文本（可能是扫描件）`; offer the user an
+  alternative version or note that OCR is required.
+- Semantic Scholar's anonymous tier rate-limits aggressively. The script
+  retries 3× with exponential backoff; persistent 429s during heavy use
+  surface as `搜索失败: rate limit, retries exhausted`.
+- This skill does not replace environment-specific validation, testing, or
+  expert review. Stop and ask for clarification if required inputs are
+  missing.
+
+## Security & Safety Notes
+
+- The CLI performs **outbound HTTPS only** to `api.semanticscholar.org` and
+  `arxiv.org` (and the arXiv-listed mirror for the bundled `arxiv` package).
+  No authentication tokens are sent.
+- `download` writes a PDF to the directory the user specifies (default: the
+  current working directory). Confirm the save path with the user before
+  downloading to an unexpected location.
+- `read` opens a local PDF file with PyMuPDF — make sure the path the user
+  supplies is one they trust.
+- No credentials or API keys are needed or stored anywhere.
+
+## Common Pitfalls
+
+- **Problem:** `需要安装 arxiv: pip install arxiv` or `需要安装 PyMuPDF: pip install PyMuPDF`.
+  **Solution:** The script returns this friendly message instead of crashing
+  when an optional dependency is missing. Offer to run the install command.
+
+- **Problem:** `搜索失败: rate limit, retries exhausted` from `search` or
+  `detail` or `citations`.
+  **Solution:** Semantic Scholar is rate-limiting. Wait ~10 seconds and
+  retry once. For repeated runs, fall back to `arxiv` for arXiv-indexed work.
+
+- **Problem:** `download` fails with `找不到 arXiv ID: …`.
+  **Solution:** The user gave a non-arXiv ID (likely a DOI for a non-arXiv
+  paper). Use `detail` to inspect; only papers with an `externalIds.ArXiv`
+  field can be downloaded.
+
+- **Problem:** Garbled Chinese output on Windows.
+  **Solution:** The script already forces UTF-8 stdout. If the host
+  terminal is still misconfigured, set `PYTHONIOENCODING=utf-8` in the
+  shell environment.
+
+## Additional Resources
+
+- Skill home (this plugin): https://github.com/xwmxcz/papers-skill
+- Upstream MCP server: https://github.com/xwmxcz/papers-mcp
+- Semantic Scholar API docs: https://api.semanticscholar.org/
+- arXiv API docs: https://info.arxiv.org/help/api/
+- PyMuPDF docs: https://pymupdf.readthedocs.io/