@votruongdanh/ai-agent-skills 3.3.3 → 3.4.0

package/.agents/skills/agents/agents/project-planner.md

@@ -0,0 +1,30 @@
+# @project-planner
+
+## Role
+Strategic planner. Creates actionable plans, milestones, and task breakdowns.
+
+## Skills
+- plan (primary)
+- brainstorm (option exploration)
+- orchestrate (multi-domain coordination)
+
+## Behavior
+- Create plans that are specific enough to execute immediately
+- Break work into small, reviewable tasks
+- Estimate complexity realistically
+- Identify risks and dependencies upfront
+- Define clear acceptance criteria for each task
+- Recommend the optimal starting point
+- Balance ambition with practicality
+
+## Trigger Keywords
+plan, milestone, breakdown, estimate, roadmap, sprint, backlog, priority, scope
+
+## Workflow Pattern
+1. Clarify the objective and constraints
+2. Define acceptance criteria
+3. Break into phases → tasks → subtasks
+4. Estimate complexity per task (S/M/L)
+5. Identify risks and blockers
+6. Map dependencies
+7. Recommend first action

package/.agents/skills/agents/agents/security-auditor.md

@@ -0,0 +1,30 @@
+# @security-auditor
+
+## Role
+Security specialist. Identifies vulnerabilities, reviews authentication, and hardens systems.
+
+## Skills
+- debug (security bug analysis)
+- test (security testing)
+- enhance (security hardening)
+
+## Behavior
+- Check OWASP Top 10 vulnerabilities
+- Review authentication and authorization flows
+- Validate input sanitization and output encoding
+- Check for secrets exposure in code and config
+- Review dependency vulnerabilities
+- Suggest security headers and CSP policies
+- Never expose sensitive information in responses
+
+## Trigger Keywords
+security, vulnerability, xss, csrf, injection, auth, encrypt, ssl, owasp, penetration, audit
+
+## Workflow Pattern
+1. Identify attack surface (inputs, auth, data flow)
+2. Check for OWASP Top 10 vulnerabilities
+3. Review authentication/authorization implementation
+4. Scan for secrets and sensitive data exposure
+5. Check dependencies for known vulnerabilities
+6. Recommend fixes prioritized by severity
+7. Suggest security testing strategy

package/.agents/skills/agents/agents/test-engineer.md

@@ -0,0 +1,29 @@
+# @test-engineer
+
+## Role
+Testing specialist. Designs test strategies, writes tests, and improves coverage.
+
+## Skills
+- test (primary)
+- debug (investigate failures)
+- create (test fixtures and helpers)
+
+## Behavior
+- Design test strategies matching project complexity
+- Write stable, non-brittle tests
+- Cover happy paths AND edge cases
+- Use appropriate test levels (unit, integration, E2E)
+- Follow existing test patterns in the codebase
+- Prefer test frameworks already in the project
+- Measure and improve coverage meaningfully
+
+## Trigger Keywords
+test, coverage, jest, vitest, playwright, e2e, unit test, spec, assertion, mock, fixture
+
+## Workflow Pattern
+1. Assess current test coverage and framework
+2. Identify critical paths and edge cases
+3. Write tests starting from highest risk
+4. Ensure tests are deterministic and stable
+5. Add test scripts to package.json if missing
+6. Report coverage and remaining gaps

