@anionzo/skill 1.1.0

package/i18n/design-brief.vi.md

@@ -0,0 +1,97 @@
+# 📋 Tóm Tắt Thiết Kế
+
+> 🌐 **[English](../docs/design-brief.md)**
+
+---
+
+### ❓ Vấn Đề
+
+Workflow AI thường hỏng vì một trong hai lý do:
+
+- 🔴 Agent không có phương pháp lặp lại cho một loại công việc
+- 🔴 Agent không có ngữ cảnh bền vững về cách người dùng muốn làm việc
+
+Repo này tách biệt hai mối quan tâm đó.
+
+### 📦 Repo Này Là Gì
+
+Thư viện vận hành cá nhân với ba lớp:
+
+| Lớp | Mục đích |
+|---|---|
+| 🎯 `skills/` | Hướng dẫn workflow tái sử dụng |
+| 📚 `knowledge/` | Ghi chú bền vững về nguyên tắc, heuristic, ngữ cảnh dự án |
+| 🔌 `adapters/` | Hướng dẫn phân phối cho các nền tảng agent |
+
+### 🚫 Repo Này Không Phải
+
+- ❌ Không phải task manager
+- ❌ Không phải plugin runtime
+- ❌ Không phải hệ thống memory dựa trên database
+- ❌ Không phải prompt pack cứng cho một agent duy nhất
+
+### 🔍 Ý Tưởng Từ Upstream
+
+#### Từ [`hoangnb24/skills`](https://github.com/hoangnb24/skills)
+
+- 🔹 Thiết kế skill theo workflow-first
+- 🔹 Router hoặc meta-skill quyết định load gì tiếp theo
+- 🔹 Output contract rõ ràng
+- 🔹 Reference và example đặt cạnh mỗi skill
+
+#### Từ các coding agent plan-first
+
+- 🔹 Tách planning khỏi execution
+- 🔹 Hiển thị mức sẵn sàng triển khai trước khi bắt đầu code
+- 🔹 Giữ plan đủ cụ thể để thực thi và dễ review
+
+#### Từ [`obra/superpowers`](https://github.com/obra/superpowers)
+
+- 🔹 Thêm giai đoạn brainstorming trước planning khi request còn mơ hồ
+- 🔹 Coi verification là cổng thật, không phải bước cuối cho có
+- 🔹 Giữ skill triggering và chuyển tiếp workflow rõ ràng
+
+#### Từ [`affaan-m/everything-claude-code`](https://github.com/affaan-m/everything-claude-code)
+
+- 🔹 Tư duy phân lớp: skill, rule ổn định, memory, adapter
+- 🔹 Hỗ trợ đa nền tảng là ưu tiên hàng đầu
+- 🔹 Để chỗ cho tự động hóa kích hoạt skill và testing trong tương lai
+
+#### Từ [`knowns-dev/knowns`](https://github.com/knowns-dev/knowns)
+
+- 🔹 Tách skill instruction khỏi kiến thức bền vững
+- 🔹 Giữ một nguồn sự thật duy nhất và sync file platform-specific từ đó
+- 🔹 Hỗ trợ nhiều agent đích mà không viết lại thư viện core
+- 🔹 Để chỗ cho interface machine-readable trong tương lai
+
+### 🏛️ Quyết Định Thiết Kế
+
+1. 📄 Nội dung core dùng Markdown và YAML để repo giữ tính portable
+2. 🎯 Skill mặc định hẹp, giải quyết tốt một vấn đề lặp lại
+3. 📚 Knowledge phân lớp: `global`, `project`, `working`
+4. 📦 File platform được sinh vào `generated/` thay vì sửa tay
+5. ⚙️ Phiên bản đầu dùng shell script đơn giản thay vì build system
+6. ✅ Planning và verification là các pha rõ ràng cho công việc thay đổi code
+
+### 🎯 Phạm Vi Ban Đầu
+
+Phiên bản đầu tập trung vào các pattern có giá trị ngay:
+
+- 🧭 Phân loại request
+- 💡 Làm rõ request mơ hồ thành hướng đi cụ thể
+- 🗺️ Onboard vào repo
+- 🐛 Triage bug
+- 📐 Lập plan trước khi code
+- 🚀 Triển khai feature
+- ✅ Xác minh kết quả trước khi tuyên bố hoàn thành
+- 🔍 Review code
+- 📝 Cập nhật docs
+
+### 🔮 Bước Tiếp Theo
+
+Nếu thư viện hữu ích, công việc tiếp theo có thể là:
+
+1. 📋 Thêm skill manifest format dễ parse bằng chương trình
+2. 📦 Sinh platform file phong phú hơn từ metadata và knowledge file được chọn
+3. 🧩 Thêm project-specific pack mở rộng thư viện global
+4. 🔌 Expose thư viện qua MCP server hoặc CLI nhẹ

