@anionzo/skill 1.1.0

package/adapters/opencode/README.md

@@ -0,0 +1,32 @@
+# OpenCode Adapter
+
+## Purpose
+
+This adapter generates platform-specific instruction files for OpenCode.
+
+## How It Works
+
+1. Run `bash scripts/sync-platform-files` to generate `generated/OPENCODE.md`
+2. Copy the generated file to your project root as `OPENCODE.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/OPENCODE.md OPENCODE.md
+```
+
+## Platform Notes
+
+- OpenCode reads `OPENCODE.md` from the project root automatically
+- Place the file at the root of your repository for best results
+- OpenCode will reference this file at the start of each session
+
+## Source
+
+- Generated from: `generated/OPENCODE.md`
+- Core skill library: `skills/` and `knowledge/`

package/docs/adapter-guide.md

@@ -0,0 +1,62 @@
+# 🔌 Adapter Guide
+
+> 🇻🇳 **[Tiếng Việt](../i18n/adapter-guide.vi.md)**
+
+---
+
+### 🎯 Goal
+
+Adapters make the same skill library usable across multiple agent platforms without rewriting the core content.
+
+> 📁 Core files stay in `skills/` and `knowledge/`.
+> 📦 Platform-specific files are generated into `generated/`.
+
+### 🤖 Current Targets
+
+| | Agent | Output File |
+|---|---|---|
+| 🤖 | Claude Code | `CLAUDE.md` |
+| ⚡ | OpenCode | `OPENCODE.md` |
+| 💎 | Gemini CLI | `GEMINI.md` |
+| 🔧 | Generic agents | `AGENTS.md` |
+| 🐙 | GitHub Copilot | `.github/copilot-instructions.md` |
+
+### 📋 Current Strategy
+
+The first version does not try to fully translate every skill into platform-specific syntax.
+
+Instead it generates concise platform files that:
+
+- 🧭 Point to the core skill router
+- 📚 Point to the most important knowledge files
+- 📋 Include a small skill catalog
+- 📏 State working rules that should be stable across platforms
+
+> 💡 This keeps the delivery artifacts short and reduces drift.
+
+### 🔄 Sync Flow
+
+```bash
+bash scripts/sync-platform-files
+```
+
+This writes fresh files into `generated/`.
+
+### 📋 Copy Flow
+
+After sync, copy the output file to the target repo:
+
+| Source | Target |
+|---|---|
+| `generated/CLAUDE.md` | `CLAUDE.md` |
+| `generated/OPENCODE.md` | `OPENCODE.md` |
+| `generated/GEMINI.md` | `GEMINI.md` |
+| `generated/AGENTS.md` | `AGENTS.md` |
+| `generated/copilot-instructions.md` | `.github/copilot-instructions.md` |
+
+### 🔮 Future Improvements
+
+- 📋 Machine-readable skill manifest
+- 🏷️ Selective sync by tag or platform
+- 📁 Project overlays that add `knowledge/project/` automatically
+- 🔌 MCP or CLI delivery for skill discovery

package/docs/authoring-guide.md

@@ -0,0 +1,69 @@
+# ✍️ Authoring Guide
+
+> 🇻🇳 **[Tiếng Việt](../i18n/authoring-guide.vi.md)**
+
+---
+
+### ➕ Creating A New Skill
+
+```
+Step 1  📁  Create skills/<name>/
+Step 2  📋  Copy files from templates/
+Step 3  📄  Fill in meta.yaml first
+Step 4  📖  Write SKILL.md around a single repeatable job
+Step 5  💡  Add one realistic example
+Step 6  📂  Add one support file in references/ if needed
+Step 7  ✅  Run bash scripts/validate-skills
+```
+
+### 📄 Writing `meta.yaml`
+
+Start by answering four questions:
+
+| # | Question |
+|---|---|
+| 1️⃣ | What is the skill called? |
+| 2️⃣ | What category does it belong to? |
+| 3️⃣ | What problem does it solve? |
+| 4️⃣ | When should an agent reach for it? |
+
+> ⚠️ If the agent would struggle to decide when to load the skill, the metadata is still too vague.
+
+### 📖 Writing `SKILL.md`
+
+Good skill files are **operational**:
+
+- ⏰ Describe when the skill should be loaded
+- 🔢 Give a small number of concrete steps
+- 📋 Define how the result should be reported
+- 🚩 Call out the common mistakes the skill is meant to prevent
+- ➡️ Define whether the skill hands off to another skill or ends the flow
+
+### 💡 Examples
+
+Examples should look like **realistic prompts or tasks**, not abstract descriptions.
+
+Include:
+
+- 🗣️ A representative user request
+- 📋 The intended response shape or chosen workflow
+- 🔑 Any key assumptions that affect routing
+
+### ☑️ Review Checklist
+
+Before keeping a new skill, check that:
+
+| | Check |
+|---|---|
+| 🏷️ | The name is specific |
+| 📝 | The summary is one sentence and still useful |
+| 🔄 | The workflow can be followed without extra private context |
+| 📋 | The output format is consistent |
+| 💡 | The example is realistic |
+| ✅ | The done criteria require evidence, not wishful language |
+
+### ✏️ Editing Existing Skills
+
+When refining a skill, prefer **tightening scope** over adding more branches.
+
+> 💡 If a skill starts handling too many unrelated cases, **split it** into two skills instead of making one file harder to reason about.

