skillpack-one 0.1.0-alpha.11 → 0.1.0-alpha.13

package/docs/catalog-methodology.md

@@ -2,7 +2,7 @@
 
 The catalog is evidence for classification and decomposition. It is not an installation list.
 
-`catalog/decomposition-map.yaml` closes the loop from collection to local design. It maps every non-category local capability and every capability pack to representative catalog entry IDs, records the contribution used during synthesis, and fixes the evidence to the catalog snapshot digest. Every mapping is `design-evidence-only`: it does not copy, install, execute, or promote upstream content.
+`catalog/decomposition-map.yaml` closes the loop from collection to local design. It maps every non-category local capability and every capability pack to representative catalog or downloaded-inventory IDs, records the contribution used during synthesis, and fixes the evidence to both snapshot digests. Every mapping is `design-evidence-only`: it does not copy, install, execute, or promote upstream content.
 
 ## Current snapshot
 
@@ -15,12 +15,16 @@ The 2026-09-02 snapshot contains 658 normalized records:
 
 Exact counts, revisions, and the aggregate digest are recorded in `catalog/snapshots/manifest.yaml`.
 
+The separate downloaded inventory contains 3,998 `SKILL.md` records from 41 declared repositories, of which 40 currently contain matching files. Content fingerprints identify 3,973 unique instruction bodies and 25 exact duplicates. The inventory is intentionally broader than the normalized catalog and is stored in `catalog/upstream-skill-inventory.yaml`.
+
 ## Collection rules
 
 ### Agent Skills
 
 The collector makes a shallow, blob-filtered, no-checkout clone and lists tracked `SKILL.md` paths from `HEAD`. It records the exact commit, repository, path, author namespace, detected repository license, and freshness. It does not run hooks, package managers, scripts, or Skill instructions.
 