package/i18n/knowledge-spec.vi.md

@@ -0,0 +1,78 @@
+# 📚 Đặc Tả Knowledge
+
+> 🌐 **[English](../docs/knowledge-spec.md)**
+
+---
+
+### 🎯 Mục Đích
+
+File knowledge lưu ngữ cảnh bền vững giúp cải thiện cách áp dụng skill.
+
+> 🎯 **Skill** giải thích *cách làm việc*.
+> 📚 **Knowledge** giải thích *điều gì quan trọng trong môi trường của bạn*.
+
+### 📂 Các Lớp
+
+#### 🌍 `knowledge/global/`
+
+Dùng cho rule và preference xuyên dự án:
+
+- 🏛️ Nguyên tắc kỹ thuật
+- 🔍 Heuristic review
+- 🐛 Pattern debug
+- ✍️ Phong cách viết
+
+> 🐢 Lớp này thay đổi **chậm**.
+
+#### 📁 `knowledge/project/`
+
+Dùng cho ngữ cảnh riêng dự án:
+
+- 🏗️ Ghi chú kiến trúc
+- ⚙️ Lệnh quan trọng
+- 📏 Convention
+- ⚠️ Rủi ro rollout
+- 📋 Rule domain
+
+> 🔄 Lớp này nên được copy hoặc tùy chỉnh **theo từng dự án**.
+
+#### 📝 `knowledge/working/`
+
+Dùng cho ghi chú tạm thời trong session:
+
+- 🧪 Giả thuyết đang active
+- ⏳ Quyết định tạm thời
+- 📌 Follow-up cần promote sau
+
+> ⚡ Lớp này thay đổi **thường xuyên** và có thể dọn dẹp mạnh tay.
+
+### 📄 Hình Dạng File
+
+File knowledge nên đọc được như Markdown thuần.
+
+**Các section khuyến nghị:**
+
+| Section | Mục đích |
+|---|---|
+| 🎯 Tại sao file này tồn tại | Ngữ cảnh và động lực |
+| 📏 Rule hoặc heuristic | Hướng dẫn hành động |
+| 💡 Ví dụ | Minh họa cụ thể |
+| ⚠️ Điều gì không nên giả định | Rào cản chống lạm dụng |
+
+> Frontmatter là tùy chọn. Bắt đầu đơn giản trừ khi cần tag machine-readable.
+
+### ⬆️ Quy Tắc Promote
+
+Promote một insight lên khi nó có giá trị lặp lại:
+
+| Từ | Đến | Khi nào |
+|---|---|---|
+| 📝 `working` | 📁 `project` | Khi nó quan trọng cho codebase hiện tại ngoài một session |
+| 📁 `project` | 🌍 `global` | Khi pattern giúp ích lặp lại xuyên repo |
+
+### 🚫 Anti-Pattern
+
+- ❌ Trộn ghi chú task-specific vào `global/`
+- ❌ Lưu ghi chú tạm thời dễ bay hơi như sự thật vĩnh viễn
+- ❌ Copy toàn bộ skill instruction vào file knowledge
+- ❌ Để file project trôi xa khỏi codebase thật

package/i18n/research-notes.vi.md