package/docs/design-brief.md

@@ -0,0 +1,97 @@
+# 📋 Design Brief
+
+> 🇻🇳 **[Tiếng Việt](../i18n/design-brief.vi.md)**
+
+---
+
+### ❓ Problem
+
+AI workflows often break down for one of two reasons:
+
+- 🔴 The agent does not have a repeatable method for a class of work
+- 🔴 The agent does not have durable context about how the user prefers to work
+
+This repository separates those two concerns.
+
+### 📦 What This Repo Is
+
+A personal operating library with three layers:
+
+| Layer | Purpose |
+|---|---|
+| 🎯 `skills/` | Reusable workflow instructions |
+| 📚 `knowledge/` | Durable notes about principles, heuristics, and project context |
+| 🔌 `adapters/` | Delivery guidance for different agent platforms |
+
+### 🚫 What This Repo Is Not
+
+- ❌ Not a full task manager
+- ❌ Not a plugin runtime
+- ❌ Not a database-backed memory system
+- ❌ Not a single-agent hard-coded prompt pack
+
+### 🔍 Upstream Ideas Adopted
+
+#### From [`hoangnb24/skills`](https://github.com/hoangnb24/skills)
+
+- 🔹 Workflow-first skill design
+- 🔹 A router or meta-skill that decides what to load next
+- 🔹 Explicit output contracts
+- 🔹 References and examples stored next to each skill
+
+#### From plan-first coding agents
+
+- 🔹 Separate planning from execution
+- 🔹 Make implementation readiness visible before code changes begin
+- 🔹 Keep plans concrete enough to execute and easy to review
+
+#### From [`obra/superpowers`](https://github.com/obra/superpowers)
+
+- 🔹 Add a brainstorming stage before planning when the request is still fuzzy
+- 🔹 Treat verification as a real gate, not a final afterthought
+- 🔹 Keep skill triggering and workflow transitions explicit
+
+#### From [`affaan-m/everything-claude-code`](https://github.com/affaan-m/everything-claude-code)
+
+- 🔹 Think in layers: skills, stable rules, memory, adapters
+- 🔹 Treat cross-platform support as a first-class concern
+- 🔹 Keep room for future automation around skill activation and testing
+
+#### From [`knowns-dev/knowns`](https://github.com/knowns-dev/knowns)
+
+- 🔹 Separate skill instructions from durable knowledge
+- 🔹 Keep one source of truth and sync platform-specific files from it
+- 🔹 Support multiple target agents without rewriting the core library
+- 🔹 Leave room for a future machine-readable interface
+
+### 🏛️ Design Decisions
+
+1. 📄 Core content lives in Markdown and YAML so the repo stays portable
+2. 🎯 Skills are narrow by default and should solve one repeatable problem well
+3. 📚 Knowledge is layered as `global`, `project`, and `working`
+4. 📦 Platform files are generated into `generated/` instead of edited manually
+5. ⚙️ The first version uses simple shell scripts instead of introducing a build system
+6. ✅ Planning and verification are explicit phases for code-changing work
+
+### 🎯 Initial Scope
+
+The first version focuses on the work patterns most likely to pay off immediately:
+
+- 🧭 Routing requests
+- 💡 Refining rough requests into a workable direction
+- 🗺️ Onboarding into repos
+- 🐛 Triaging bugs
+- 📐 Planning implementation work before code edits
+- 🚀 Delivering features
+- ✅ Verifying outcomes before claiming completion
+- 🔍 Reviewing code
+- 📝 Updating docs
+
+### 🔮 Next Steps
+
+If the library proves useful, the likely follow-up work is:
+
+1. 📋 Add a skill manifest format that is easier to parse programmatically
+2. 📦 Generate richer platform files from metadata and selected knowledge files
+3. 🧩 Add project-specific packs that extend the global library
+4. 🔌 Expose the library through a lightweight MCP server or CLI

package/docs/knowledge-spec.md