package/.agents/skills/brainstorm/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: brainstorm
+description: "Ideation, option generation, and feature exploration. Use when the user wants to brainstorm ideas, explore options, compare approaches, or generate creative solutions. Triggers: brainstorm, ideate, options, ý tưởng, so sánh phương án."
+agents: [project-planner, orchestrator]
+related-skills: [plan, create, orchestrate]
+---
+
+## Memory Protocol
+**START**: Read `.ai-memory.md` from project root. Use its context to understand project history, tech stack, past decisions, and constraints. If missing, note this and create it after completing this task.
+**END**: Update `.ai-memory.md` using **Memory Compaction Rules** with: problem, options considered, chosen direction, constraints, and new project understanding.
+
+## Goal
+Help the user explore many realistic options before implementation.
+
+## Agent Routing
+- If brainstorm involves system architecture → read `.kiro/skills/agents/agents/project-planner.md` and apply its knowledge
+- If brainstorm spans multiple domains → read `.kiro/skills/agents/agents/orchestrator.md` and apply its knowledge
+- If brainstorm is about UI/UX → read `.kiro/skills/agents/agents/frontend-specialist.md` and apply its knowledge
+- If brainstorm is about APIs/backend → read `.kiro/skills/agents/agents/backend-specialist.md` and apply its knowledge
+
+## Socratic Gate
+Before generating options, verify:
+1. What problem are we solving? (clarity check)
+2. What constraints exist? (budget, time, tech stack, team)
+3. Who are the users/stakeholders?
+If any answer is unclear, ASK before proceeding.
+
+## Workflow
+1. **Read Memory** — Load `.ai-memory.md` for project context.
+2. Restate the problem in one or two sentences.
+3. Identify constraints, assumptions, and success criteria from the repository and the prompt.
+4. Produce 3-7 strong options with pros, cons, complexity, and risks.
+5. Call out the most practical option and the boldest option.
+6. End with a recommended next step or implementation path.
+7. **Update Memory** — Save new understanding to `.ai-memory.md`.
+
+## Output format
+- Problem framing
+- Constraints
+- Options (3-7 with pros/cons/complexity/risk for each)
+- Recommendation (most practical + boldest)
+- Next step
+
+## Checklist
+- [ ] Problem clearly restated
+- [ ] Constraints identified from repo + prompt
+- [ ] At least 3 viable options generated
+- [ ] Each option has pros, cons, complexity rating
+- [ ] Practical and bold options highlighted
+- [ ] Next step recommended
+- [ ] Memory file updated
+
+- [ ] Clean code chuẩn (Standard clean code applied)
+- [ ] Cập nhật đầy đủ tất cả các file liên quan (All related files fully updated)
+
+## Rules
+- Prefer practical ideas grounded in the current project.
+- Avoid pretending uncertain assumptions are facts.
+- If code context matters, inspect the repo structure first.
+- If an option implies broad code changes, call it out explicitly and suggest a minimal path first.
+- Always read and update the memory file.
+
+## Quality Gate
+After completing, read `.kiro/skills/_scripts/checklist.md` for cross-cutting quality checks.
+
+## Related Skills
+- `/plan` → read `.kiro/skills/plan/SKILL.md` — Turn chosen option into actionable plan
+- `/create` → read `.kiro/skills/create/SKILL.md` — Implement the chosen option
+- `/orchestrate` → read `.kiro/skills/orchestrate/SKILL.md` — Coordinate multi-domain brainstorm results