@@ -0,0 +1,99 @@
+# 🔬 Ghi Chú Nghiên Cứu
+
+> 🌐 **[English](../docs/research-notes.md)**
+
+---
+
+### 🎯 Mục Tiêu
+
+Ghi chú này lưu lại các pattern mạnh nhất từ bên ngoài đáng để chuyển thể vào thư viện skill cá nhân.
+
+### 📦 Các Repo Đã Xem Xét
+
+#### 🏛️ [`anthropics/skills`](https://github.com/anthropics/skills)
+
+**Tại sao quan trọng:**
+
+- Ví dụ public sạch về đóng gói skill portable
+- Hợp đồng core cực kỳ đơn giản: skill là folder chứa `SKILL.md`
+- Nhắc nhở tốt rằng skill nên tự chứa và dễ khám phá
+
+**Pattern áp dụng:**
+
+- 🔹 Một skill mỗi folder
+- 🔹 Tên và mô tả rõ ràng
+- 🔹 Example đặt cạnh skill
+
+#### ⚡ [`obra/superpowers`](https://github.com/obra/superpowers)
+
+**Tại sao quan trọng:**
+
+- Ví dụ public mạnh nhất về workflow phân phối phần mềm dựa trên skill
+- Giữ brainstorm, plan, execution, review, verification thành các bước riêng
+- Coi skill triggering và chuyển tiếp workflow là vấn đề thiết kế, không phải ngẫu nhiên
+
+**Pattern áp dụng:**
+
+- 🔹 Giai đoạn `brainstorming` rõ ràng cho request chưa rõ
+- 🔹 Giai đoạn `planning` rõ ràng trước thay đổi code non-trivial
+- 🔹 Cổng `verification-before-completion` rõ ràng
+
+#### 🧩 [`affaan-m/everything-claude-code`](https://github.com/affaan-m/everything-claude-code)
+
+**Tại sao quan trọng:**
+
+- Cho thấy hệ sinh thái skill lớn có thể phát triển thành các lớp: skill, rule, memory, hook, adapter
+- Thể hiện kỷ luật đóng gói đa nền tảng mạnh
+- Coi nghiên cứu, verification, và tiến hóa skill là mối quan tâm hàng đầu
+
+**Pattern áp dụng:**
+
+- 🔹 Tách biệt `skills/`, `knowledge/`, và `adapters/`
+- 🔹 Chỗ cho rule always-on và output platform phong phú hơn trong tương lai
+- 🔹 Tập trung vào hướng dẫn vận hành tái sử dụng thay vì prompt một lần
+
+#### 🗃️ [`knowns-dev/knowns`](https://github.com/knowns-dev/knowns)
+
+**Tại sao quan trọng:**
+
+- Ví dụ mạnh về tách ngữ cảnh và memory khỏi skill instruction
+- Mô hình tốt để sinh file hướng dẫn platform từ một nguồn
+
+**Pattern áp dụng:**
+
+- 🔹 Ghi chú bền vững ở trong `knowledge/`
+- 🔹 File platform được sinh thay vì phân kỳ thủ công
+
+#### 📦 [`hoangnb24/skills`](https://github.com/hoangnb24/skills)
+
+**Tại sao quan trọng:**
+
+- Thiết kế skill workflow-first với router quyết định load gì tiếp theo
+- Output contract rõ ràng và reference đặt cạnh mỗi skill
+
+**Pattern áp dụng:**
+
+- 🔹 Router skill (`using-skills`) là điểm vào
+- 🔹 Output template trong `references/`
+- 🔹 Related skills graph cho điều hướng
+
+### 🏆 Pattern Được Xếp Hạng
+
+| # | Pattern |
+|---|---|
+| 1️⃣ | Tách brainstorming khỏi planning khi request mơ hồ |
+| 2️⃣ | Tách planning khỏi execution cho thay đổi non-trivial |
+| 3️⃣ | Yêu cầu bằng chứng verification trước khi tuyên bố hoàn thành |
+| 4️⃣ | Giữ skill portable và tự chứa |
+| 5️⃣ | Giữ knowledge tách biệt khỏi workflow |
+| 6️⃣ | Sinh adapter output từ một nguồn sự thật duy nhất |
+
+### ⏳ Pattern Hoãn Lại
+
+- 📦 Đóng gói plugin đầy đủ
+- ⚙️ Hook runtime và tự động hóa
+- 📋 Skill manifest machine-readable
+- 🧪 Test kích hoạt skill
+- 🔌 MCP hoặc CLI bridge
+
+> 💡 Đây là nâng cấp tốt trong tương lai, nhưng cố tình ngoài phạm vi phiên bản nhẹ hiện tại.

package/i18n/skill-spec.vi.md

