@anionzo/skill 1.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,302 @@
+<div align="center">
+
+# 🤝 Contributing Guide
+
+**How to contribute skills, knowledge, and improvements to this library**
+
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat-square&logo=github)](https://github.com/anionzo/skill/pulls)
+[![Skill Spec](https://img.shields.io/badge/read-skill_spec-blue?style=flat-square&logo=bookstack)](docs/skill-spec.md)
+[![Authoring Guide](https://img.shields.io/badge/read-authoring_guide-purple?style=flat-square&logo=pencil)](docs/authoring-guide.md)
+
+---
+
+🇻🇳 **[Tiếng Việt](i18n/CONTRIBUTING.vi.md)**
+
+</div>
+
+---
+
+> 🎯 Thank you for your interest in contributing! This guide covers everything you need to add or improve skills, knowledge files, and tooling in this repo.
+
+### 📋 Table of Contents
+
+| | Section |
+|---|---|
+| 🏁 | [Quick Start](#-quick-start) |
+| ➕ | [Adding a New Skill](#-adding-a-new-skill) |
+| ✏️ | [Editing an Existing Skill](#️-editing-an-existing-skill) |
+| 📚 | [Contributing Knowledge](#-contributing-knowledge) |
+| 🔌 | [Updating Adapters](#-updating-adapters) |
+| ✅ | [Validation & Quality](#-validation--quality) |
+| 📐 | [Style & Conventions](#-style--conventions) |
+| 🔄 | [Pull Request Process](#-pull-request-process) |
+| 🚫 | [What Not to Do](#-what-not-to-do) |
+
+---
+
+### 🏁 Quick Start
+
+```bash
+# 1. Fork and clone the repo
+git clone https://github.com/<your-username>/skill.git
+cd skill
+
+# 2. Create a feature branch
+git branch feat/my-new-skill
+git checkout feat/my-new-skill
+
+# 3. Make your changes (see sections below)
+
+# 4. Validate
+bash scripts/validate-skills
+
+# 5. Generate platform files
+bash scripts/sync-platform-files
+
+# 6. Commit and push
+git add .
+git commit -m "add skill: <skill-name>"
+git push origin feat/my-new-skill
+
+# 7. Open a Pull Request on GitHub
+```
+
+---
+
+### ➕ Adding a New Skill
+
+Every skill lives in its own directory under `skills/`. Follow these steps:
+
+#### Step 1 — Scaffold from template
+
+```bash
+cp -r templates/ skills/<your-skill-name>/
+```
+
+#### Step 2 — Fill in `meta.yaml`
+
+| Key | Required | Description |
+|---|---|---|
+| `name` | ✅ | Skill identifier (kebab-case) |
+| `version` | ✅ | Semantic version (`1.0.0`) |
+| `category` | ✅ | One of: `routing`, `discovery`, `planning`, `implementation`, `debugging`, `review`, `documentation`, `verification` |
+| `summary` | ✅ | One-line English description |
+| `summary_vi` | 🟡 | One-line Vietnamese description |
+| `triggers` | 🟡 | When to activate this skill |
+| `inputs` | 🟡 | What the skill needs |
+| `outputs` | 🟡 | What the skill produces |
+| `constraints` | 🟡 | Guardrails and limits |
+| `related_skills` | 🟡 | Connected skills in the graph |
+
+> ✅ = required &nbsp; 🟡 = recommended
+
+#### Step 3 — Write `SKILL.md`
+
+Follow the structure from the [Skill Spec](docs/skill-spec.md):
+
+```markdown
+# <Skill Name>
+
+## 🎯 Purpose
+## ⏰ When to Use
+## 🔄 Workflow
+## 📋 Output Format
+## 🚩 Red Flags
+## ✅ Done Criteria
+## ➡️ Handoff
+```
+
+> 💡 Keep it **operational** — concrete steps, not abstract theory. See the [Authoring Guide](docs/authoring-guide.md) for detailed writing rules.
+
+#### Step 4 — Add `examples.md`
+
+Include at least one realistic example with:
+
+- 🗣️ A representative user request
+- 📋 The intended response shape or workflow
+- ✅ A completed output example
+
+#### Step 5 — Add references (optional)
+
+Place supporting files in `references/`:
+
+- 📋 Output templates
+- ☑️ Checklists
+- 📊 Rubrics
+- 🌳 Decision trees
+
+#### Step 6 — Wire into the skill graph
+
+Update the `related_skills` field in relevant existing skills' `meta.yaml` files so the router (`using-skills`) can discover your new skill.
+
+#### Step 7 — Validate
+
+```bash
+bash scripts/validate-skills
+```
+
+All skills must pass with **0 FAIL** and **0 WARN**.
+
+---
+
+### ✏️ Editing an Existing Skill
+
+| | Guideline |
+|---|---|
+| 🔹 | Prefer **tightening scope** over adding more branches |
+| 🔹 | If a skill handles too many cases, **split it** into two |
+| 🔹 | Keep the output format stable — downstream skills depend on it |
+| 🔹 | Update `examples.md` if the workflow changes |
+| 🔹 | Bump the `version` in `meta.yaml` |
+
+---
+
+### 📚 Contributing Knowledge
+
+Knowledge files live in `knowledge/global/`. They contain principles, heuristics, and patterns — **not** step-by-step workflows (those belong in skills).
+
+| File | Purpose |
+|---|---|
+| 📐 `engineering-principles.md` | Core coding values |
+| 🔍 `review-heuristics.md` | Code review rules |
+| 🐛 `debugging-patterns.md` | Systematic debugging approaches |
+| 🧠 `skill-triggering-rules.md` | When to load which skill |
+
+When adding or editing knowledge:
+
+- 🔹 Keep entries concise and actionable
+- 🔹 Avoid project-specific details — knowledge should be portable
+- 🔹 Each entry should help an AI agent make better decisions
+
+---
+
+### 🔌 Updating Adapters
+
+Adapter skeletons in `adapters/` define how platform-specific files are generated. If you change the skill catalog or knowledge structure:
+
+```bash
+# Regenerate all platform files
+bash scripts/sync-platform-files
+```
+
+> ⚠️ Never edit files in `generated/` directly — they are overwritten on every sync.
+
+---
+
+### ✅ Validation & Quality
+
+Before submitting any change, run:
+
+```bash
+# 1. Validate all skills
+bash scripts/validate-skills
+
+# 2. Regenerate platform files
+bash scripts/sync-platform-files
+```
+
+#### Quality Checklist
+
+| | Check |
+|---|---|
+| 🏷️ | Skill name is specific and descriptive |
+| 📝 | Summary is one sentence and still useful |
+| 🔄 | Workflow can be followed without private context |
+| 📋 | Output format is consistent |
+| 💡 | Example is realistic and includes completed output |
+| ✅ | Done criteria require evidence, not wishful language |
+| 🔗 | `related_skills` graph is consistent (bidirectional links) |
+| ⚙️ | `validate-skills` passes with 0 FAIL, 0 WARN |
+| 📦 | `sync-platform-files` runs without errors |
+
+---
+
+### 📐 Style & Conventions
+
+| | Convention |
+|---|---|
+| 📁 | Skill directories use **kebab-case** (`feature-delivery`, not `FeatureDelivery`) |
+| 📄 | Skill files: `meta.yaml`, `SKILL.md`, `examples.md`, `references/` |
+| 🌐 | Documentation must be **bilingual** — English in main file, Vietnamese in `i18n/` |
+| 📂 | Vietnamese translations go in `i18n/<filename>.vi.md` |
+| 🔗 | Main file links to `i18n/` translation; translation links back to main file |
+| 🎨 | Use emoji icons, tables, and badges — no plain-text walls |
+| 🔗 | All source repos must be **clickable links** to GitHub |
+| 💬 | Commit messages in **English**, clear and descriptive |
+| 📏 | Keep `SKILL.md` under ~200 lines — split if larger |
+
+---
+
+### 🔄 Pull Request Process
+
+```
+┌──────────────┐     ┌─────────────┐     ┌──────────────┐
+│  Fork & Code │────▶│  Validate   │────▶│  Open PR     │
+│              │     │  & Sync     │     │              │
+└──────────────┘     └─────────────┘     └──────┬───────┘
+                                                │
+                                         ┌──────▼───────┐
+                                         │   Review     │
+                                         │   & Merge    │
+                                         └──────────────┘
+```
+
+#### PR Requirements
+
+| | Requirement |
+|---|---|
+| 1️⃣ | Branch from `main`, target `main` |
+| 2️⃣ | `bash scripts/validate-skills` passes with 0 errors |
+| 3️⃣ | `bash scripts/sync-platform-files` runs cleanly |
+| 4️⃣ | PR title follows format: `add skill: <name>`, `fix: <description>`, or `update: <description>` |
+| 5️⃣ | PR description explains **what** changed and **why** |
+| 6️⃣ | No secrets, tokens, or machine-specific paths |
+| 7️⃣ | No changes to `generated/` (it is gitignored) |
+
+---
+
+### 📦 Publishing a Release
+
+The package is published to [npm](https://www.npmjs.com/package/@anionzo/skill) via a GitHub Actions workflow.
+
+#### To publish a new version:
+
+```bash
+# 1. Bump the version in package.json
+npm version patch   # 1.0.0 → 1.0.1
+# or
+npm version minor   # 1.0.0 → 1.1.0
+# or
+npm version major   # 1.0.0 → 2.0.0
+
+# 2. Push the version tag
+git push origin main --tags
+
+# 3. Create a GitHub Release (triggers publish workflow)
+gh release create v1.0.1 --generate-notes
+```
+
+> 💡 The workflow (`.github/workflows/publish.yml`) runs validation, generates platform files, and publishes to npm automatically.
+
+---
+
+### 🚫 What Not to Do
+
+| | Anti-Pattern |
+|---|---|
+| ❌ | Commit files in `generated/` — they are auto-generated |
+| ❌ | Create skills that try to handle every possible case |
+| ❌ | Write vague prompts like "be a great engineer" |
+| ❌ | Embed secrets, tokens, or local file paths |
+| ❌ | Hard-code assumptions about a specific AI agent |
+| ❌ | Edit platform files directly instead of editing adapters |
+| ❌ | Skip validation before opening a PR |
+| ❌ | Write English-only docs (bilingual is required) |
+
+---
+
+<div align="center">
+
+**Built with 🤝 for collaborative AI skill development**
+
+</div>

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mai Trung Tiến
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,209 @@
+<div align="center">
+
+# 🧠 Personal AI Skill Library
+
+**A vendor-neutral, multi-agent skill library for AI-powered software engineering**
+
+[![Skills](https://img.shields.io/badge/skills-10-blue?style=flat-square&logo=bookstack)](skills/)
+[![Knowledge](https://img.shields.io/badge/knowledge-5_files-green?style=flat-square&logo=readme)](knowledge/)
+[![Platforms](https://img.shields.io/badge/platforms-5_agents-purple?style=flat-square&logo=robot-framework)](adapters/)
+[![License](https://img.shields.io/badge/license-MIT-yellow?style=flat-square)](LICENSE)
+[![Contributing](https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat-square&logo=github)](CONTRIBUTING.md)
+[![npm](https://img.shields.io/npm/v/@anionzo/skill?style=flat-square&logo=npm&color=crimson)](https://www.npmjs.com/package/@anionzo/skill)
+
+---
+
+🇻🇳 **[Tiếng Việt](i18n/README.vi.md)**
+
+</div>
+
+---
+
+> 🎯 Keep repeatable AI workflows in one place. Separate skills from knowledge. Work across any agent.
+
+This repo is intentionally lighter than a full workflow product. It borrows the **workflow-first** mindset from `hoangnb24/skills`, the **plan-first** behavior from modern coding agents like OpenCode, and the **multi-platform** approach from `knowns-dev/knowns` — then turns them into a practical personal library.
+
+### 🏗️ Design Goals
+
+| | Goal |
+|---|---|
+| 🔹 | Skills are small, specific, and reusable |
+| 🔹 | Knowledge is stored separately from skills |
+| 🔹 | Adapters are generated from one source — not hand-maintained |
+| 🔹 | Works without any custom plugin runtime |
+
+### 📁 Repository Layout
+
+```
+.
+├─ 📄 docs/                 → Specs, authoring rules, design decisions
+├─ 🎯 skills/               → Reusable skill definitions
+├─ 📚 knowledge/            → Global, project, and working knowledge
+├─ 📋 templates/            → Starting points for new skills
+├─ 🔌 adapters/             → Platform-specific guidance
+├─ ⚙️ scripts/              → Validation and sync helpers
+├─ 🌐 i18n/                 → Vietnamese translations
+└─ 📦 generated/            → Auto-generated output (gitignored)
+```
+
+### 🎯 Skill Catalog
+
+| | Skill | Purpose |
+|---|---|---|
+| 🧭 | `using-skills` | Route a request to the right skill and working mode |
+| 💡 | `brainstorming` | Refine rough ideas into a concrete direction before planning |
+| 🗺️ | `repo-onboarding` | Understand an unfamiliar codebase before acting |
+| 📐 | `planning` | Turn a request into an execution-ready plan |
+| 🚀 | `feature-delivery` | Implement a feature with minimal, repo-aligned change |
+| 🐛 | `bug-triage` | Investigate errors, regressions, and unclear failures |
+| ♻️ | `refactor-safe` | Restructure code without changing behavior |
+| ✅ | `verification-before-completion` | Require fresh evidence before claiming done |
+| 🔍 | `code-review` | Review diffs — bugs, regressions, test gaps first |
+| 📝 | `docs-writer` | Update docs from verified source behavior |
+
+### 🔄 Default Workflow
+
+```
+┌─────────────┐     ┌───────────────┐     ┌─────────────────┐
+│ using-skills │────▶│ brainstorming │────▶│ repo-onboarding │
+│   (router)   │     │  (if vague)   │     │  (if new repo)  │
+└──────┬───────┘     └───────┬───────┘     └────────┬────────┘
+       │                     │                      │
+       │                     ▼                      │
+       │              ┌──────────┐                  │
+       └─────────────▶│ planning │◀─────────────────┘
+                      └────┬─────┘
+                           │
+              ┌────────────┼────────────┐
+              ▼            ▼            ▼
+     ┌────────────┐ ┌───────────┐ ┌──────────────┐
+     │  feature-  │ │ bug-triage│ │ refactor-safe│
+     │  delivery  │ │           │ │              │
+     └─────┬──────┘ └─────┬─────┘ └──────┬───────┘
+           │              │              │
+           ▼              ▼              ▼
+     ┌─────────────────────────────────────────┐
+     │      verification-before-completion     │
+     └────────────────────┬────────────────────┘
+                          ▼
+                   ┌─────────────┐
+                   │ code-review │
+                   └─────────────┘
+```
+
+### 📖 Research Highlights
+
+This scaffold distills patterns from strong public repos:
+
+| Source | Key Pattern |
+|---|---|
+| 🏛️ [`anthropics/skills`](https://github.com/anthropics/skills) | Minimal, portable skill packaging |
+| ⚡ [`obra/superpowers`](https://github.com/obra/superpowers) | Brainstorm → plan → execute → verify workflow |
+| 🧩 [`affaan-m/everything-claude-code`](https://github.com/affaan-m/everything-claude-code) | Layered model: skills, rules, memory, adapters |
+| 🗃️ [`knowns-dev/knowns`](https://github.com/knowns-dev/knowns) | Separate skills from knowledge; generate platform files |
+| 📦 [`hoangnb24/skills`](https://github.com/hoangnb24/skills) | Workflow-first skill design with router and output contracts |
+
+### 🚀 Quick Start
+
+```bash
+# 1. Understand the repo shape
+cat docs/design-brief.md
+
+# 2. Customize knowledge to your preferences
+vim knowledge/global/engineering-principles.md
+
+# 3. Start working — the router picks the right skill
+cat skills/using-skills/SKILL.md
+
+# 4. Validate your skills
+bash scripts/validate-skills
+
+# 5. Generate platform files
+bash scripts/sync-platform-files
+```
+
+### 📦 Install via npm
+
+> Available on [npm](https://www.npmjs.com/package/@anionzo/skill) — no authentication required
+
+```bash
+# 1. Install the package
+npm install @anionzo/skill
+
+# 2. Copy skills/knowledge to your project
+cp -r node_modules/@anionzo/skill/skills/ ./
+cp -r node_modules/@anionzo/skill/knowledge/ ./
+
+# 3. Generate platform files
+bash node_modules/@anionzo/skill/scripts/sync-platform-files
+
+# 4. Copy the output to your agent
+cp generated/CLAUDE.md ./   # or OPENCODE.md, GEMINI.md, etc.
+```
+
+> 💡 Or clone the repo directly if you prefer editing skills in place.
+
+### 🔌 Agent Integration
+
+> This repo is the **source of truth**. Generated files are delivery artifacts only.
+
+| Agent | Copy from | Copy to |
+|---|---|---|
+| 🤖 Claude Code | `generated/CLAUDE.md` | `CLAUDE.md` |
+| ⚡ OpenCode | `generated/OPENCODE.md` | `OPENCODE.md` |
+| 💎 Gemini CLI | `generated/GEMINI.md` | `GEMINI.md` |
+| 🔧 Generic | `generated/AGENTS.md` | `AGENTS.md` |
+| 🐙 GitHub Copilot | `generated/copilot-instructions.md` | `.github/copilot-instructions.md` |
+
+### ➕ Create A New Skill
+
+```bash
+# 1. Scaffold from template
+cp -r templates/ skills/<new-skill>/
+
+# 2. Edit the files
+vim skills/<new-skill>/meta.yaml
+vim skills/<new-skill>/SKILL.md
+vim skills/<new-skill>/examples.md
+
+# 3. Validate
+bash scripts/validate-skills
+```
+
+### ⚙️ Commands
+
+| Command | Purpose |
+|---|---|
+| `bash scripts/validate-skills` | Check all skills have required files and keys |
+| `bash scripts/sync-platform-files` | Generate platform instruction files |
+
+### 📋 Recommended Customization Order
+
+1. 🥇 `knowledge/global/engineering-principles.md`
+2. 🥈 `knowledge/global/review-heuristics.md`
+3. 🥉 `knowledge/global/debugging-patterns.md`
+4. 🎯 The skill files you use weekly
+5. 🔌 Adapter output for your two most-used agents
+
+### 🤝 Contributing
+
+We welcome contributions! See **[CONTRIBUTING.md](CONTRIBUTING.md)** for:
+
+- ➕ How to add a new skill
+- ✏️ How to edit existing skills
+- 📚 How to contribute knowledge
+- 🔄 Pull request process and conventions
+
+### 📌 Notes
+
+- `generated/` is gitignored — regenerate anytime
+- No plugin runtime or MCP server shipped (yet)
+- Next step: machine-readable manifest or MCP bridge
+
+---
+
+<div align="center">
+
+**Built with ❤️ for AI-assisted software engineering**
+
+</div>

package/adapters/README.md

@@ -0,0 +1,13 @@
+# Adapters
+
+This directory describes where generated instruction files should land for each target platform.
+
+The actual generated files are written to `generated/` by `bash scripts/sync-platform-files`.
+
+Current targets:
+
+- `claude-code/` -> `CLAUDE.md`
+- `opencode/` -> `OPENCODE.md`
+- `gemini/` -> `GEMINI.md`
+- `generic/` -> `AGENTS.md`
+- `copilot/` -> `.github/copilot-instructions.md`

package/adapters/claude-code/README.md

@@ -0,0 +1,32 @@
+# Claude Code Adapter
+
+## Purpose
+
+This adapter generates platform-specific instruction files for Claude Code.
+
+## How It Works
+
+1. Run `bash scripts/sync-platform-files` to generate `generated/CLAUDE.md`
+2. Copy the generated file to your project root as `CLAUDE.md`
+3. The agent will automatically read this file and apply the skill library
+
+## Copy Flow
+
+```bash
+# Generate
+bash scripts/sync-platform-files
+
+# Copy to your project
+cp generated/CLAUDE.md CLAUDE.md
+```
+
+## Platform Notes
+
+- Claude Code reads `CLAUDE.md` from the project root automatically
+- Place the file at the root of your repository for best results
+- Claude Code will reference this file at the start of each session
+
+## Source
+
+- Generated from: `generated/CLAUDE.md`
+- Core skill library: `skills/` and `knowledge/`

package/adapters/copilot/README.md

@@ -0,0 +1,32 @@
+# GitHub Copilot Adapter
+
+## Purpose
+
+This adapter generates platform-specific instruction files for GitHub Copilot.
+
+## How It Works
+
+1. Run `bash scripts/sync-platform-files` to generate `generated/copilot-instructions.md`
+2. Copy the generated file to your project as `.github/copilot-instructions.md`
+3. The agent will automatically read this file and apply the skill library
+
+## Copy Flow
+
+```bash
+# Generate
+bash scripts/sync-platform-files
+
+# Copy to your project
+cp generated/copilot-instructions.md .github/copilot-instructions.md
+```
+
+## Platform Notes
+
+- GitHub Copilot reads `.github/copilot-instructions.md` from the repository
+- The `.github/` directory must exist before copying the file
+- Works with both Copilot Chat and Copilot Workspace
+
+## Source
+
+- Generated from: `generated/copilot-instructions.md`
+- Core skill library: `skills/` and `knowledge/`

package/adapters/gemini/README.md

@@ -0,0 +1,32 @@
+# Gemini CLI Adapter
+
+## Purpose
+
+This adapter generates platform-specific instruction files for Gemini CLI.
+
+## How It Works
+
+1. Run `bash scripts/sync-platform-files` to generate `generated/GEMINI.md`
+2. Copy the generated file to your project root as `GEMINI.md`
+3. The agent will automatically read this file and apply the skill library
+
+## Copy Flow
+
+```bash
+# Generate
+bash scripts/sync-platform-files
+
+# Copy to your project
+cp generated/GEMINI.md GEMINI.md
+```
+
+## Platform Notes
+
+- Gemini CLI reads `GEMINI.md` from the project root automatically
+- Place the file at the root of your repository for best results
+- Gemini CLI will reference this file at the start of each session
+
+## Source
+
+- Generated from: `generated/GEMINI.md`
+- Core skill library: `skills/` and `knowledge/`

package/adapters/generic/README.md

@@ -0,0 +1,32 @@
+# Generic Adapter
+
+## Purpose
+
+This adapter generates platform-specific instruction files for generic AI agents and tooling.
+
+## How It Works
+
+1. Run `bash scripts/sync-platform-files` to generate `generated/AGENTS.md`
+2. Copy the generated file to your project root as `AGENTS.md`
+3. The agent will automatically read this file and apply the skill library
+
+## Copy Flow
+
+```bash
+# Generate
+bash scripts/sync-platform-files
+
+# Copy to your project
+cp generated/AGENTS.md AGENTS.md
+```
+
+## Platform Notes
+
+- `AGENTS.md` is a convention used by various AI agents and tools
+- This adapter is useful for any agent that reads a general repository instruction file
+- Works with custom agents, internal tooling, or any platform without a dedicated adapter
+
+## Source
+
+- Generated from: `generated/AGENTS.md`
+- Core skill library: `skills/` and `knowledge/`