@fectivnfy112358/minimax-code-web 0.1.0-preview.0 → 0.1.0-preview.3

package/server/assets/skills/skill-creator/scripts/lint-skill.js

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+// lint-skill.js — Mavis SKILL.md validator
+//
+// Usage: node lint-skill.js <path/to/skill-directory>
+// Exit codes: 0 = pass, 1 = errors found.
+//
+// See Step 5 in the adjacent SKILL.md for validation checks.
+// No third-party dependencies; uses only Node.js built-in fs + path.
+
+import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { join, basename, resolve } from 'node:path';
+
+const FORBIDDEN_FILES = ['README.md', 'CHANGELOG.md', 'INSTALLATION.md', 'INSTALLATION_GUIDE.md', 'QUICK_REFERENCE.md'];
+const FORBIDDEN_FRONTMATTER_KEYS = ['allowed-tools', 'license', 'model'];
+const MAX_BODY_LINES = 500;
+const REDUNDANT_WHEN_TO_USE_HEADINGS = [
+  '## When to use',
+  '## When to use this skill',
+  '## When this skill should be used',
+];
+const README_SMELLS = [
+  '## How it works',
+  '## Usage',
+  '### Command line',
+  '### As a Python module',
+  '### As a Node module',
+  '## API',
+];
+
+function fail(msg) {
+  console.error(`[FAIL] ${msg}`);
+  return false;
+}
+
+function warn(msg) {
+  console.error(`[WARN] ${msg}`);
+}
+
+function ok(msg) {
+  console.log(`[OK]   ${msg}`);
+}
+
+// Minimal frontmatter parser: only top-level key: value entries enclosed by `---`.
+// No nesting or complex YAML beyond multiline strings; sufficient for SKILL.md.
+function parseFrontmatter(content) {
+  const lines = content.split('\n');
+  if (lines[0]?.trim() !== '---') return { frontmatter: null, bodyStart: 0 };
+  let endIdx = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === '---') {
+      endIdx = i;
+      break;
+    }
+  }
+  if (endIdx === -1) return { frontmatter: null, bodyStart: 0 };
+
+  const fm = {};
+  let currentKey = null;
+  let currentValue = [];
+  let inBlockScalar = false;
+  for (let i = 1; i < endIdx; i++) {
+    const line = lines[i];
+    if (inBlockScalar) {
+      if (/^[a-zA-Z_-]+\s*:/.test(line)) {
+        // Flush the previous key when a new one starts.
+        fm[currentKey] = currentValue.join('\n').trim();
+        inBlockScalar = false;
+        currentKey = null;
+        currentValue = [];
+        // Do not continue; proceed to parse the new line.
+      } else {
+        currentValue.push(line.replace(/^\s{0,4}/, ''));
+        continue;
+      }
+    }
+    const m = line.match(/^([a-zA-Z_-]+)\s*:\s*(.*)$/);
+    if (m) {
+      const [, k, v] = m;
+      if (v === '|' || v === '>' || v === '|-' || v === '>-') {
+        // Block scalar
+        currentKey = k;
+        currentValue = [];
+        inBlockScalar = true;
+      } else {
+        fm[k] = v.trim();
+      }
+    }
+  }
+  if (inBlockScalar && currentKey) {
+    fm[currentKey] = currentValue.join('\n').trim();
+  }
+  return { frontmatter: fm, bodyStart: endIdx + 1 };
+}
+
+function lintSkill(skillDir) {
+  const dirAbs = resolve(skillDir);
+  const dirName = basename(dirAbs);
+  const skillMdPath = join(dirAbs, 'SKILL.md');
+
+  console.log(`Linting skill at: ${dirAbs}`);
+  console.log('');
+
+  let allOk = true;
+
+  // 0. SKILL.md must exist.
+  if (!existsSync(skillMdPath)) {
+    fail(`SKILL.md not found at ${skillMdPath}`);
+    process.exit(1);
+  }
+  ok('SKILL.md exists');
+
+  const content = readFileSync(skillMdPath, 'utf-8');
+  const { frontmatter, bodyStart } = parseFrontmatter(content);
+
+  // 1. Frontmatter must exist.
+  if (!frontmatter) {
+    fail('frontmatter (--- ... ---) missing or unclosed');
+    process.exit(1);
+  }
+  ok('frontmatter parsed');
+
+  // 2. name is required, must use kebab-case, and must match the directory name.
+  const name = frontmatter.name;
+  if (!name) {
+    allOk = fail('frontmatter.name is missing') && allOk;
+  } else if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+    allOk = fail(`frontmatter.name "${name}" is not kebab-case (lowercase letters/digits/hyphens, start with letter)`) && allOk;
+  } else if (name !== dirName) {
+    allOk = fail(`frontmatter.name "${name}" does not match directory name "${dirName}"`) && allOk;
+  } else {
+    ok(`name "${name}" is valid kebab-case and matches directory`);
+  }
+
+  // 3. description is required and must include a trigger phrase.
+  const desc = frontmatter.description;
+  if (!desc) {
+    allOk = fail('frontmatter.description is missing') && allOk;
+  } else {
+    const hasTriggerHint = /\b(when|trigger|use this|load this)\b/i.test(desc) || /["'']/.test(desc);
+    if (!hasTriggerHint) {
+      allOk = fail('frontmatter.description must contain at least one trigger phrase: a quoted phrase, "when", "trigger", "use this", or "load this"') && allOk;
+    } else {
+      ok('description contains trigger hint');
+    }
+    if (desc.length < 30) {
+      warn(`description is very short (${desc.length} chars); make sure it covers what + when + near misses`);
+    }
+  }
+
+  // 4. Forbidden frontmatter fields.
+  for (const key of FORBIDDEN_FRONTMATTER_KEYS) {
+    if (key in frontmatter) {
+      allOk = fail(`frontmatter contains forbidden key "${key}" (Mavis does not recognize this; remove it)`) && allOk;
+    }
+  }
+  if (FORBIDDEN_FRONTMATTER_KEYS.every((k) => !(k in frontmatter))) {
+    ok('no forbidden frontmatter keys');
+  }
+
+  // 5. Body line-count check.
+  const bodyLines = content.split('\n').length - bodyStart;
+  if (bodyLines > MAX_BODY_LINES) {
+    allOk = fail(`SKILL.md body is ${bodyLines} lines (> ${MAX_BODY_LINES}); split into references/<topic>.md`) && allOk;
+  } else {
+    ok(`body is ${bodyLines} lines (limit ${MAX_BODY_LINES})`);
+  }
+
+  // 5.1 README-style anti-pattern check.
+  const body = content.split('\n').slice(bodyStart).join('\n');
+  const hasRedundantWhenToUse = REDUNDANT_WHEN_TO_USE_HEADINGS.some((heading) => body.includes(heading));
+  if (hasRedundantWhenToUse) {
+    warn('body contains a "When to use" heading; prefer putting trigger/boundary rules in frontmatter.description to avoid duplication');
+  }
+  const readmeMatches = README_SMELLS.filter((heading) => body.includes(heading));
+  if (readmeMatches.length > 0) {
+    warn(`body contains README-style section(s): ${readmeMatches.join(', ')}; keep SKILL.md focused on execution rules unless these sections are truly necessary`);
+  }
+
+  // 5.2 Windows compatibility: WARN if the body indicates shell commands but the text never mentions windows/win32.
+  const shellIndicators = [/python3\b/, /bash\s+scripts\//, /brew\s+install/, /\/tmp\//, /```(?:bash|sh)\b/];
+  const hasShellIndicator = shellIndicators.some((re) => re.test(body));
+  const mentionsWindows = /windows|win32/i.test(content);
+  if (hasShellIndicator && !mentionsWindows) {
+    warn('body contains shell/bash commands but does not mention Windows/win32; consider adding a "## Windows (win32) platform notes" section for cross-platform support');
+  }
+
+  // 6. Forbidden-file check.
+  const entries = readdirSync(dirAbs);
+  for (const entry of entries) {
+    if (FORBIDDEN_FILES.includes(entry)) {
+      allOk = fail(`forbidden file "${entry}" in skill directory (skill is for LLM, not human docs); remove it`) && allOk;
+    }
+  }
+  if (FORBIDDEN_FILES.every((f) => !entries.includes(f))) {
+    ok('no forbidden files in skill directory');
+  }
+
+  // 7. Referenced files under references/ must exist.
+  const refRefs = [...content.matchAll(/references\/([a-zA-Z0-9_-]+\.md)/g)].map((m) => m[1]);
+  const uniqueRefs = [...new Set(refRefs)];
+  for (const ref of uniqueRefs) {
+    const refPath = join(dirAbs, 'references', ref);
+    if (!existsSync(refPath)) {
+      allOk = fail(`SKILL.md references "references/${ref}" but file does not exist`) && allOk;
+    }
+  }
+  if (uniqueRefs.length > 0 && uniqueRefs.every((r) => existsSync(join(dirAbs, 'references', r)))) {
+    ok(`all ${uniqueRefs.length} references/*.md links resolve`);
+  }
+
+  console.log('');
+  if (allOk) {
+    console.log('✓ All checks passed');
+    process.exit(0);
+  } else {
+    console.error('✗ Lint failed');
+    process.exit(1);
+  }
+}
+
+const arg = process.argv[2];
+if (!arg) {
+  console.error('Usage: node lint-skill.js <path/to/skill-directory>');
+  process.exit(2);
+}
+lintSkill(arg);

package/server/assets/skills/skill-refiner/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: skill-refiner
+description: |
+  Refine an existing Mavis skill with evidence-driven minimal patches.
+  Use when a skill has a concrete problem (wrong instructions, outdated steps,
+  missing edge case) backed by evidence. Do not use for creating new skills
+  (use skill-creator), or for stylistic preferences without evidence.
+descriptions:
+  zh-Hans: '基于证据对已有 Mavis skill 做最小修补，修正错误说明、过期步骤或缺失边界。'
+---
+
+# Skill Refiner
+
+Apply the smallest evidence-backed patch to fix a real skill problem.
+
+## When NOT to use
+
+- Creating a brand-new skill -> use `skill-creator`
+- No concrete evidence of a problem -> do nothing
+- The agent failed to follow correct instructions -> agent error, not a skill issue
+
+## Procedure
+
+1. **Collect evidence**.
+
+Identify exactly what went wrong. Evidence sources:
+
+- User feedback in the current session ("this skill told me to X but the right step is Y")
+- A concrete failure trace where the skill's instructions caused wrong behavior
+
+If the only evidence is "the skill could be better" with no specifics, stop here.
+
+2. **Read the current skill**.
+
+```
+skill({ name: "<name>" })
+```
+
+The native `skill` tool returns the SKILL.md body plus a `Location:` header with the file path. Capture the current content before editing.
+
+3. **Attribute the problem**.
+
+Before touching the skill, determine what actually went wrong:
+
+| Situation                                               | Action                                  |
+| ------------------------------------------------------- | --------------------------------------- |
+| Skill text is factually wrong or outdated               | Fix the skill                           |
+| Agent didn't follow the skill's correct instructions    | Do NOT change the skill -- agent error  |
+| Environment changed (new API, renamed command, etc.)    | Update the skill to reflect new reality |
+| Skill works for the common case but misses an edge case | Add the edge case                       |
+| Stylistic preference with no functional impact          | Do NOT change                           |
+
+If the problem is not in the skill itself, explain why and stop.
+
+4. **Generate patch**.
+
+Design the minimal change that fixes the problem. Document:
+
+```
+Problem:   <what is broken>
+Evidence:  <specific quote, error trace, or user statement>
+Rationale: <why this change fixes it without breaking other behavior>
+```
+
+Use `old_string` / `new_string` format for each edit point. Prefer surgical patches over section
+rewrites.
+
+5. **Self-check before applying**.
+
+Ask yourself:
+
+- Does this change actually address the evidence? (not a nearby symptom)
+- Could it break existing correct behavior?
+- Am I adding generic best practices instead of fixing a specific problem? (anti-pattern)
+- Is this a self-referential modification? (skill-refiner editing itself -- forbidden)
+
+If any check fails, revise the patch or abandon the change.
+
+6. **Apply the patch**.
+
+Two routes depending on skill type:
+
+#### User / Agent skills (mutable)
+
+Edit the skill file directly with the Edit tool (user skills live in
+`{{DATA_DIR}}/skills/<name>/`, agent skills in `{{DATA_DIR}}/agents/<agent>/skills/<name>/`).
+Re-read the file right before editing so you are patching the current content,
+not a stale copy.
+
+#### Built-in / Project skills (immutable at runtime)
+
+These live in the repo (`packages/local-runtime/assets/skills/` or the project's own skill
+directory under version control). Do NOT edit the runtime copies. Instead:
+
+1. Note the required change
+2. Advise the user to make the change in a worktree and submit via MR
+
+4. **Verify**.
+
+After applying, re-read the skill and confirm:
+
+- The patch landed correctly
+- The frontmatter `name` and `description` are intact
+- The overall skill still reads coherently
+
+```
+skill({ name: "<name>" })
+```
+
+## Hard constraints
+
+- **No secrets**: never write API keys, tokens, or credentials into skill files
+- **Size limit**: skill must stay under 100KB after patch
+- **Frontmatter sacred**: `name` and `description` fields must survive every edit
+- **No self-referential edits**: skill-refiner must not modify its own SKILL.md
+- **Evidence mandatory**: every patch must trace back to a specific problem
+- **Built-in skills are read-only**: changes go through MR, not runtime edits
+
+## Anti-patterns
+
+- Rewriting a skill from scratch when a one-line fix would work
+- Adding generic disclaimers ("always check...", "be careful to...")
+- Deleting a correct instruction because one report was a false positive
+- Changing style (wording, formatting) without functional justification
+- Applying multiple unrelated fixes in one patch (split them)
+- Acting on a report without verifying the evidence first
+
+## Output contract
+
+Deliver:
+
+- The applied patch with problem/evidence/rationale documented
+- Verification that the skill reads correctly post-patch
+
+## Failure handling
+
+- If the file changed under you (concurrent edit), re-read and re-plan the patch
+- If the patch makes the skill worse on re-read, revert and try a different approach
+- If evidence is ambiguous, explain why and stop rather than guessing

package/server/assets/skills/visual-page/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: visual-page
+description: >
+  Proactively create a visual HTML page when plain text cannot effectively convey the information.
+  Use this skill when: the content involves diagrams (flowcharts, architecture, sequence diagrams),
+  data comparisons (tables, charts), timelines, interactive demos, visual layouts, or any scenario
+  where a simple webpage would communicate more clearly than markdown text.
+  Also use when the user explicitly asks for a visual page, a webpage, or says "show me" / "画个图" / "做个页面" / "可视化".
+  This skill should be used proactively by the model — do not wait for the user to ask.
+descriptions:
+  zh-Hans: "在纯文本难以表达时主动创建可视化 HTML 页面，适用于图表、流程、时间线、交互演示和布局说明。"
+displayNames:
+  zh-Hans: "可视化页面"
+---
+
+# Visual Page Skill
+
+## Workflow
+
+Create a self-contained local HTML page and deliver it to the user.
+
+1. Choose an output path:
+   - If the user specified an output path, use it.
+   - If the user provided an input file or directory and no output path, save the HTML next to the input when appropriate.
+   - Otherwise, create a descriptive `.html` file in the current workspace or a temp directory.
+2. Write one complete `index.html`-style document with all CSS and JavaScript inlined unless an external CDN library is genuinely useful (Tailwind, Chart.js, Mermaid, D3).
+3. Verify the page is valid enough to open directly in a browser: no missing local assets, no broken relative references, responsive layout.
+4. Send the file to the user: `<media type="file" src="/absolute/path/to/page.html" caption="Visual page" />`
+
+When the user asks to revise or update a page, edit the existing HTML file directly so any previous references stay valid. If the previous file is unavailable, create a new one and mention it.
+
+---
+
+## Design Philosophy
+
+**Aesthetics is the goal, not decoration.** A page that "works" but looks cheap is a failure. The reader's eyes judge in 2 seconds before reading a single word. Treat beauty as a non-negotiable requirement equal to data correctness.
+
+**图表先行，文字辅助。** Charts, diagrams, and illustrations are the PRIMARY communication tool — they let readers grasp the point in seconds. Text exists to annotate details that visuals can't convey alone. When building a page, start from "what chart/diagram tells this story?" not "what paragraphs explain this?" If a section has 3+ paragraphs without a visual, you're doing it wrong — find the chart, flow, or illustration that replaces most of that text.
+
+**Design for the reader.** You are guiding a human eye, not displaying your work. One H1, one core conclusion, F-pattern scanning. Empty space is a feature. Charts and inline SVG beat dense paragraphs for any structured comparison or hierarchy.
+
+**Less is more.** Every element earns its place. No filler sections, no data slop (pointless stats/badges). When unsure between "add another card" or "let it breathe" — let it breathe.
+
+---
+
+## Rules
+
+### 1. Pick the page mode FIRST
+
+| Mode | When | Background | Font |
+|---|---|---|---|
+| **Data UI** | Dashboards, charts, tables | `#fafafa` / white | Sans (Outfit) |
+| **Long-read / Report** | Research, design docs, architecture pages | Warm cream `#f7f5f0` | Sans body + **serif headlines** (DM Serif Display) |
+| **Terminal** | Code demos, log viewers | `#1a1a2e` (NEVER `#000`) | Mono-prominent |
+
+Wrong-mode = ugly page. Research report on dark slate → dashboard look. Dashboard with serif → poster look.
+
+### 2. Color
+
+**BANNED:** pure `#000`, purple/blue AI gradients, neon glows, oversaturated accents.
+
+**Accent — pick ONE per page:**
+- Data UI: `#10b981` / `#3b82f6` / `#f59e0b` / `#f43f5e` / `#6366f1`
+- Report: `#2f6f5e` / `#c97b3f` / `#b06367`
+
+Use at 5-10% opacity for backgrounds, 100% for headers/icons only.
+
+**Report palette:** cream `#f7f5f0`, cards white + border `#e9e3d6`, text `#14171e` / `#3a4256` / `#7c7a72`. Optional: two corner radial gradients at 5% opacity.
+
+### 3. Typography
+
+**BANNED fonts:** Inter, Roboto, Arial, Fraunces, system defaults.
+
+**Use:** `Outfit` (sans), `JetBrains Mono` (mono), `DM Serif Display` (Report headlines only).
+
+```html
+<link href="https://fonts.googleapis.com/css2?family=DM+Serif+Display&family=Outfit:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
+```
+
+Report headlines: `font-serif text-3xl font-normal tracking-[-0.005em]`. Body always sans. Serif forbidden on Data UI.
+
+### 4. Layout
+
+**BANNED:** 3 equal cards in a row, centered-everything heroes, `border-l-4` accent cards, `h-screen`.
+
+**Use:** `max-w-5xl mx-auto px-6 md:px-8`, `space-y-16`, CSS Grid 12-column, `min-h-[100dvh]`. Mobile: single-column below 768px, no horizontal scroll.
+
+### 4.5 Density — CJK pages need tighter spacing
+
+Most CSS frameworks assume Latin typography. CJK characters are square blocks with built-in
+visual mass — copying Latin defaults (`line-height: 1.7+`, body `16-17px`, section gap `80px+`,
+card padding `28-32px`) makes Chinese pages feel sparse, with the first screen showing only
+a hero and one card.
+
+Calibrate: **does the first screen communicate the core idea, or is it just hero + breathing room?**
+
+Working ranges for CJK-heavy text (adjust by content, not hard rules):
+- Body: 14–15px, line-height 1.5–1.65
+- Headlines: H1 28–34px, H2 22–26px
+- Section gaps: 40–56px
+- Paragraph margin-bottom: 8–12px
+- Card padding: 16–22px
+
+Latin-only pages can be more generous. Mixed CJK + Latin follows the CJK side.
+
+### 5. Surfaces
+
+`rounded-2xl`, `border border-zinc-200/50`. Diffusion shadows only: `shadow-[0_2px_8px_rgba(0,0,0,0.04)]` / `shadow-[0_4px_16px_-2px_rgba(0,0,0,0.06)]`. Hover: `hover:-translate-y-0.5 hover:shadow-md transition-all duration-200`.
+
+### 6. Icons & diagrams — inline SVG only
+
+**No emoji as icons, no ASCII art (`┌─┐ │ ├─`) for diagrams.** Use inline SVG from [lucide.dev](https://lucide.dev) with `currentColor`, `stroke-width="2"`, `viewBox="0 0 24 24"`. One icon per section header max.
+
+For diagrams: use the minimal patterns in §8, or Mermaid for 4+ nodes. Never box-drawing characters.
+
+### 7. Visualization — chart-first, pick the right renderer
+
+**Default mindset:** every key point deserves a visual. Ask "what chart explains this?" before writing paragraphs. Text annotates what the visual can't show alone.
+
+| Visual need | Renderer |
+|---|---|
+| Architecture / module layers | Inline SVG or CSS grid |
+| Flowchart, process flow (≥4 nodes) | Mermaid |
+| Flowchart, process flow (2-3 nodes) | Inline SVG or CSS cards + arrows |
+| Pie / bar / line chart, time-series >8 points | Chart.js |
+| Data comparison (2-8 rows) | CSS bench bars or `<table>` |
+| Timeline / roadmap | CSS list with vertical rail |
+| Key-value pairs ≤6 rows | CSS two-column grid |
+
+**Rule:** don't import Chart.js / Mermaid for <5 data points or <4 nodes — hand-roll with CSS / inline SVG.
+
+When using Chart.js, match the page typography: `font.family = "'Outfit'"`, muted gridlines (`borderColor = 'rgba(0,0,0,0.04)'`), `borderRadius: 6`.
+
+### 8. Minimal patterns
+
+Three starting points for the most common shapes. Treat them as scaffolds, not constraints — adjust spacing, colors, structure to fit the page. CSS vars assume the Report palette (see §2).
+
+**Bench bar (comparison row):**
+```html
+<div class="bench"><span class="bench-label">Name</span><div class="bench-track"><div class="bench-fill" style="width:42%"></div></div><span class="bench-val">42%</span></div>
+```
+```css
+.bench { display: grid; grid-template-columns: 140px 1fr 60px; gap: 12px; align-items: center; padding: 6px 0; }
+.bench-track { height: 16px; background: var(--line-soft); border-radius: 6px; overflow: hidden; }
+.bench-fill { height: 100%; background: var(--primary); border-radius: 6px; }
+```
+
+**KV card (≤6 key-value rows):**
+```html
+<dl class="kv"><dt>Key</dt><dd>Value</dd><dt>Key</dt><dd>Value</dd></dl>
+```
+```css
+.kv { display: grid; grid-template-columns: 110px 1fr; row-gap: 10px; column-gap: 16px; margin: 0; }
+.kv dt { color: var(--muted); border-bottom: 1px dashed var(--line); padding-bottom: 8px; }
+.kv dd { margin: 0; border-bottom: 1px dashed var(--line); padding-bottom: 8px; }
+```
+
+**Step timeline (vertical rail):**
+```html
+<ol class="timeline"><li><strong>Step</strong><p>Detail.</p></li><li><strong>Step</strong><p>Detail.</p></li></ol>
+```
+```css
+.timeline { list-style: none; padding: 0; margin: 0; position: relative; }
+.timeline::before { content: ""; position: absolute; left: 8px; top: 6px; bottom: 6px; width: 2px; background: var(--primary); opacity: .35; }
+.timeline li { position: relative; padding: 0 0 24px 32px; }
+.timeline li::before { content: ""; position: absolute; left: 2px; top: 4px; width: 14px; height: 14px; border-radius: 50%; background: white; border: 2px solid var(--primary); }
+```
+
+For architecture diagrams (boxes + arrows) and multi-node flows, hand-write inline SVG or use Mermaid — they vary too much to template.
+
+---
+
+## Anti-Slop Checklist
+
+- [ ] 2-second test — first impression crafted, not generic?
+- [ ] Reader gets core conclusion within one screen
+- [ ] **Every key point has a visual** — no section with 3+ paragraphs and zero charts/diagrams
+- [ ] **Renderer matched correctly** — structured data uses SVG/CSS/Chart.js
+- [ ] Enough whitespace — if "full", remove a section
+- [ ] Page mode picked correctly (not dark dashboard for a report)
+- [ ] No `#000`, no AI gradients, no neon, no Inter/Roboto/Arial
+- [ ] No emoji icons — inline SVG with `currentColor`
+- [ ] No ASCII art diagrams — using CSS/SVG patterns
+- [ ] No 3-equal-cards, no `border-l-4` accent cards
+- [ ] Didn't import Chart.js/Mermaid for <5 data points
+- [ ] No filler, no round-number stats, no banned copy ("Elevate", "Seamless")
+- [ ] Mobile responsive, every interactive element has hover state
+- [ ] Delivered as a local `.html` file via `<media />`
+
+---
+
+## Example Output
+
+> Here's a visual page — much clearer than text:
+>
+> `<media type="file" src="/absolute/path/to/page.html" caption="Visual page" />`

package/server/assets/skills/x-link-reader/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: x-link-reader
+description: "Read X/Twitter content from x.com or twitter.com URLs. Use when the user shares an X or Twitter link (tweet or profile) and asks about its content. Also use when webfetch fails on x.com with anti-bot errors. Bypasses X's anti-scraping via the FxTwitter API — no API key needed."
+descriptions:
+  zh-Hans: "读取 x.com 或 Twitter 链接内容，在网页抓取失败或遇到反爬时通过 FxTwitter API 获取信息。"
+---
+
+# X/Twitter Link Reader
+
+X.com blocks direct HTTP fetching (returns anti-bot challenge pages). This skill
+uses the open-source [FxTwitter](https://github.com/FixTweet/FxTweet) API to
+retrieve tweet and profile data as structured JSON — free, no auth required.
+
+## When to use
+
+- User shares a URL matching `x.com/*/status/*` or `twitter.com/*/status/*`
+- User shares a profile URL like `x.com/username`
+- User asks "what does this tweet say", "summarize this post", etc.
+- `webfetch` on an `x.com` URL returns an error or empty page
+
+## Tweet: fetch a single post
+
+Replace the domain with `api.fxtwitter.com` and fetch as **text**:
+
+```
+Original:  https://x.com/elonmusk/status/1234567890
+Proxy:     https://api.fxtwitter.com/elonmusk/status/1234567890
+```
+
+Use `webfetch` with format `text` (the response is JSON):
+
+```
+webfetch url="https://api.fxtwitter.com/{user}/status/{id}" format="text"
+```
+
+### Tweet response structure
+
+```jsonc
+{
+  "code": 200,
+  "tweet": {
+    "url": "https://x.com/user/status/123",
+    "text": "The full tweet text",
+    "author": {
+      "name": "Display Name",
+      "screen_name": "handle",
+      "followers": 12345,
+      "avatar_url": "https://..."
+    },
+    "created_at": "Sun Apr 05 19:32:37 +0000 2026",
+    "replies": 20,
+    "retweets": 181,
+    "likes": 1424,
+    "views": 116843,
+    "lang": "en",
+    "replying_to": "other_user",        // null if not a reply
+    "quoted_status_result": { ... },     // quoted tweet, if any
+    "media": {
+      "photos": [{ "url": "..." }],
+      "videos": [{ "url": "..." }]
+    },
+    "card": {
+      "url": "...",
+      "title": "...",
+      "description": "..."
+    }
+  }
+}
+```
+
+## Profile: fetch user info
+
+```
+webfetch url="https://api.fxtwitter.com/{username}" format="text"
+```
+
+Returns user profile data including name, bio, follower/following counts, etc.
+
+## Translate a tweet
+
+Append `/translate/{lang}` to the tweet path:
+
+```
+webfetch url="https://api.fxtwitter.com/{user}/status/{id}/translate/zh" format="text"
+```
+
+Supported language codes: `zh`, `en`, `ja`, `ko`, `es`, `fr`, `de`, etc.
+
+## Key fields to present
+
+1. **Author**: `tweet.author.name` (@`tweet.author.screen_name`)
+2. **Text**: `tweet.text`
+3. **Date**: `tweet.created_at`
+4. **Engagement**: likes, retweets, replies, views
+5. **Media**: photos/videos URLs if present
+6. **Card**: linked article title/description if present
+7. **Reply context**: who the tweet is replying to, if applicable
+
+## Limitations
+
+- **Individual tweets and profiles only** — no timelines, search, or batch.
+- **Public content only** — private/protected accounts return errors.
+- **Deleted tweets** — the API returns an error; report this to the user.
+- **No write operations** — read-only, cannot post or interact.
+
+## Rules
+
+- Always use `api.fxtwitter.com`, never fetch `x.com` or `twitter.com` directly.
+- This API is read-only and public — no API key or authentication needed.
+- If the user just wants a tweet summary, present it concisely; don't dump raw JSON.