@@ -0,0 +1,78 @@
+# 📚 Knowledge Spec
+
+> 🇻🇳 **[Tiếng Việt](../i18n/knowledge-spec.vi.md)**
+
+---
+
+### 🎯 Purpose
+
+Knowledge files store durable context that improves how skills are applied.
+
+> 🎯 **Skills** explain *how to work*.
+> 📚 **Knowledge** explains *what matters in your environment*.
+
+### 📂 Layers
+
+#### 🌍 `knowledge/global/`
+
+Use for cross-project rules and preferences:
+
+- 🏛️ Engineering principles
+- 🔍 Review heuristics
+- 🐛 Debugging patterns
+- ✍️ Writing tone
+
+> 🐢 This layer should change **slowly**.
+
+#### 📁 `knowledge/project/`
+
+Use for project-specific context:
+
+- 🏗️ Architecture notes
+- ⚙️ Important commands
+- 📏 Conventions
+- ⚠️ Rollout risks
+- 📋 Domain rules
+
+> 🔄 This layer should be copied or adapted **per project**.
+
+#### 📝 `knowledge/working/`
+
+Use for session-scoped or temporary notes:
+
+- 🧪 Active hypotheses
+- ⏳ Temporary decisions
+- 📌 Follow-ups to promote later
+
+> ⚡ This layer changes **often** and can be cleaned up aggressively.
+
+### 📄 File Shape
+
+Knowledge files should stay readable as plain Markdown.
+
+**Recommended sections:**
+
+| Section | Purpose |
+|---|---|
+| 🎯 Why this exists | Context and motivation |
+| 📏 Rules or heuristics | Actionable guidelines |
+| 💡 Examples | Concrete illustrations |
+| ⚠️ What should not be assumed | Guard against misuse |
+
+> Frontmatter is optional. Start simple unless you need machine-readable tags.
+
+### ⬆️ Promotion Rules
+
+Promote an insight upward when it has repeated value:
+
+| From | To | When |
+|---|---|---|
+| 📝 `working` | 📁 `project` | When it matters for the current codebase beyond one session |
+| 📁 `project` | 🌍 `global` | When the pattern repeatedly helps across repos |
+
+### 🚫 Anti-Patterns
+
+- ❌ Mixing task-specific notes into `global/`
+- ❌ Storing volatile scratch notes as permanent truth
+- ❌ Copying full skill instructions into knowledge files
+- ❌ Letting project files drift away from the real codebase

package/docs/research-notes.md

@@ -0,0 +1,99 @@
+# 🔬 Research Notes
+
+> 🇻🇳 **[Tiếng Việt](../i18n/research-notes.vi.md)**
+
+---
+
+### 🎯 Goal
+
+This note records the strongest external patterns worth adapting into this personal skill library.
+
+### 📦 Repositories Reviewed
+
+#### 🏛️ [`anthropics/skills`](https://github.com/anthropics/skills)
+
+**Why it matters:**
+
+- Clean public example of portable skill packaging
+- Extremely simple core contract: a skill is a folder with `SKILL.md`
+- Good reminder that skills should stay self-contained and discoverable
+
+**Patterns adopted here:**
+
+- 🔹 One skill per folder
+- 🔹 Clear name and description
+- 🔹 Examples close to the skill itself
+
+#### ⚡ [`obra/superpowers`](https://github.com/obra/superpowers)
+
+**Why it matters:**
+
+- Strongest public example of a skill-driven software delivery workflow
+- Keeps brainstorm, plan, execution, review, and verification as separate steps
+- Treats skill triggering and workflow transitions as design problems, not accidents
+
+**Patterns adopted here:**
+
+- 🔹 Explicit `brainstorming` stage for unclear requests
+- 🔹 Explicit `planning` stage before non-trivial code changes
+- 🔹 Explicit `verification-before-completion` gate
+
+#### 🧩 [`affaan-m/everything-claude-code`](https://github.com/affaan-m/everything-claude-code)
+
+**Why it matters:**
+
+- Shows how a large skill ecosystem can grow into layers: skills, rules, memory, hooks, adapters
+- Demonstrates strong cross-platform packaging discipline
+- Treats research, verification, and skill evolution as first-class concerns
+
+**Patterns adopted here:**
+
+- 🔹 Separation between `skills/`, `knowledge/`, and `adapters/`
+- 🔹 Room for future always-on rules and richer platform output
+- 🔹 Focus on reusable operating guidance instead of one-off prompts
+
+#### 🗃️ [`knowns-dev/knowns`](https://github.com/knowns-dev/knowns)
+
+**Why it matters:**
+
+- Strong example of separating context and memory from skill instructions
+- Good model for generating platform instruction files from one source
+
+**Patterns adopted here:**
+
+- 🔹 Durable notes live in `knowledge/`
+- 🔹 Platform files are generated instead of manually diverging
+
+#### 📦 [`hoangnb24/skills`](https://github.com/hoangnb24/skills)
+
+**Why it matters:**
+
+- Workflow-first skill design with a router that decides what to load next
+- Explicit output contracts and references stored alongside each skill
+
+**Patterns adopted here:**
+
+- 🔹 Router skill (`using-skills`) as the entry point
+- 🔹 Output templates in `references/`
+- 🔹 Related skills graph for navigation
+
+### 🏆 Ranked Patterns To Keep
+
+| # | Pattern |
+|---|---|
+| 1️⃣ | Separate brainstorming from planning when the request is vague |
+| 2️⃣ | Separate planning from execution for non-trivial changes |
+| 3️⃣ | Require verification evidence before completion claims |
+| 4️⃣ | Keep skills portable and self-contained |
+| 5️⃣ | Keep knowledge separate from workflows |
+| 6️⃣ | Generate adapter output from one source of truth |
+
+### ⏳ Patterns Deferred For Later
+
+- 📦 Full plugin packaging
+- ⚙️ Hook runtime and automation
+- 📋 Machine-readable skill manifests
+- 🧪 Skill-triggering tests
+- 🔌 MCP or CLI bridge
+
+> 💡 These are good future upgrades, but they are intentionally out of scope for the current lightweight version.