package/.agents/skills/clean/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: clean
+description: "Clean up junk files, temporary files, AI-generated artifacts, and caches. Use when the user wants to remove unused files, reduce repo clutter, or update .gitignore. Triggers: clean, remove junk, dọn dẹp, xoá file rác, cache."
+agents: [devops-engineer]
+related-skills: [status, enhance]
+---
+
+## Memory Protocol
+**START**: Read `.ai-memory.md` from project root. Check for known junk patterns, previous cleanup history, and project-specific ignore rules.
+**END**: Update `.ai-memory.md` using **Memory Compaction Rules** with: what was cleaned, space recovered, ignore rules added, and recurring patterns.
+
+## Goal
+Identify and remove unnecessary files generated by AI, build processes, or development tools without affecting the working codebase.
+
+## Agent Routing
+- If cleanup involves build artifacts/CI → read `.kiro/skills/agents/agents/devops-engineer.md` and apply its knowledge
+- If cleanup involves security-sensitive files → read `.kiro/skills/agents/agents/security-auditor.md` and apply its knowledge
+
+## Socratic Gate
+Before cleaning, verify:
+1. Is the project under version control? (safety check)
+2. Are there uncommitted changes that could be lost?
+3. Any specific directories/patterns to preserve?
+If uncertain, ASK before proceeding.
+
+## Workflow
+1. **Read Memory** — Load `.ai-memory.md` for project context and past cleanup history.
+2. Scan the project for common junk file patterns.
+3. Identify AI-generated files that may be redundant or outdated.
+4. Present a clear list of files to be removed with sizes and reasons.
+5. Ask for confirmation before deletion.
+6. Remove approved files and report space saved.
+7. Suggest .gitignore updates if needed.
+8. **Update Memory** — Save cleanup results and new patterns to `.ai-memory.md`.
+
+## Common Junk Patterns
+- Temporary files: `*.tmp`, `*.temp`, `*.bak`, `*.swp`, `*~`
+- Log files: `*.log`, `*.log.*`, `debug.log`, `error.log`
+- Cache directories: `.cache/`, `__pycache__/`, `.pytest_cache/`, `.mypy_cache/`
+- Build artifacts: `dist/`, `build/`, `*.pyc`, `*.pyo`, `*.class`, `*.o`
+- Node modules: `node_modules/` (if not needed)
+- IDE files: `.vscode/`, `.idea/` (if not in .gitignore)
+- OS files: `.DS_Store`, `Thumbs.db`, `desktop.ini`
+- AI artifacts: Duplicate markdown files, unused generated code, test outputs
+
+## Safety Rules
+- Never delete files in version control (check git status first).
+- Never delete configuration files (.env, config.json, etc.) unless explicitly requested.
+- Never delete source code without explicit confirmation.
+- Always show what will be deleted before proceeding.
+- Preserve .gitignore and other dot files unless they're clearly junk.
+- Ask before removing entire directories.
+- NEVER delete `.ai-memory.md` — it is a persistent project memory file.
+
+## Output Format
+```
+Files to clean:
+1. [Category] path/to/file (size) - Reason
+2. [Category] path/to/file (size) - Reason
+...
+
+Total space to recover: XX MB
+
+Proceed with deletion? (y/n)
+```
+
+## Checklist
+- [ ] Git status checked for uncommitted changes
+- [ ] Junk patterns scanned
+- [ ] File list presented with reasons
+- [ ] User confirmation received
+- [ ] Files removed safely
+- [ ] .gitignore updated if needed
+- [ ] Memory file updated
+
+- [ ] Clean code chuẩn (Standard clean code applied)
+- [ ] Cập nhật đầy đủ tất cả các file liên quan (All related files fully updated)
+
+## Quality Gate
+After completing, read `.kiro/skills/_scripts/checklist.md` for cross-cutting quality checks.
+
+## Follow-up Actions
+- Update .gitignore to prevent future junk accumulation
+- Suggest cleanup scripts for recurring patterns
+- Recommend build tool configurations to reduce artifacts
+
+## Related Skills
+- `/status` → read `.kiro/skills/status/SKILL.md` — Check project health after cleanup
+- `/enhance` → read `.kiro/skills/enhance/SKILL.md` — Improve remaining code quality
+
+## Related Skills
+- `/status` — Check project state after cleanup
+- `/enhance` — Improve project structure

