ai-developer-skill-os 1.0.0

package/skills/engineering/bug-fix/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: bug-fix
+description: >-
+  Chẩn đoán và sửa lỗi an toàn. Tái hiện lỗi, tìm nguyên nhân gốc rễ và áp dụng bản sửa lỗi tối thiểu, có kiểm chứng.
+version: 2.0.0
+category: engineering
+tags: [bug, fix, debug, root-cause, regression]
+platforms: [antigravity, claude-code, kilo-code, cursor, windsurf]
+---
+
+# Bug Fix — Diagnose & Repair
+
+> **Language rule:**
+> Use **English** for: code, identifiers, error messages, file paths, technical labels.
+> Use **the user's language** for: explanations, questions, and fix summaries.
+
+---
+
+## Trigger
+
+Activate this skill when:
+- User reports a specific bug with a stack trace, error message, or behavior description
+- A test is failing
+- The app crashes or hangs
+- A regression occurred after a code change
+- User says "it's broken", "this doesn't work", "I'm getting an error"
+
+**Not this skill** → Use `project-audit` if the problem is unknown and needs discovery first.
+
+---
+
+## Scope
+
+- ✅ Reproduce the reported bug
+- ✅ Identify the root cause (not just the symptom)
+- ✅ Apply a minimal, targeted fix
+- ✅ Verify the fix with evidence (tests, logs, comparison)
+- ✅ Prevent recurrence with guards or tests
+
+---
+
+## Non-goals
+
+- ❌ Do NOT refactor code outside the buggy area
+- ❌ Do NOT change public APIs unless the bug requires it
+- ❌ Do NOT silence errors with empty `try/catch` or blind `?.` / `!`
+- ❌ Do NOT change formatting or unrelated code
+- ❌ Do NOT mark as done without verifying the fix
+
+---
+
+## Severity Levels
+
+| Level | Meaning |
+|-------|---------|
+| P0 | Production down, data loss, security breach |
+| P1 | Core feature broken, blocking users |
+| P2 | Non-critical feature broken, workaround exists |
+| P3 | Edge case, cosmetic, minor annoyance |
+
+---
+
+## Workflow
+
+### Phase 1 — Triage & Understand
+
+Before touching code, gather:
+- What is the symptom? (error message, wrong behavior, crash)
+- What is the expected behavior?
+- How to reproduce? (steps, conditions, environment)
+- What changed recently? (git log, deployment, dependency update)
+- What is the severity and impact scope?
+
+If critical information is missing → ask before proceeding.
+
+---
+
+### Phase 2 — Reproduce the Issue
+
+1. Write a failing test or script that triggers the bug
+2. Confirm the bug is consistently reproducible
+3. For intermittent bugs → identify timing, data, or environment conditions
+4. Document the exact reproduction steps
+
+> Rule: **Never skip reproduction.** A fix without a repro is a guess.
+
+---
+
+### Phase 3 — Localize the Problem
+
+1. Read the stack trace top-down, following frames inside project code
+2. Use logs, breakpoints, or `git blame` / `git bisect` to narrow scope
+3. Identify the exact file and line where the failure originates
+4. Trace the data flow that leads to the failure
+
+---
+
+### Phase 4 — Root Cause Analysis
+
+Answer: *Why does this happen? What condition triggers it?*
+
+Common root cause categories:
+- Logic error (wrong condition, wrong operator)
+- Off-by-one or boundary case
+- Null / undefined / missing data
+- Async timing or race condition
+- Type mismatch
+- Stale state or stale closure
+- Config or environment issue
+- API contract change
+- Dependency version change
+
+Use 5 Whys: keep asking "why" until you reach the actual cause, not just the symptom.
+
+---
+
+### Phase 5 — Apply the Fix
+
+Rules:
+- Fix the root cause, not the symptom
+- Smallest possible change that fully resolves the issue
+- Keep existing code style, naming, and conventions
+- Handle related edge cases to prevent similar bugs
+- Remove all debug code, console.logs, and temporary patches
+- Do not change public APIs unless strictly required
+
+---
+
+### Phase 6 — Verify the Result
+
+- [ ] The failing test from Phase 2 now passes
+- [ ] Run the related test suite — no new failures
+- [ ] Run lint and type-check — clean
+- [ ] Manually reproduce the original steps — bug is gone
+- [ ] No regressions in adjacent functionality
+
+---
+
+### Phase 7 — Report & Prevent
+
+Summarize and propose prevention:
+- What was the root cause?
+- What was changed and why?
+- Are there similar patterns elsewhere in the codebase?
+- Should a test be added to prevent regression?
+
+---
+
+## Decision Tree
+
+```
+Is the bug reproducible?
+  ├── No  → Isolate timing, data, environment conditions first
+  └── Yes → Is the root cause known?
+              ├── No  → Run Phase 3-4 (localize + analyze)
+              └── Yes → Apply minimal fix → verify → report
+```
+
+```
+Is the fix risky (touches shared code / public API)?
+  ├── Yes → Confirm scope with user before applying
+  └── No  → Apply fix
+```
+
+---
+
+## Output Format
+
+```
+🐛 Bug Report
+─────────────────────────────────────────────────
+Symptom:     [What broke + how to reproduce]
+Root cause:  [Exact file:line — why it happens]
+Severity:    [P0 / P1 / P2 / P3]
+
+🔧 Fix Applied
+─────────────────────────────────────────────────
+Changed:     [File(s) modified]
+Change:      [What was changed and why it's minimal]
+
+✅ Verification
+─────────────────────────────────────────────────
+Tests:       [Test name / command — PASSED]
+Lint/Types:  [Clean / warnings noted]
+Manual:      [Reproduced original steps — bug gone]
+Regression:  [No new failures]
+
+🛡️ Prevention
+─────────────────────────────────────────────────
+Test added:  [Yes / No — reason]
+Similar areas to check: [file or pattern to review]
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Bug was reproduced before fixing
+- [ ] Root cause identified at exact file:line with explanation
+- [ ] Fix is minimal — only changes what's needed
+- [ ] Failing test now passes
+- [ ] Related tests and lint/type-check clean
+- [ ] No debug code left behind
+- [ ] Side effects documented
+- [ ] Prevention strategy noted
+
+---
+
+## Examples
+
+See `examples/` folder.

package/skills/engineering/context-manager/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: context-manager
+description: >-
+  Xác định các file cần thiết, tóm tắt kiến trúc và quản lý bộ nhớ ngữ cảnh để tránh tràn bộ nhớ.
+version: 1.0.0
+category: engineering
+tags: [context, architecture, memory, file-selection, summarization]
+platforms: [antigravity, claude-code, kilo-code, cursor, windsurf]
+---
+
+# Context Manager
+
+> **Language rule:**
+> Use **English** for: file paths, architecture terms, module names, technical labels.
+> Use **the user's language** for: explanations, summaries, and questions.
+
+---
+
+## Trigger
+
+Activate this skill when:
+- Starting work on an unfamiliar or large codebase
+- About to read many files and need to prioritize
+- Context window is at risk of overflowing
+- User asks "where is X", "what does Y do", "how is this project structured"
+- Another skill (e.g. `project-audit`, `frontend-architecture`) needs project context first
+
+---
+
+## Scope
+
+- ✅ Identify which files are relevant to the current task
+- ✅ Summarize project architecture in structured format
+- ✅ Map folder structure to responsibilities
+- ✅ Track what has been read and what still needs reading
+- ✅ Flag context window risks
+- ✅ Maintain a working memory summary for multi-turn sessions
+
+---
+
+## Non-goals
+
+- ❌ Do NOT modify any files
+- ❌ Do NOT fix bugs
+- ❌ Do NOT make architectural decisions
+- ❌ Do NOT read every file blindly — be selective and efficient
+
+---
+
+## Workflow
+
+### Phase 1 — Project Discovery
+
+Read only top-level signals first:
+1. `package.json` / `pyproject.toml` / `Cargo.toml` → detect framework, language, scripts
+2. Root config files → `.env.example`, `tsconfig.json`, `vite.config.ts`, `next.config.js`
+3. Folder structure (1-2 levels deep) → identify key directories
+4. Entry points → `src/index.ts`, `app/`, `pages/`, `main.py`
+
+Produce: **Project Profile** (framework, language, key directories, architecture style)
+
+---
+
+### Phase 2 — Task-Scoped File Selection
+
+Given the current task, identify the minimum relevant set of files:
+
+```
+Task type → Files to read
+─────────────────────────────────────────────────────
+UI work         → components/, pages/, styles/, design system files
+API work        → services/, hooks/, api/, types/
+State work      → store/, context/, hooks/
+Bug fix         → files mentioned in error, related modules
+Architecture    → folder structure, key abstractions
+```
+
+Rules:
+- Read **entry points** before diving into details
+- Prefer **index files** as anchors
+- Skip `node_modules`, `dist`, `build`, `.git`
+- If uncertain which file → check imports, not the file itself
+
+---
+
+### Phase 3 — Architecture Summary
+
+Produce a concise summary:
+
+```
+Project:    [Name / repo]
+Framework:  [React 18 / Next.js 14 / Vue 3 / etc.]
+Language:   [TypeScript / JavaScript / Python]
+Structure:  [Feature-based / Layer-based / Domain-based]
+
+Key directories:
+  src/components/  → Shared UI components
+  src/features/    → Feature modules (collocated)
+  src/services/    → API and data services
+  src/hooks/       → Custom React hooks
+  src/types/       → TypeScript interfaces
+
+State:       [Zustand / Redux / React Query / Pinia]
+HTTP client: [axios instance at src/lib/axios.ts]
+Auth:        [JWT stored in httpOnly cookie]
+```
+
+---
+
+### Phase 4 — Working Memory Maintenance
+
+During multi-turn sessions:
+- Track which files have been read (avoid re-reading)
+- Track decisions made (e.g. "we decided to use feature-based structure")
+- Flag when context is approaching limits
+- Offer to summarize and compress if needed
+
+---
+
+## Decision Tree
+
+```
+Is this a new project / first time seeing this codebase?
+  ├── Yes → Run full Phase 1 + Phase 2 + Phase 3
+  └── No  → Has something changed since last context load?
+              ├── Yes → Re-run Phase 2 for affected area
+              └── No  → Use cached architecture summary
+```
+
+```
+Is context window at risk?
+  ├── Yes → Summarize what's been read, drop low-relevance files
+  └── No  → Continue loading relevant files
+```
+
+---
+
+## Output Format
+
+```
+🗂️  Project Context Loaded
+
+Framework:  [framework]
+Language:   [language]
+Structure:  [style]
+
+Relevant files for this task:
+  📄 [path/to/file.ts]     — [why it's relevant]
+  📄 [path/to/file.ts]     — [why it's relevant]
+
+Architecture summary:
+  [2-4 lines describing how this codebase is organized]
+
+⚠️  Context notes:
+  [Any risks, unknowns, or files that couldn't be read]
+
+✅ Ready. Proceeding with: [next skill or action]
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Framework and language correctly identified
+- [ ] Only task-relevant files selected (no noise)
+- [ ] Architecture summary is accurate and concise
+- [ ] Context window usage is reasonable
+- [ ] Working memory updated for this session
+
+---
+
+## Examples
+
+See `examples/` folder.

package/skills/engineering/git-engineer/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: git-engineer
+description: >-
+  Viết commit message chuẩn Conventional Commits, mô tả Pull Request, Changelog và Release Notes chuyên nghiệp.
+version: 1.0.0
+category: engineering
+tags: [git, commit, pull-request, changelog, release, conventional-commits]
+platforms: [antigravity, claude-code, kilo-code, cursor, windsurf]
+---
+
+# Git Engineer
+
+> **Language rule:**
+> Use **English** for: commit messages, PR titles, changelog entries, branch names, git commands.
+> Use **the user's language** for: explanations, questions, and summaries.
+
+> 📌 **Standard followed:** [Conventional Commits v1.0.0](https://www.conventionalcommits.org/)
+
+---
+
+## Trigger
+
+Activate this skill when:
+- User wants to write a commit message
+- User has finished a feature and needs a PR description
+- User needs to generate a changelog for a release
+- User asks "what should I commit?", "write PR", "release notes"
+- User wants to clean up their git history before merging
+
+---
+
+## Scope
+
+- ✅ Write commit messages (Conventional Commits format)
+- ✅ Suggest logical commit groupings from a set of changes
+- ✅ Write pull request titles and descriptions
+- ✅ Generate CHANGELOG entries from commit history
+- ✅ Write release notes (human-readable)
+- ✅ Suggest branch naming conventions
+- ✅ Review and improve existing commit messages
+
+---
+
+## Non-goals
+
+- ❌ Do NOT run git commands without explicit user approval
+- ❌ Do NOT force-push or rebase without warning
+- ❌ Do NOT create commits that bundle unrelated changes
+- ❌ Do NOT write vague messages like "fix stuff" or "updates"
+
+---
+
+## Conventional Commits Format
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+### Types
+
+| Type | When to use |
+|------|-------------|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `docs` | Documentation only changes |
+| `style` | Formatting, missing semicolons — no logic change |
+| `refactor` | Code restructure without behavior change |
+| `perf` | Performance improvement |
+| `test` | Adding or fixing tests |
+| `build` | Build system or dependency changes |
+| `ci` | CI/CD configuration changes |
+| `chore` | Other changes that don't modify src or test files |
+| `revert` | Reverts a previous commit |
+
+### Breaking Changes
+
+```
+feat!: remove deprecated login endpoint
+
+BREAKING CHANGE: The /auth/login endpoint has been removed.
+Use /auth/v2/login instead.
+```
+
+---
+
+## Workflow
+
+### Phase 1 — Understand the Changes
+
+Review what has changed:
+1. Read the diff or file list provided by the user
+2. Group changes by concern (feature, fix, refactor, docs, etc.)
+3. Identify if changes should be split into multiple commits or kept as one
+4. Note any breaking changes
+
+---
+
+### Phase 2 — Commit Message(s)
+
+For each logical group of changes, write:
+
+**Single commit:**
+```
+feat(auth): add refresh token rotation
+
+Implements automatic refresh token rotation on each use.
+Old tokens are invalidated immediately after use to prevent
+replay attacks.
+
+Closes #142
+```
+
+**Multiple commits (if changes should be split):**
+```
+refactor(api): extract axios instance to lib/axios.ts
+
+No behavior change — prepares for interceptor configuration.
+
+---
+
+feat(api): add request retry interceptor
+
+Automatically retries failed requests up to 3 times with
+exponential backoff. Skips retry for 4xx errors.
+```
+
+**Rules:**
+- Subject line: ≤72 characters, imperative mood ("add" not "added")
+- Body: explain *why*, not *what* (the diff shows what)
+- Reference issues: `Closes #123`, `Fixes #456`, `Refs #789`
+
+---
+
+### Phase 3 — Pull Request Description
+
+Structure:
+```markdown
+## Summary
+[1-3 sentences describing what this PR does and why]
+
+## Changes
+- [Specific change 1]
+- [Specific change 2]
+- [Specific change 3]
+
+## Testing
+- [ ] Unit tests pass
+- [ ] Manual testing: [describe what you tested]
+- [ ] [Other relevant checks]
+
+## Breaking Changes
+[None | Description of breaking change and migration path]
+
+## Screenshots / Demo
+[If UI changes — attach before/after screenshots]
+
+## Related Issues
+Closes #[issue number]
+```
+
+---
+
+### Phase 4 — Changelog Entry
+
+Follow [Keep a Changelog](https://keepachangelog.com/) format:
+
+```markdown
+## [1.2.0] - 2026-07-01
+
+### Added
+- Refresh token rotation for improved security (#142)
+- Retry interceptor with exponential backoff (#138)
+
+### Changed
+- Extracted axios instance to `src/lib/axios.ts` for cleaner configuration
+
+### Fixed
+- Fixed race condition in useUserData hook causing stale state (#135)
+- Resolved memory leak when component unmounts during fetch (#133)
+
+### Deprecated
+- `GET /api/v1/users` — use `GET /api/v2/users` instead (removes in v2.0)
+
+### Removed
+- Removed legacy `moment.js` dependency — migrated to `date-fns`
+
+### Security
+- Updated `package-x` from 2.1.0 to 2.1.4 (CVE-2026-XXXX)
+```
+
+---
+
+### Phase 5 — Release Notes (Human-Readable)
+
+For non-technical stakeholders:
+
+```markdown
+# Release v1.2.0 — Security & Stability
+
+## What's new
+
+**Better security**: Login sessions are now more secure with automatic
+token rotation. Each time you use the app, your session is refreshed
+automatically.
+
+**More reliable**: The app now automatically retries failed requests,
+so temporary network issues won't interrupt your workflow.
+
+## Bug fixes
+
+- Fixed an issue where user data could appear stale after navigating
+- Fixed a rare crash that occurred when closing the app during data loading
+
+## Under the hood
+
+We've updated several internal libraries to keep the app fast, secure,
+and maintainable.
+```
+
+---
+
+## Decision Tree
+
+```
+What does the user need?
+  ├── Commit message     → Phase 2 only
+  ├── PR description     → Phase 3 (+ Phase 2 if commits not written)
+  ├── Changelog entry    → Phase 4 (from commit list or diff)
+  └── Full release       → Phase 2 + Phase 4 + Phase 5
+
+Should changes be split into multiple commits?
+  ├── Changes are unrelated → Yes — split by concern
+  ├── Changes form one atomic feature → No — single commit
+  └── Unsure → Ask user
+
+Is there a breaking change?
+  ├── Yes → Use `feat!` or `fix!` type + BREAKING CHANGE footer
+  └── No  → Standard type
+```
+
+---
+
+## Branch Naming Convention
+
+```
+feature/short-description       → new features
+fix/short-description           → bug fixes
+refactor/short-description      → refactoring
+chore/dependency-upgrade        → maintenance
+release/v1.2.0                  → release preparation
+hotfix/critical-issue           → urgent production fixes
+```
+
+---
+
+## Output Format
+
+```
+📝 Git Output
+─────────────────────────────────────────────────
+Type:    [commit | PR | changelog | release-notes]
+
+─── Commit Message ───────────────────────────────
+feat(scope): short imperative description
+
+Body explaining why this change was made.
+What problem does it solve?
+
+Closes #123
+
+─── PR Title ─────────────────────────────────────
+feat(scope): short imperative description
+
+─── PR Description ───────────────────────────────
+[Formatted markdown PR body]
+
+─── Changelog ────────────────────────────────────
+[Formatted changelog section]
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Commit type is correct (feat/fix/refactor/etc.)
+- [ ] Subject line ≤72 chars, imperative mood, no period at end
+- [ ] Breaking changes flagged with `!` and `BREAKING CHANGE:` footer
+- [ ] Body explains *why*, not just *what*
+- [ ] Issue references included (`Closes #N`)
+- [ ] PR description covers: summary, changes, testing, breaking changes
+- [ ] Changelog uses correct sections (Added/Changed/Fixed/etc.)
+- [ ] No vague messages ("fix stuff", "updates", "wip")
+
+---
+
+## Examples
+
+See `examples/` folder.