@@ -0,0 +1,107 @@
+# 🎯 Đặc Tả Skill
+
+> 🌐 **[English](../docs/skill-spec.md)**
+
+---
+
+### 📁 Bố Cục Bắt Buộc
+
+Mỗi skill nằm trong thư mục riêng dưới `skills/`.
+
+```text
+skills/<ten-skill>/
+├─ 📄 meta.yaml
+├─ 📖 SKILL.md
+├─ 💡 examples.md
+└─ 📂 references/
+   └─ <file-ho-tro>.md
+```
+
+### 📄 File Bắt Buộc
+
+#### `meta.yaml`
+
+Dùng cho metadata ổn định mà script hoặc tooling tương lai có thể đọc.
+
+**Trường bắt buộc:**
+
+| Key | Mục đích |
+|---|---|
+| `name` | Định danh skill |
+| `version` | Phiên bản semantic |
+| `category` | Danh mục skill |
+| `summary` | Mô tả một dòng |
+
+**Trường khuyến nghị:**
+
+| Key | Mục đích |
+|---|---|
+| `triggers` | Khi nào kích hoạt |
+| `inputs` | Skill cần gì |
+| `outputs` | Skill tạo ra gì |
+| `constraints` | Rào cản |
+| `related_skills` | Skill liên quan |
+
+#### `SKILL.md`
+
+File hướng dẫn chính. Giữ tập trung và hướng hành động.
+
+**Các section khuyến nghị:**
+
+- 🎯 Mục đích
+- ⏰ Khi nào dùng
+- 🔄 Workflow
+- 📋 Output format
+- 🚩 Red flag
+- ✅ Done criteria
+
+**Khuyến nghị mạnh khi liên quan:**
+
+- 🧭 Quy tắc kích hoạt hoặc gợi ý routing
+- ✅ Cổng verification
+- ➡️ Handoff sang skill tiếp theo
+
+#### `examples.md`
+
+Cho ít nhất một input thực tế và phong cách response hoặc hành vi mong đợi.
+
+#### `references/`
+
+Dùng cho artifact hỗ trợ:
+
+- 📋 Output template
+- ☑️ Checklist
+- 📊 Rubric
+- 🌳 Cây quyết định
+
+> ⚠️ Không chuyển workflow chính vào `references/`. Hành vi chính phải ở trong `SKILL.md`.
+
+### ✍️ Quy Tắc Viết
+
+- 🔹 Giữ skill đủ hẹp để agent có thể quyết định khi nào dùng
+- 🔹 Tối ưu cho tái sử dụng, không phải cho chi tiết dự án một lần
+- 🔹 Ưu tiên hướng dẫn portable hơn cú pháp vendor-specific
+- 🔹 Tránh giả định ngầm về tool, framework, hay tên thư mục
+- 🔹 Hỏi một câu ngắn khi cần thay vì viết xung quanh sự mơ hồ
+- 🔹 Nếu skill thay đổi code hoặc trạng thái task, nêu rõ bằng chứng nào tính là hoàn thành
+
+### ✅ Ngưỡng Chất Lượng
+
+Một skill đủ tốt để giữ khi:
+
+| | Tiêu chí |
+|---|---|
+| 🎯 | Có trigger rõ ràng |
+| 🔄 | Có workflow lặp lại được |
+| 📋 | Cho output shape ổn định |
+| 🛡️ | Giúp agent tránh failure mode phổ biến |
+| 💡 | Có example thực tế |
+| ➡️ | Làm rõ bước tiếp theo cần làm gì |
+
+### 🚫 Anti-Pattern
+
+- ❌ Skill cố giải quyết mọi task cùng lúc
+- ❌ Prompt mơ hồ kiểu "hãy là kỹ sư giỏi"
+- ❌ Lý thuyết dài mà không có bước hành động
+- ❌ Giả định cứng về một nền tảng agent
+- ❌ Nhúng secret, token cá nhân, hay đường dẫn máy

package/knowledge/README.md

@@ -0,0 +1,7 @@
+# Knowledge Layer
+
+This directory stores reusable context that helps skills perform better.
+
+- `global/` is for cross-project principles and heuristics.
+- `project/` is for repo-specific notes that should travel with a project.
+- `working/` is for temporary session notes that may later be promoted.

package/knowledge/global/debugging-patterns.md

@@ -0,0 +1,20 @@
+# Debugging Patterns
+
+## Why This Exists
+
+These notes capture a repeatable way to debug without thrashing.
+
+## Patterns
+
+- Restate the symptom before touching the code.
+- Reproduce the issue if possible.
+- Narrow the code path before editing multiple modules.
+- Separate evidence from hypothesis.
+- Prefer one confirming experiment over many speculative changes.
+- Add regression coverage once the cause is understood.
+
+## What Should Not Be Assumed
+
+- that the stack trace names the real root cause
+- that the latest changed file is the only relevant area
+- that a flaky issue can be solved by adding retries everywhere

package/knowledge/global/engineering-principles.md