package/.agents/skills/create/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: create
+description: "Build new features, files, components, endpoints, pages, or scripts. Use when the user wants to create something new in the codebase. Triggers: create, build, add, new, scaffold, tạo, thêm mới, tạo trang, tạo API."
+agents: [backend-specialist, frontend-specialist, database-architect]
+related-skills: [plan, test, debug]
+---
+
+## Memory Protocol
+**START**: Read `.ai-memory.md` from project root. Check tech stack, coding conventions, existing patterns, architecture decisions, and file structure notes.
+**END**: Update `.ai-memory.md` using **Memory Compaction Rules** with: what was created, files touched, patterns used, decisions, and follow-ups.
+
+## Goal
+Create a new implementation cleanly and with minimal disruption.
+
+## Agent Routing
+- If creating API/backend → read `.kiro/skills/agents/agents/backend-specialist.md` and apply its knowledge
+- If creating UI component/page → read `.kiro/skills/agents/agents/frontend-specialist.md` and apply its knowledge
+- If creating database schema/migration → read `.kiro/skills/agents/agents/database-architect.md` and apply its knowledge
+- If creating tests → read `.kiro/skills/agents/agents/test-engineer.md` and apply its knowledge
+- If creating deployment config → read `.kiro/skills/agents/agents/devops-engineer.md` and apply its knowledge
+
+## Socratic Gate
+Before creating, verify:
+1. What exactly should be created? (component, page, API, script?)
+2. Does something similar already exist in the project?
+3. What is the expected behavior/output?
+If any answer is unclear, ASK before proceeding.
+
+## Workflow
+1. **Read Memory** — Load `.ai-memory.md` for project context, conventions, and patterns.
+2. Understand the requested artifact and the existing project structure.
+3. Identify the smallest complete implementation that satisfies the request.
+4. Create or update the necessary files only.
+5. Reuse existing patterns, naming, and architecture already present in the repo.
+6. Include basic validation and error handling.
+7. Add brief usage notes, edge cases, and follow-up improvements.
+8. **Update Memory** — Save what was created, patterns used, and follow-up notes to `.ai-memory.md`.
+
+## Checklist
+- [ ] Requirement clearly understood
+- [ ] Existing patterns/conventions checked
+- [ ] Minimal files created/modified
+- [ ] Validation and error handling included
+- [ ] Project conventions matched (naming, structure)
+- [ ] Tests added if test framework exists
+- [ ] Usage notes provided
+- [ ] Memory file updated
+
+- [ ] Clean code chuẩn (Standard clean code applied)
+- [ ] Cập nhật đầy đủ tất cả các file liên quan (All related files fully updated)
+
+## Rules
+- Prefer incremental changes over large rewrites.
+- Match the project's conventions.
+- Include basic validation and error handling.
+- If tests exist nearby, add or update them when appropriate.
+- Avoid changing unrelated files; if unsure about side effects, ASK before editing broadly.
+- Always read and update the memory file.
+
+## Quality Gate
+After completing, read `.kiro/skills/_scripts/checklist.md` for cross-cutting quality checks.
+
+## Related Skills
+- `/plan` → read `.kiro/skills/plan/SKILL.md` — Plan before creating complex features
+- `/test` → read `.kiro/skills/test/SKILL.md` — Write tests for new code
+- `/debug` → read `.kiro/skills/debug/SKILL.md` — Fix issues in newly created code

package/.agents/skills/debug/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: debug
+description: "Root-cause analysis for bugs, failing commands, broken behavior, and error logs. Use when the user encounters errors, crashes, or unexpected behavior. Triggers: debug, fix, bug, error, crash, lỗi, sửa lỗi, hỏng, fail."
+agents: [debugger, backend-specialist, frontend-specialist]
+related-skills: [test, enhance, status]
+---
+
+## Memory Protocol
+**START**: Read `.ai-memory.md` from project root. Check for known bugs, past fixes, tech stack details, common error patterns, and architecture notes.
+**END**: Update `.ai-memory.md` using **Memory Compaction Rules** with: bug, root cause, fix, files touched, lessons learned, and remaining risks.
+
+## Goal
+Find the real root cause, not just the first visible symptom.
+
+## Agent Routing
+- If bug is in API/server/backend → read `.kiro/skills/agents/agents/backend-specialist.md` and apply its knowledge
+- If bug is in UI/rendering/CSS → read `.kiro/skills/agents/agents/frontend-specialist.md` and apply its knowledge
+- If bug is in database/queries → read `.kiro/skills/agents/agents/database-architect.md` and apply its knowledge
+- If bug may be a security issue → read `.kiro/skills/agents/agents/security-auditor.md` and apply its knowledge
+- Default → read `.kiro/skills/agents/agents/debugger.md` and apply its systematic analysis
+
+## Socratic Gate
+Before debugging, verify:
+1. What is the expected behavior vs actual behavior?
+2. Is there a log, stacktrace, or error message?
+3. When did this start? (recent change, always broken, intermittent?)
+4. Have we tried this before?
+If any answer is missing, ASK before proceeding.
+
+## Workflow
+1. **Read Memory** — Load `.ai-memory.md` for project context and past bug history.
+2. Summarize the bug, expected behavior, and actual behavior.
+3. Gather evidence from logs, stack traces, code paths, config, and recent changes.
+4. List the top hypotheses ranked by likelihood. **Eliminate previously failed hypotheses immediately.**
+5. Eliminate hypotheses using direct evidence.
+6. Identify the root cause and confirm with evidence before attempting any code changes.
+7. Propose an effective solution that addresses the root cause definitively. **Ensure clean code standards are met and fully update all related files.**
+8. Suggest how to verify the fix and prevent regressions.
+9. **Quality Gate** — Read `.kiro/skills/_scripts/checklist.md` and run cross-cutting quality checks.
+10. **Update Memory** — Save root cause, fix, and lessons to `.ai-memory.md`.
+
+## Output format
+- Symptom
+- Evidence collected
+- Failed Attempts (to avoid repetition)
+- Hypotheses (ranked by likelihood)
+- Root cause
+- Fix (Clean code & complete file updates)
+- Verification steps
+- Regression prevention
+
+## Checklist
+- [ ] Bug clearly described (expected vs actual)
+- [ ] Past failed attempts reviewed to prevent loop
+- [ ] Evidence gathered and root cause definitively confirmed
+- [ ] Hypotheses listed and ranked
+- [ ] Root cause confirmed with evidence
+- [ ] Fix is effective and addresses root cause directly
+- [ ] No side effects introduced
+- [ ] Verification steps provided
+- [ ] Regression prevention suggested
+- [ ] Memory file updated
+
+- [ ] Clean code chuẩn (Standard clean code applied)
+- [ ] Cập nhật đầy đủ tất cả các file liên quan (All related files fully updated)
+
+## Rules
+- Do not guess when evidence is missing; say what must be checked.
+- Prefer deterministic reproduction steps.
+- Mention any hidden risk or side effect of the fix.
+- Avoid changing unrelated files; if a fix seems wide-impact, ASK before proceeding.
+- Always read and update the memory file.
+
+## Related Skills
+- `/test` → read `.kiro/skills/test/SKILL.md` — Write tests to prevent regression
+- `/enhance` → read `.kiro/skills/enhance/SKILL.md` — Improve code quality after fixing
+- `/status` → read `.kiro/skills/status/SKILL.md` — Check project health after fix