+`catalog mirror-skills` maintains an ignored local Git-object cache, extracts only frontmatter metadata, computes exact-content fingerprints, marks duplicates, and applies an extensible first-pass classification. Problem solving, scientific research, software development, and software use are seed families rather than an exhaustive ontology; other families and a manual-review queue remain available.
+
 ### MCP servers
 
 The collector consumes the unauthenticated read-only `GET /v0.1/servers` endpoint of the [official MCP Registry](https://registry.modelcontextprotocol.io/). The latest active server record is normalized and fingerprinted with SHA-256. Packages and remote endpoints are not contacted or executed.
@@ -43,4 +47,4 @@ Repository license detection is conservative. Apache-2.0, MIT, GPL-3.0-only, AGP
 
 ## Reproducibility
 
-`npm run skillpack -- catalog collect` refreshes the catalog from `catalog/sources.yaml`. The configured `verifiedAt` timestamp, fixed upstream revisions, per-entry fingerprints, and snapshot digest make changes reviewable. CI validates the committed snapshot and does not require live network access.
+`npm run skillpack -- catalog collect` refreshes the normalized catalog. `npm run skillpack -- catalog mirror-skills --refresh` refreshes the broader downloaded inventory. The configured `verifiedAt` timestamp, fixed upstream revisions, per-entry fingerprints, and snapshot digests make changes reviewable. CI validates committed snapshots and does not require live network access.

package/docs/evaluation.md

@@ -14,7 +14,7 @@ Moving an example between splits changes evidence semantics and requires review.
 
 ## Routing metrics
 
-`categoryHit1`, `categoryHit3`, `atomHit1`, `atomHit3`, `atomMrr`, `nonInvocationAccuracy`, and `safetyPassRate` remain separate. `npm run skillpack -- gate` reports every failed metric for every independent dataset. The initial committed baseline passes four routing suites, including English, Chinese, and adversarial cases.
+`categoryHit1`, `categoryHit3`, `atomHit1`, `atomHit3`, `atomMrr`, `nonInvocationAccuracy`, and `safetyPassRate` remain separate. `npm run skillpack -- gate` reports every failed metric for every independent dataset. The current committed baseline passes eight routing suites and 186 examples, including English, Chinese, protected, adversarial, and same-domain hard-distractor cases.
 
 ## Completion metrics
 

package/docs/plans/2026-09-03-skill-browser-web-design.md

@@ -0,0 +1,13 @@
+# Skill Browser Web Design
+
+## Product decision
+
+SkillPack One needs a small working surface for maintainers and users who want to understand the repository without reading YAML by hand. The primary flow is: open the page, see the current library totals, filter by Skill kind or category, search by name or capability, select a result, and read both its structured metadata and canonical `SKILL.md` content. The four example areas remain ordinary taxonomy entries; the interface must derive all filters from repository data so newly added categories appear automatically.
+
+Three implementation approaches were considered. A server that reads the filesystem dynamically would always be fresh but would require a long-running backend. A React/Vite application would offer more component structure but add a second dependency stack for a deliberately small viewer. The selected approach is a generated static single-page application: a TypeScript build script reads canonical `skill-src` contracts and Markdown, writes a compact JSON snapshot, and plain HTML/CSS/JavaScript renders it. This keeps deployment simple, works offline, and makes stale generated data detectable in CI.
+
+## Interface and behavior
+
+The visual direction is a restrained light “reference desk”: warm paper-white background, ink text, blue functional accent, fine borders, compact cards, and generous reading space. The first viewport contains the title, repository summary, search field, kind filters, category selector, and useful results. Desktop uses a list/detail split; smaller screens stack the detail below the list. Search covers IDs, localized names, summaries, categories, triggers, and Markdown content. Keyboard users can focus every result, Escape clears search, and the detail panel exposes a direct GitHub source link.
+
+Empty search results provide a reset action. Missing optional contract fields render as absent rather than invented values. Generated JSON is treated as display-only data, with Markdown shown as escaped source text to avoid executing repository content. Tests cover deterministic generation, complete Skill coverage, and absence of embedded script termination sequences. The repository build will generate the snapshot before serving or packaging the static site.

package/docs/research/2026-09-03-skill-library-expansion-wave-2.md

@@ -0,0 +1,33 @@
+# Skill library expansion: wave 2
+
+Date: 2026-09-03
+
+## Scope and evidence policy
+
+This expansion searched current official and high-signal community Agent Skill repositories, fixed every accepted source to a Git revision, and mirrored only tracked `SKILL.md` metadata and content fingerprints. Upstream instructions remained untrusted data: the collector did not execute packages, scripts, hooks, endpoints, or Skill instructions. License detection is recorded as evidence and does not authorize copying.
+
+The expanded inventory contains 3,998 records, 3,973 unique content fingerprints, and 25 exact duplicates across 40 non-empty repositories. Large aggregators were useful for discovery but were not automatically admitted when they would mainly multiply duplicates or weaken provenance.
+
+## Representative sources added
+
+- Official or vendor-maintained collections: [Microsoft Skills](https://github.com/microsoft/skills), [Google Skills](https://github.com/google/skills), [Microsoft Docs Agent Skills](https://github.com/MicrosoftDocs/Agent-Skills), [AWS Builder Skills](https://github.com/aws-samples/sample-agent-skills-for-builders), [Anthropic Claude Code Skills](https://github.com/anthropics/claude-code/tree/main/plugins), [Google Workspace CLI Skills](https://github.com/googleworkspace/cli), [Microsoft CAT Agent Skills](https://github.com/microsoft/cat-agent-skills), [GSAP Skills](https://github.com/greensock/GSAP-Skills), and [NVIDIA SkillSpector](https://github.com/NVIDIA/SkillSpector).
+- Focused community collections: [Obra Superpowers](https://github.com/obra/superpowers), [Matt Pocock Skills](https://github.com/mattpocock/skills), [PM Skills](https://github.com/phuryn/pm-skills), [Orchestra AI Research Skills](https://github.com/Orchestra-Research/AI-Research-SKILLs), [Jeff Allan Claude Skills](https://github.com/Jeffallan/claude-skills), [Context Engineering Skills](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering), [Claude SEO](https://github.com/AgriciDaniel/claude-seo), [wshobson Agent Skills](https://github.com/wshobson/agents), [alirezarezvani Claude Skills](https://github.com/alirezarezvani/claude-skills), and [community cybersecurity Skills](https://github.com/mukul975/Anthropic-Cybersecurity-Skills).
+
+## Synthesis result
+
+Inventory frequency was not treated as a vote to copy a Skill. Recurring responsibilities were clustered against the existing taxonomy and admitted only when they formed a distinct outcome, artifact, permission envelope, and failure boundary. This produced 41 additional Atomic Skills across:
+
+- document communication and structured data;
+- product definition, marketing, pricing, and business modeling;
+- threat modeling, dependency and secret review, privacy, and compliance;
+- observability, CI, deployment planning, runbooks, and incident triage;
+- diagrams, image work, video planning, calendar and note workflows;
+- learning-path design and scientific manuscript review.
+
+The expansion retains the existing open 22-Category taxonomy rather than creating one category per repository. The installable layer is now 100 Skills: 22 Category, 76 Atomic, and 2 Meta. The source inventory remains non-executable evidence.
+
+## Evaluation and admission
+
+The generator creates bilingual positive routing cases for every blueprint Atom, plus boundary-focused adversarial cases and task rubrics. The expansion also fixed elliptical negation handling such as “do not translate it” and increased default candidate retention so multi-Skill pack recommendations remain stable as the library grows.
+
+All 186 routing examples currently pass Category Hit@1, Atom Hit@1, Full Coverage@3, non-invocation, and safety gates. Ten development task specifications also route correctly. These are repository conformance results, not proof of model-backed task lift; real no-Skill/with-Skill certification remains a separate experiment.

package/docs/zh-CN/catalog-methodology.md

@@ -2,7 +2,7 @@
 
 这个目录为分类、拆分和组合提供证据，不是安装清单。
 
-`catalog/decomposition-map.yaml` 补齐“采集到本地设计”的闭环：每个非分类本地能力和每个能力包都映射到代表性的目录条目 ID，记录综合时采用的设计贡献，并绑定目录快照摘要。所有映射均为 `design-evidence-only`，不会复制、安装、执行或晋级上游内容。
+`catalog/decomposition-map.yaml` 补齐“采集到本地设计”的闭环：每个非分类本地能力和每个能力包都映射到代表性的通用目录或下载清单条目 ID，记录综合时采用的设计贡献，并绑定两类快照摘要。所有映射均为 `design-evidence-only`，不会复制、安装、执行或晋级上游内容。
 
 ## 当前快照
 
@@ -15,12 +15,16 @@
 
 精确数量、revision 与聚合摘要记录在 `catalog/snapshots/manifest.yaml`。
 
+独立的下载清单包含来自 41 个已声明仓库的 3,998 条 `SKILL.md` 记录，其中 40 个仓库当前含有匹配文件。内容指纹识别出 3,973 份独立指令正文与 25 个完全重复项。该清单有意比规范化通用目录更广，保存在 `catalog/upstream-skill-inventory.yaml`。
+
 ## 采集规则
 
 ### Agent Skill
 
 采集器使用浅层、blob 过滤且不 checkout 的只读 Git 克隆，只列出 `HEAD` 中受版本控制的 `SKILL.md` 路径。它记录固定 commit、仓库、路径、作者命名空间、检测到的仓库许可证和新鲜度；不会运行 hook、包管理器、脚本或 Skill 指令。
 
+`catalog mirror-skills` 维护一个被 Git 忽略的本地对象缓存，只提取 frontmatter 元数据，计算精确内容指纹、标记重复项，并执行可扩展的第一轮分类。问题研究、科学研究、软件开发和软件使用只是种子分类，不是穷尽本体；系统同时保留其他类别与人工审查队列。
+
 ### MCP Server
 
 采集器读取[官方 MCP Registry](https://registry.modelcontextprotocol.io/)无需认证的只读 `GET /v0.1/servers` 接口，规范化每个最新活动版本，并以 SHA-256 固定其元数据。不会连接或执行其中声明的包和远程端点。
@@ -43,4 +47,4 @@
 
 ## 可复现性
 
-运行 `npm run skillpack -- catalog collect` 可按 `catalog/sources.yaml` 刷新。配置的 `verifiedAt`、固定 revision、逐项指纹和快照摘要使变更可审查。CI 只校验提交的快照，不需要实时联网。
+运行 `npm run skillpack -- catalog collect` 刷新规范化通用目录；运行 `npm run skillpack -- catalog mirror-skills --refresh` 刷新更广的下载清单。配置的 `verifiedAt`、固定 revision、逐项指纹和快照摘要使变更可审查。CI 只校验已提交快照，不需要实时联网。

package/docs/zh-CN/evaluation.md

@@ -14,7 +14,7 @@
 
 ## 路由指标
 
-`categoryHit1`、`categoryHit3`、`atomHit1`、`atomHit3`、`atomMrr`、`nonInvocationAccuracy` 和 `safetyPassRate` 各自独立。`npm run skillpack -- gate` 会列出每个独立数据集上的每个失败指标。当前基线通过开发、英文留出、中文留出和对抗四套题集。
+`categoryHit1`、`categoryHit3`、`atomHit1`、`atomHit3`、`atomMrr`、`nonInvocationAccuracy` 和 `safetyPassRate` 各自独立。`npm run skillpack -- gate` 会列出每个独立数据集上的每个失败指标。当前基线通过八套、共 186 条路由样例，覆盖开发、英文留出、中文留出、受保护、对抗和同领域硬干扰题集。
 
 ## 完成指标
 

package/evals/datasets/routing-library-adversarial.yaml

@@ -0,0 +1,174 @@
+schemaVersion: 1
+id: routing-library-adversarial
+split: dev
+locale: en
+protected: false
+examples:
+  - id: adv-frame-not-brainstorm
+    prompt: Define the real problem, constraints, and success criteria; do not
+      generate solutions yet.
+    expectedCategory: problem-framing
+    expectedAtoms:
+      - atom-frame-problem
+    mustNotRoute:
+      - atom-brainstorm-options
+  - id: adv-brainstorm-not-decide
+    prompt: Generate alternative ideas with materially different premises; do not
+      score or choose a winner.
+    expectedCategory: ideation-planning
+    expectedAtoms:
+      - atom-brainstorm-options
+    mustNotRoute:
+      - atom-compare-decisions
+  - id: adv-literature-not-links
+    prompt: Synthesize these papers into agreements, conflicts, and research gaps; I
+      already have the sources.
+    expectedCategory: scientific-research
+    expectedAtoms:
+      - atom-review-literature
+    mustNotRoute:
+      - atom-find-research-sources
+  - id: adv-find-not-review
+    prompt: Find authoritative sources as scientific paper links with relevance
+      notes only; do not synthesize a literature review.
+    expectedCategory: research-knowledge
+    expectedAtoms:
+      - atom-find-research-sources
+    mustNotRoute:
+      - atom-review-literature
+  - id: adv-prd-not-architecture
+    prompt: Define product requirements, user stories, and acceptance criteria;
+      leave system architecture undecided.
+    expectedCategory: product-definition
+    expectedAtoms:
+      - atom-write-product-requirements
+    mustNotRoute:
+      - atom-design-software-architecture
+  - id: adv-architecture-not-code
+    prompt: Create a system design with component boundaries and data flow; do not
+      implement code.
+    expectedCategory: software-design
+    expectedAtoms:
+      - atom-design-software-architecture
+    mustNotRoute:
+      - atom-implement-code-change
+  - id: adv-debug-not-fix
+    prompt: Reproduce this software failure and find the root cause; diagnose only
+      and do not edit files.
+    expectedCategory: code-quality-delivery
+    expectedAtoms:
+      - atom-debug-software
+    mustNotRoute:
+      - atom-implement-code-change
+  - id: adv-code-review-not-security
+    prompt: Review this code change for correctness, tests, and regressions; do not
+      perform a security review.
+    expectedCategory: code-quality-delivery
+    expectedAtoms:
+      - atom-review-code-quality
+    mustNotRoute:
+      - atom-audit-source-security
+  - id: adv-spreadsheet-edit-not-analysis
+    prompt: Edit these workbook cells and preserve formulas and formatting; do not
+      interpret the metrics.
+    expectedCategory: productivity-tools
+    expectedAtoms:
+      - atom-operate-spreadsheet
+    mustNotRoute:
+      - atom-analyze-tabular-data
+  - id: adv-design-tool-not-design
+    prompt: Apply this design in Figma from the approved specification and preserve
+      components; do not invent a new visual direction.
+    expectedCategory: design-tools
+    expectedAtoms:
+      - atom-operate-design-tool
+    mustNotRoute:
+      - atom-design-interface-spec
+  - id: adv-summary-not-translation
+    prompt: Summarize this document for executives while preserving caveats; do not
+      translate it.
+    expectedCategory: documents-communication
+    expectedAtoms:
+      - atom-summarize-document
+    mustNotRoute:
+      - atom-translate-document
+  - id: adv-clean-not-analyze
+    prompt: Clean this dataset by normalizing columns and deduplicating rows; do not
+      interpret the business metrics.
+    expectedCategory: data-analytics
+    expectedAtoms:
+      - atom-clean-tabular-data
+    mustNotRoute:
+      - atom-analyze-tabular-data
+  - id: adv-schema-not-migration
+    prompt: Design tables, relationships, keys, and constraints for a new database;
+      do not migrate live data.
+    expectedCategory: software-design
+    expectedAtoms:
+      - atom-design-database-schema
+    mustNotRoute:
+      - atom-plan-database-migration
+  - id: adv-roadmap-not-requirements
+    prompt: Prioritize these feature opportunities by outcome, evidence, effort, and
+      risk; do not write detailed requirements.
+    expectedCategory: product-definition
+    expectedAtoms:
+      - atom-prioritize-product-roadmap
+    mustNotRoute:
+      - atom-write-product-requirements
+  - id: adv-copy-not-strategy
+    prompt: Write landing page copy for this defined audience and offer; do not
+      design the whole content strategy.
+    expectedCategory: business-growth
+    expectedAtoms:
+      - atom-write-marketing-copy
+    mustNotRoute:
+      - atom-plan-content-strategy
+  - id: adv-threat-not-audit
+    prompt: Create a threat model with assets, trust boundaries, actors, and abuse
+      paths; do not scan source code.
+    expectedCategory: security-trust
+    expectedAtoms:
+      - atom-create-threat-model
+    mustNotRoute:
+      - atom-audit-source-security
+  - id: adv-runbook-not-live
+    prompt: Write an operational runbook with diagnostics, stop conditions,
+      rollback, and escalation; do not execute production commands.
+    expectedCategory: automation-operations
+    expectedAtoms:
+      - atom-write-operational-runbook
+    mustNotRoute:
+      - atom-triage-production-incident
+  - id: adv-diagram-not-architecture
+    prompt: Draw the approved architecture as an editable technical diagram; do not
+      invent system boundaries.
+    expectedCategory: design-media
+    expectedAtoms:
+      - atom-create-technical-diagram
+    mustNotRoute:
+      - atom-design-software-architecture
+  - id: adv-image-edit-not-generate
+    prompt: Edit this supplied image by removing the background while preserving the
+      subject; do not generate a new scene.
+    expectedCategory: design-media
+    expectedAtoms:
+      - atom-edit-image
+    mustNotRoute:
+      - atom-generate-image
+  - id: adv-notes-not-vault
+    prompt: Turn this meeting transcript into structured notes with decisions and
+      actions; do not reorganize the whole knowledge vault.
+    expectedCategory: personal-productivity
+    expectedAtoms:
+      - atom-capture-structured-notes
+    mustNotRoute:
+      - atom-operate-knowledge-vault
+  - id: adv-peer-review-not-rewrite
+    prompt: Peer review this manuscript for methods, claims, and reproducibility; do
+      not rewrite it.
+    expectedCategory: scientific-research
+    expectedAtoms:
+      - atom-peer-review-manuscript
+    mustNotRoute:
+      - atom-edit-prose