{"repo": "andrewnggirl/skilllens", "files": {"web/README.md": {"0005e1d20d8c04491a10361093c27ba54457387c": {"t": 1786068581.311137, "n": 7044, "h": "110ded90cab2abca", "c": "# SkillLens\n\n> Upload an Agent Skill → get a quantitative, rubric-based audit.\n> Compatible with **Claude / OpenClaw** style skill packages.\n\nSkillLens helps skill authors evaluate whether a skill is clear, valuable, reliable, lightweight, and ready to publish. It combines deterministic rule checks with optional LLM-based Deep Review and GitHub market research.\n\nThe Web UI also includes a Finance Expert Review MVP. Users can choose a finance scenario before uploading, then full Deep Review adds `domainExpert.score`, finance risk level, and commercial readiness on top of the general SkillLens score.\n\n## Scope Of This README\n\nThis file is only for running and configuring the Web app. For the full product overview, read `../README.md`. For Cursor, WorkBuddy, Hermes, or other code-agent workflows, use the official Agent CLI contract in `../skills/skill-scorer/USAGE.md`.\n\n## What You Can Upload\n\n- A single `SKILL.md`\n- A skill folder with `scripts/`, `references/`, `assets/`, tests, or schemas\n- A zipped skill package\n- Claude-style, OpenClaw-style, or Cursor-compatible skill projects\n\nThe built-in sample comes from `../skills/skill-scorer/examples/pr-reviewer`.\n\n## Scoring Model\n\nThe 100-point rubric has 5 pillars (Skill Value · Market Competitiveness · Runtime Cost · Reliability · Writeup Quality). Sub-dimensions are activated per skill structure:\n\n- **atomic** — single-purpose skill; uses the full shared backbone (script fallback, output validation, etc.)\n- **pipeline** — orchestrator over multiple sub SKILL.md; adds 5 type-specific dimensions (routing, sub-agent boundaries, IO protocol, partial-failure handling, sub-skill self-containment)\n- **composite** — independent toolkit bundle; adds 4 type-specific dimensions (tool index, orthogonality, consistency, discoverability)\n\nThe Uploader has 4 type cards above the upload area (Auto / Atomic / Pipeline / Composite) so users can override the auto-detection. Out-of-scope dimensions are folded into a \"show N dimensions not applicable\" toggle at the bottom of each pillar to keep the dashboard clean.\n\nThe rubric source is `../skills/skill-scorer/rubric/rubric.yaml` (single source of truth, mirrored into `lib/rubric/rubric.ts` by `sync_rubric_to_ts.py`).\n\nThe finance expert overlay source is `../skills/skill-scorer/domains/finance/rubric.yaml`.\n\nFor the full rubric backbone, type-specific dimension table, and `applies_to` mechanism, see the root [`README.md`](../README.md) (\"What It Evaluates\" section) or [`USAGE.md`](../skills/skill-scorer/USAGE.md).\n\n## Quick Start\n\n```bash\ncd web\nnpm install\ncp .env.example .env.local\n# edit .env.local and add your own model API key\nnpm run dev\n# open http://localhost:3000\n```\n\n## Self-Hosted Model Configuration\n\nSkillLens is designed for open-source self-hosting. API keys are read only from server-side environment variables and are never required in the browser.\n\n1. Copy the example env file:\n\n```bash\ncp .env.example .env.local\n```\n\n2. Add at least one provider key:\n\n```env\nDEEPSEEK_API_KEY=\n# or\nANTHROPIC_API_KEY=\n```\n\n3. Start the app:\n\n```bash\nnpm run dev\n```\n\nIf no model key is configured, SkillLens falls back to mock scores so the UI can still be previewed.\n\n## Web Features\n\n- Upload a single `SKILL.md`, a skill folder, or a zipped skill package.\n- Choose `General Review` or a supported expert domain before upload.\n- Finance Expert Review currently supports fundraising, quant trading, stock trading, securities research, banking workflow, financial education, financial data analysis, and other finance scenarios.\n- Load built-in examples. Finance examples are mapped to the selected finance scenario.\n- Run optional LLM Deep Review when a provider key is configured.\n- View score KPI cards, radar charts, pillar/check details, top suggestions, and editable weights.\n- Export JSON, copy Markdown, or generate PDF.\n\n## Code Agent / CLI Usage\n\nThis README is only for the Web app. For Cursor, WorkBuddy, Hermes, or other code-agent workflows, use the official agent contract in `../skills/skill-scorer/USAGE.md`.\n\nFor a public deployment, keep the browser-origin guard enabled so visitors cannot spend your model key by calling `/api/llm` directly from tools:\n\n```env\nLLM_REQUIRE_BROWSER_REQUEST=1\n```\n\nWith this setting, users can still click Deep Review in the web UI without entering a token. `/api/llm` only accepts same-origin browser requests from the SkillLens page. If you also need private server-to-server access, set `LLM_ACCESS_TOKEN` and pass it in `x-skilllens-llm-token` or `Authorization: Bearer ...`.\n\n### Security Notes\n\n- Do not commit `.env.local`, `.env`, or any real API key.\n- Do not put secrets in `NEXT_PUBLIC_*` variables. Those are bundled into client-side JavaScript.\n- Keep `LLM_REQUIRE_BROWSER_REQUEST=1` before exposing a server that has `DEEPSEEK_API_KEY` or `ANTHROPIC_API_KEY`.\n- Use `web/.env.example` for documentation only; keep real values in your local machine or deployment platform secrets.\n- If a real key was ever committed, pasted into an issue, shared in a screenshot, or included in logs, rotate it in the provider dashboard before publishing.\n\n### Optional Environment Variables\n\n```env\nANTHROPIC_MODEL=claude-sonnet-4-5-20250929\nDEEPSEEK_MODEL=deepseek-v4-flash\nLLM_THINKING_MODE=disabled\nLLM_TIMEOUT_MS=180000\nDAILY_SCORE_LIMIT=20\nLLM_REQUIRE_BROWSER_REQUEST=1\nLLM_ACCESS_TOKEN=\nGITHUB_TOKEN=\nMARKET_CACHE_TTL_MS=1800000\n```\n\n`GITHUB_TOKEN` is optional. It only increases the GitHub Search API rate limit for market research.\n\n## Stack\n\n- Next.js (App Router) + TypeScript + Tailwind\n- `gray-matter` for frontmatter, `yaml` for rubric, `jszip` for archives\n- Recharts for the radar chart, `html2canvas` + `jsPDF` for PDF export\n- General rubric source of truth: `../skills/skill-scorer/rubric/rubric.yaml`\n- Finance expert rubric source: `../skills/skill-scorer/domains/finance/rubric.yaml`\n- TypeScript rubric mirror: `lib/rubric/rubric.ts`\n\n## Important Directories\n\n```text\nweb/\n├── app/                  # Pages and API routes\n│   └── api/\n│       ├── llm/          # Server-side LLM review endpoint\n│       ├── market/       # GitHub market survey endpoint\n│       └── sample/[id]/  # Built-in sample loader\n├── components/           # Upload, report, radar, pillar/check UI\n├── lib/\n│   ├── domain/           # Finance expert domain logic\n│   ├── llm/              # Provider, prompt, cache, and types\n│   ├── market/           # Keyword extraction and market client\n│   ├── rubric/           # TS mirror of the general rubric\n│   ├── scoring/          # Rule scoring, aggregation, LLM client\n│   └── spec/             # Skill loading and parsing\n└── .env.example\n```\n\n## Scripts\n\n- `npm run dev` — 启动本地开发服务器\n- `npm run lint` — 运行 ESLint\n- `npm run build` — 生产构建\n- `npm run typecheck` — TS 类型检查\n\n## Before Publishing\n\nRun a quick secret scan before publishing. For example, use a dedicated tool such as `gitleaks`:\n\n```bash\ngitleaks detect --source .\n```\n\nThe scan may find variable names in docs or code. It should not find real secret values.\n"}}}}