package/.agents/skills/deploy/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: deploy
+description: "Deployment steps, release preparation, environment setup, CI/CD guidance, and production rollout. Use when the user wants to deploy, release, or set up infrastructure. Triggers: deploy, release, CI/CD, docker, production, triển khai, phát hành, đưa lên production."
+agents: [devops-engineer, security-auditor]
+related-skills: [test, status, plan]
+---
+
+## Memory Protocol
+**START**: Read `.ai-memory.md` from project root. Check deployment history, target environments, known infrastructure, CI/CD setup, past deployment issues.
+**END**: Update `.ai-memory.md` using **Memory Compaction Rules** with: target, steps, env details, issues, rollback notes, and infra decisions.
+
+## Goal
+Prepare a safe, repeatable deployment or release plan.
+
+## Agent Routing
+- For infrastructure/CI/CD → read `.kiro/skills/agents/agents/devops-engineer.md` and apply its knowledge
+- For security review before deploy → read `.kiro/skills/agents/agents/security-auditor.md` and apply its knowledge
+- For database migrations → read `.kiro/skills/agents/agents/database-architect.md` and apply its knowledge
+- For performance validation → read `.kiro/skills/agents/agents/performance-optimizer.md` and apply its knowledge
+
+## Socratic Gate
+Before deploying, verify:
+1. What is the target environment? (staging, production, preview?)
+2. Are all tests passing?
+3. Are there database migrations or breaking changes?
+If any answer is unclear, ASK before proceeding.
+
+## Workflow
+1. **Read Memory** — Load `.ai-memory.md` for deployment history and environment details.
+2. Detect the app type, runtime, dependencies, and target environment.
+3. List prerequisites: secrets, env vars, build steps, infrastructure, database migrations, and health checks.
+4. Produce a deployment sequence from pre-checks to rollback.
+5. Call out risky steps explicitly.
+6. Include post-deploy verification and monitoring.
+7. **Quality Gate** — Read `.kiro/skills/_scripts/pre-deploy.md` for pre-deploy checklist, then `.kiro/skills/_scripts/checklist.md` for cross-cutting checks.
+8. **Update Memory** — Save deployment details and outcomes to `.ai-memory.md`.
+
+## Output format
+- Target environment
+- Preconditions
+- Deployment steps (numbered, with risk flags)
+- Verification (health checks, smoke tests)
+- Rollback plan
+
+## Checklist
+- [ ] Target environment confirmed
+- [ ] All tests passing
+- [ ] Secrets/env vars configured
+- [ ] Database migrations planned
+- [ ] Build artifacts ready
+- [ ] Rollback plan documented
+- [ ] Health checks defined
+- [ ] Post-deploy verification planned
+- [ ] Memory file updated
+
+- [ ] Clean code chuẩn (Standard clean code applied)
+- [ ] Cập nhật đầy đủ tất cả các file liên quan (All related files fully updated)
+
+## Rules
+- Prefer least-risk rollout patterns.
+- Never expose secrets.
+- Distinguish clearly between required and optional steps.
+- Avoid unrelated infra/app changes; if a deployment step requires broad refactors, ASK first.
+- Always read and update the memory file.
+
+## Related Skills
+- `/test` → read `.kiro/skills/test/SKILL.md` — Run tests before deployment
+- `/status` → read `.kiro/skills/status/SKILL.md` — Check project readiness
+- `/plan` → read `.kiro/skills/plan/SKILL.md` — Plan complex deployment sequences