@@ -0,0 +1,23 @@
+# Engineering Principles
+
+## Why This Exists
+
+These notes capture stable preferences for how work should be done across projects.
+
+## Principles
+
+- Read the code before proposing structure changes.
+- Prefer the smallest correct change over a broad rewrite.
+- Reuse existing patterns unless they are clearly broken.
+- Refine vague requests before pretending they are implementation-ready.
+- Ask one short blocking question instead of guessing on critical behavior.
+- Verify important claims with code, tests, or commands.
+- Do not claim completion without fresh evidence.
+- Do not add compatibility layers unless there is a concrete need.
+- Do not revert or overwrite user changes unless explicitly asked.
+
+## What Should Not Be Assumed
+
+- that newer abstractions are automatically better
+- that a missing test means the behavior is unimportant
+- that docs are always up to date

package/knowledge/global/evidence-before-claims.md

@@ -0,0 +1,20 @@
+# Evidence Before Claims
+
+## Why This Exists
+
+Agents often overstate success after editing code. This note exists to stop that pattern.
+
+## Rules
+
+- Do not say a fix works unless the relevant check was run fresh.
+- Do not say tests pass unless the test command actually passed.
+- Do not say a bug is fixed unless the original symptom or regression test was verified.
+- Do not rely on partial checks when the claim requires a broader one.
+- If verification is blocked, say exactly what is blocked and what remains unproven.
+
+## Examples
+
+- Good: `I ran the targeted test and it now passes.`
+- Bad: `This should be fixed now.`
+- Good: `I could not run the full build because dependency installation is missing.`
+- Bad: `Everything looks good.`

package/knowledge/global/review-heuristics.md

@@ -0,0 +1,23 @@
+# Review Heuristics
+
+## Why This Exists
+
+These heuristics help keep reviews focused on risk and user impact.
+
+## Heuristics
+
+- Check whether the change can break existing behavior.
+- Check whether edge cases are now unhandled.
+- Check whether data shape, timing, or ordering assumptions changed.
+- Check whether migrations, flags, or rollout behavior were considered.
+- Check whether tests still prove the intended behavior.
+- Prefer comments that explain impact, not just implementation taste.
+
+## Common Categories
+
+- correctness
+- regression risk
+- data loss or corruption
+- authorization or security
+- performance cliffs
+- missing coverage

package/knowledge/global/skill-triggering-rules.md

@@ -0,0 +1,24 @@
+# Skill Triggering Rules
+
+## Why This Exists
+
+These notes keep the library behavior consistent across agents and sessions.
+
+## Rules
+
+- Start with `using-skills` when the task shape is unclear.
+- Use `brainstorming` when the request is still fuzzy and the user is really asking for a clarified direction.
+- Use `planning` before code changes for multi-file, ambiguous, or higher-risk work.
+- Use `feature-delivery` only after the implementation path is concrete enough to execute.
+- Use `bug-triage` before fixing an issue whose cause is not yet grounded.
+- Use `verification-before-completion` before any strong success claim.
+- Use `code-review` for review requests and post-implementation risk checks.
+- Use `repo-onboarding` when entering an unfamiliar codebase before productive work can begin.
+- Use `docs-writer` for documentation tasks in a repo whose structure is already understood.
+- Use `refactor-safe` for restructuring, extracting, or migrating code without intended behavior change.
+
+## What Should Not Be Assumed
+
+- that every request is ready for implementation immediately
+- that planning is unnecessary just because the task sounds small
+- that code edits themselves prove success

package/knowledge/project/README.md

@@ -0,0 +1,10 @@
+# Project Knowledge
+
+Use this directory for per-project notes such as:
+
+- architecture summaries
+- important commands
+- coding conventions that differ from your defaults
+- domain rules and rollout constraints
+
+Keep these notes tied to the real project and update them when the code changes.

package/knowledge/working/README.md