package/docs/skill-spec.md

@@ -0,0 +1,107 @@
+# 🎯 Skill Spec
+
+> 🇻🇳 **[Tiếng Việt](../i18n/skill-spec.vi.md)**
+
+---
+
+### 📁 Required Layout
+
+Every skill lives in its own directory under `skills/`.
+
+```text
+skills/<skill-name>/
+├─ 📄 meta.yaml
+├─ 📖 SKILL.md
+├─ 💡 examples.md
+└─ 📂 references/
+   └─ <supporting-file>.md
+```
+
+### 📄 Required Files
+
+#### `meta.yaml`
+
+Use this file for stable metadata that scripts or future tooling can read.
+
+**Required keys:**
+
+| Key | Purpose |
+|---|---|
+| `name` | Skill identifier |
+| `version` | Semantic version |
+| `category` | Skill category |
+| `summary` | One-line description |
+
+**Recommended keys:**
+
+| Key | Purpose |
+|---|---|
+| `triggers` | When to activate |
+| `inputs` | What the skill needs |
+| `outputs` | What the skill produces |
+| `constraints` | Guardrails |
+| `related_skills` | Connected skills |
+
+#### `SKILL.md`
+
+The main instruction file. Keep it focused and operational.
+
+**Recommended sections:**
+
+- 🎯 Purpose
+- ⏰ When to use
+- 🔄 Workflow
+- 📋 Output format
+- 🚩 Red flags
+- ✅ Done criteria
+
+**Strongly recommended when relevant:**
+
+- 🧭 Activation rule or routing hint
+- ✅ Verification gate
+- ➡️ Handoff to the next skill
+
+#### `examples.md`
+
+Show at least one realistic input and the expected style of response or behavior.
+
+#### `references/`
+
+Use this for supporting artifacts:
+
+- 📋 Output templates
+- ☑️ Checklists
+- 📊 Rubrics
+- 🌳 Decision trees
+
+> ⚠️ Do not move the main workflow into `references/`. The main behavior should stay in `SKILL.md`.
+
+### ✍️ Authoring Rules
+
+- 🔹 Keep the skill narrow enough that an agent can decide when to use it
+- 🔹 Optimize for reuse, not for one-off project details
+- 🔹 Prefer portable instructions over vendor-specific syntax
+- 🔹 Avoid hidden assumptions about tools, frameworks, or directory names
+- 🔹 Ask one short blocking question when needed instead of writing around ambiguity
+- 🔹 If the skill changes code or task state, be clear about what evidence counts as done
+
+### ✅ Quality Bar
+
+A skill is good enough to keep when it:
+
+| | Criteria |
+|---|---|
+| 🎯 | Has a clear trigger |
+| 🔄 | Has a repeatable workflow |
+| 📋 | Gives a stable output shape |
+| 🛡️ | Helps the agent avoid a common failure mode |
+| 💡 | Includes an example grounded in reality |
+| ➡️ | Makes it obvious what should happen next |
+
+### 🚫 Anti-Patterns
+
+- ❌ Skills that try to solve every task at once
+- ❌ Vague prompts such as "be a great engineer"
+- ❌ Long theory with no operational steps
+- ❌ Hard-coded assumptions about one agent platform
+- ❌ Embedding secrets, user-specific tokens, or machine paths