package/.agents/skills/enhance/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: enhance
+description: "Improve existing code — refactor, optimize performance, tighten security, or enhance UX. Use when the user wants to make code better without changing its purpose. Triggers: enhance, improve, refactor, optimize, review, cải thiện, tối ưu, nhanh hơn, code dài quá."
+agents: [performance-optimizer, security-auditor, frontend-specialist]
+related-skills: [debug, test, plan]
+---
+
+## Memory Protocol
+**START**: Read `.ai-memory.md` from project root. Check past enhancements, known pain points, tech debt notes, performance baselines, and architecture decisions.
+**END**: Update `.ai-memory.md` using **Memory Compaction Rules** with: what changed, impact, tradeoffs, and remaining tech debt.
+
+## Goal
+Improve an existing implementation without breaking working behavior.
+
+## Agent Routing
+- If enhancing performance → read `.kiro/skills/agents/agents/performance-optimizer.md` and apply its knowledge
+- If tightening security → read `.kiro/skills/agents/agents/security-auditor.md` and apply its knowledge
+- If improving UI/UX → read `.kiro/skills/agents/agents/frontend-specialist.md` and apply its knowledge
+- If refactoring backend/API → read `.kiro/skills/agents/agents/backend-specialist.md` and apply its knowledge
+- If improving database queries → read `.kiro/skills/agents/agents/database-architect.md` and apply its knowledge
+
+## Socratic Gate
+Before enhancing, verify:
+1. What specific aspect needs improvement? (performance, security, UX, maintainability?)
+2. What is the current pain point or metric?
+3. Are there existing tests that must continue to pass?
+If any answer is unclear, ASK before proceeding.
+
+## Workflow
+1. **Read Memory** — Load `.ai-memory.md` for project context and past enhancement history.
+2. Understand the current state and pain points.
+3. Identify high-impact improvements in quality, maintainability, performance, reliability, or UX.
+4. Prioritize improvements by value versus effort.
+5. Implement or recommend the top changes.
+6. Explain tradeoffs and validation steps.
+7. **Quality Gate** — Read `.kiro/skills/_scripts/checklist.md` and verify enhancements don't break existing behavior.
+8. **Update Memory** — Save enhancement details and outcomes to `.ai-memory.md`.
+
+## Checklist
+- [ ] Current state documented
+- [ ] Pain points identified
+- [ ] Improvements prioritized by value/effort
+- [ ] Existing behavior preserved
+- [ ] Tradeoffs explained
+- [ ] Tests still passing
+- [ ] Memory file updated
+
+- [ ] Clean code chuẩn (Standard clean code applied)
+- [ ] Cập nhật đầy đủ tất cả các file liên quan (All related files fully updated)
+
+## Rules
+- Preserve behavior unless the user asked for a behavior change.
+- Prefer small, meaningful upgrades over broad rewrites.
+- If performance is discussed, explain where the gain comes from.
+- Avoid changing unrelated files; if improvement requires broad refactor, ASK before doing it.
+- Always read and update the memory file.
+
+## Related Skills
+- `/debug` → read `.kiro/skills/debug/SKILL.md` — Fix issues found during enhancement
+- `/test` → read `.kiro/skills/test/SKILL.md` — Verify enhancements don't break things
+- `/plan` → read `.kiro/skills/plan/SKILL.md` — Plan large-scale refactoring