@@ -0,0 +1,10 @@
+# Working Knowledge
+
+Use this directory for temporary notes that matter during active work, for example:
+
+- current hypotheses
+- unresolved questions
+- temporary decision logs
+- follow-up items to promote later
+
+Delete or promote these notes regularly so this layer stays useful.

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@anionzo/skill",
+  "version": "1.1.0",
+  "description": "Personal AI Skill Library — vendor-neutral, multi-agent skill library for AI-powered software engineering",
+  "scripts": {
+    "validate": "bash scripts/validate-skills",
+    "sync": "bash scripts/sync-platform-files",
+    "postinstall": "echo \"\\n🧠 @anionzo/skill installed successfully!\\n\\n📁 Skills:     node_modules/@anionzo/skill/skills/\\n📚 Knowledge:  node_modules/@anionzo/skill/knowledge/\\n📄 Docs:       node_modules/@anionzo/skill/docs/\\n🌐 i18n:       node_modules/@anionzo/skill/i18n/\\n\\n🔌 To use: copy generated/ output to your project\\n   bash node_modules/@anionzo/skill/scripts/sync-platform-files\\n\""
+  },
+  "files": [
+    "skills/",
+    "knowledge/",
+    "docs/",
+    "i18n/",
+    "adapters/",
+    "templates/",
+    "scripts/",
+    "CONTRIBUTING.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anionzo/skill.git"
+  },
+  "keywords": [
+    "ai",
+    "skills",
+    "agent",
+    "claude",
+    "opencode",
+    "gemini",
+    "copilot",
+    "coding-agent",
+    "workflow"
+  ],
+  "author": "Mai Trung Tiến",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/anionzo/skill/issues"
+  },
+  "homepage": "https://github.com/anionzo/skill#readme"
+}

package/scripts/sync-platform-files

@@ -0,0 +1,73 @@
+#!/usr/bin/env sh
+
+set -eu
+
+ROOT=$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)
+OUT=${1:-"$ROOT/generated"}
+CATALOG_FILE="$OUT/.skill-catalog"
+
+mkdir -p "$OUT"
+
+build_catalog() {
+  : > "$CATALOG_FILE"
+
+  for meta in "$ROOT"/skills/*/meta.yaml; do
+    [ -f "$meta" ] || continue
+
+    name=$(sed -n 's/^name:[[:space:]]*//p' "$meta" | sed -n '1p')
+    summary=$(sed -n 's/^summary:[[:space:]]*//p' "$meta" | sed -n '1p')
+
+    printf '%s|%s\n' "$name" "$summary" >> "$CATALOG_FILE"
+  done
+}
+
+write_file() {
+  title=$1
+  target=$2
+
+  {
+    printf '<!-- Generated by scripts/sync-platform-files -->\n'
+    printf '# %s\n\n' "$title"
+    printf 'Start with `skills/using-skills/SKILL.md` when the task shape is unclear. Use one primary skill at a time, then pull in the smallest amount of supporting knowledge needed.\n\n'
+
+    printf '## Core Files\n\n'
+    printf -- '- `skills/using-skills/SKILL.md`\n'
+    printf -- '- `knowledge/global/engineering-principles.md`\n'
+    printf -- '- `knowledge/global/review-heuristics.md`\n'
+    printf -- '- `knowledge/global/debugging-patterns.md`\n'
+    printf -- '- `knowledge/global/evidence-before-claims.md`\n'
+    printf -- '- `knowledge/global/skill-triggering-rules.md`\n'
+    printf -- '- `docs/skill-spec.md`\n\n'
+
+    printf '## Working Rules\n\n'
+    printf -- '- Prefer the smallest correct change.\n'
+    printf -- '- Read the repo and nearby patterns before editing.\n'
+    printf -- '- Ask only the shortest blocking question when a decision is missing.\n'
+    printf -- '- Verify important claims with code, tests, or commands when possible.\n'
+    printf -- '- Keep summaries concise and grounded in files you inspected.\n\n'
+
+    printf '## Skill Catalog\n\n'
+    while IFS='|' read -r name summary; do
+      [ -n "$name" ] || continue
+      printf -- '- `%s`: %s\n' "$name" "$summary"
+    done < "$CATALOG_FILE"
+
+    printf '\n## Suggested Flow\n\n'
+    printf '1. Route with `using-skills` when unsure.\n'
+    printf '2. Load one primary skill that matches the current task.\n'
+    printf '3. Pull in `knowledge/project/` notes when working inside a real project.\n'
+    printf '4. Verify the outcome before declaring the work complete.\n'
+  } > "$target"
+}
+
+build_catalog
+
+write_file "Claude Code Instructions" "$OUT/CLAUDE.md"
+write_file "OpenCode Instructions" "$OUT/OPENCODE.md"
+write_file "Gemini Instructions" "$OUT/GEMINI.md"
+write_file "Generic Agent Instructions" "$OUT/AGENTS.md"
+write_file "GitHub Copilot Instructions" "$OUT/copilot-instructions.md"
+
+rm -f "$CATALOG_FILE"
+
+printf 'Generated platform files in %s\n' "$OUT"