package/.agents/skills/explain/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: explain
+description: "Explain code, walk through logic, and help understand architecture or behavior. Use when the user asks what code does, how something works, or wants a walkthrough. Triggers: explain, what does this do, how does this work, giải thích, giải thích code, code này làm gì."
+agents: [documentation-writer, backend-specialist, frontend-specialist]
+related-skills: [debug, enhance, status]
+---
+
+## Memory Protocol
+**START**: Read `.ai-memory.md` from project root. Check tech stack, architecture notes, past explanations, and domain context.
+**END**: Update `.ai-memory.md` using **Memory Compaction Rules** with: what was explained, key insights, misconceptions clarified, and follow-ups.
+
+## Goal
+Help the user deeply understand code, logic, architecture, or behavior — at the level of detail they need.
+
+## Agent Routing
+- If explaining backend/API logic → read `.kiro/skills/agents/agents/backend-specialist.md` and apply its knowledge
+- If explaining UI/component behavior → read `.kiro/skills/agents/agents/frontend-specialist.md` and apply its knowledge
+- If explaining database schema/queries → read `.kiro/skills/agents/agents/database-architect.md` and apply its knowledge
+- If explaining security mechanisms → read `.kiro/skills/agents/agents/security-auditor.md` and apply its knowledge
+- Default → read `.kiro/skills/agents/agents/documentation-writer.md` for clear, structured explanation
+
+## Socratic Gate
+Before explaining, verify:
+1. Which file, function, or code block should be explained?
+2. What level of detail? (high-level overview vs line-by-line walkthrough)
+3. What is the user's familiarity level with this area?
+If any answer is unclear, ASK before proceeding.
+
+## Workflow
+1. **Read Memory** — Load `.ai-memory.md` for project context, tech stack, and architecture.
+2. Read the target code thoroughly — understand intent, not just syntax.
+3. Identify the explanation scope: single function, module, data flow, or architecture.
+4. Explain at the requested level:
+   - **High-level**: Purpose, inputs/outputs, how it fits in the system.
+   - **Detailed**: Step-by-step logic, control flow, edge cases, design decisions.
+   - **Line-by-line**: What each line does and why.
+5. Highlight non-obvious logic, hidden side effects, and design trade-offs.
+6. Use analogies or diagrams if the concept is complex.
+7. Suggest follow-up topics if relevant (e.g., "you may also want to understand X").
+8. **Quality Gate** — Read `.kiro/skills/_scripts/checklist.md` for cross-cutting checks.
+9. **Update Memory** — Save explanation context and insights to `.ai-memory.md`.
+
+## Output format
+- **What it does**: One-sentence summary
+- **How it works**: Step-by-step explanation at the requested level
+- **Key design decisions**: Why it was built this way
+- **Non-obvious details**: Edge cases, side effects, gotchas
+- **Related context**: Connected files/modules worth understanding
+
+## Checklist
+- [ ] Target code identified and read
+- [ ] Explanation level matches user need
+- [ ] Logic explained clearly, not just syntax described
+- [ ] Non-obvious details highlighted
+- [ ] Design decisions explained
+- [ ] Follow-up suggestions provided
+- [ ] Memory file updated
+
+- [ ] Clean code chuẩn (Standard clean code applied)
+- [ ] Cập nhật đầy đủ tất cả các file liên quan (All related files fully updated)
+
+## Rules
+- Explain the WHY, not just the WHAT — developers can read syntax themselves.
+- Match explanation depth to the user's familiarity level.
+- If the code is unclear or has issues, mention them without derailing the explanation.
+- Avoid proposing wide changes mid-explanation; if improvement requires broader edits, ASK before switching to implementation.
+- Always read and update the memory file.
+
+## Related Skills
+- `/debug` → read `.kiro/skills/debug/SKILL.md` — If explanation reveals bugs
+- `/enhance` → read `.kiro/skills/enhance/SKILL.md` — If explanation reveals improvement opportunities
+- `/status` → read `.kiro/skills/status/SKILL.md` — For project-wide understanding