ai-developer-skill-os 3.0.0 → 3.1.1

package/docs/adr/0004-progressive-evidence.md

@@ -0,0 +1,19 @@
+# 4. Progressive Evidence Collection
+
+Date: 2026-07-02
+
+## Status
+Accepted
+
+## Context
+AI Agents frequently fall into "hallucination loops" or "over-exploration loops", running commands like `ls`, `tree`, or reading entire project directories just to find one file. This burns through context windows rapidly and leads to poor reasoning.
+
+## Decision
+We implemented a strict **Progressive Evidence Collection** pipeline inside the OS Kernel (`AGENTS.md`):
+- **Context Budget:** Agents must start by reading 1 file, then 3 files, then a directory. They must never read the whole project unless explicitly required.
+- **Sufficient Confidence:** Agents must stop collecting evidence the moment they reach an 80% confidence threshold to proceed. 
+- **Evidence Priority:** User input > Existing context > Source code > Types > Logs > Runtime > External knowledge.
+
+## Consequences
+- **Positive:** Drastically reduced unnecessary `run_command` usage. Agents act much more like senior developers who pinpoint issues via stack traces instead of blindly searching the filesystem.
+- **Negative:** Requires rigorous enforcement in the Kernel to prevent agents from falling back to old habits.

package/docs/skill-classification.md

@@ -0,0 +1,25 @@
+# Skill Classifications (Intent-Based Policies)
+
+Skills are classified into behavioral groups that define their **Primary Objective** and **Preferred Evidence Strategy**.
+
+*Note: Actual verification depth is NOT determined by the skill itself, but must strictly follow the **Risk-based Verification Policy** defined in `AGENTS.md`.*
+
+## 1. Static Analysis Skills
+*e.g., Code Review, Project Health, Architecture, Documentation*
+- **Primary Goal:** Audit, analyze, or document without altering system behavior.
+- **Preferred Behavior:** Prefer static analysis (`read_file`, `grep_search`). Do not execute code or run test suites unless explicitly requested to validate the audit.
+
+## 2. Development Skills
+*e.g., Feature Delivery, Refactor, Bug Resolution*
+- **Primary Goal:** Modify existing behavior or implement new features safely.
+- **Preferred Behavior:** Apply localized changes. Gather targeted evidence. Avoid speculative full-project validation; verify only what is affected.
+
+## 3. Validation Skills
+*e.g., Validation Gate, CI Check, Release*
+- **Primary Goal:** Ensure code quality, security, and build stability before release.
+- **Preferred Behavior:** Exhaustive scanning. Running automated checks and full builds is encouraged to satisfy the validation gate.
+
+## 4. Maintenance Skills
+*e.g., System Evolution, Dependency Update*
+- **Primary Goal:** Upgrade system foundations safely with a rollback strategy.
+- **Preferred Behavior:** Inspect changelogs and compatibility carefully before updating. Run full system verifications post-update to ensure stability.

package/knowledge/backend/nodejs.md

@@ -0,0 +1,52 @@
+---
+id: nodejs-knowledge-base
+domain: backend
+tags: [nodejs, express, api, middleware]
+priority: high
+---
+
+# Node.js Backend Knowledge Base
+
+## Architecture Patterns
+- **Controller Layer:** Handle HTTP requests/responses, input validation, delegate to Service
+- **Service Layer:** Business logic, data transformation, transaction management  
+- **Repository Layer:** Direct database queries, ORM interactions
+- **Middleware:** Auth guards, logging, rate limiting, error handling
+
+## Express Best Practices
+```ts
+// Controller pattern - thin, delegates to service
+export async function createUser(req: Request, res: Response) {
+  const result = await userService.create(req.body);
+  res.status(201).json(result);
+}
+
+// Service pattern - business logic
+export async function create(userData: UserDto) {
+  // Validation
+  const validated = userSchema.parse(userData);
+  // Transaction
+  return db.user.create({ data: validated });
+}
+
+// Middleware pattern - reusable
+export const requireAuth = (req: Request, res: Response, next: NextFunction) => {
+  const user = verifyToken(req.headers.authorization);
+  if (!user) return res.status(401).json({ error: 'Unauthorized' });
+  req.user = user;
+  next();
+};
+```
+
+## Error Handling
+- Never throw raw Errors. Use custom error classes.
+- Always catch async errors in middleware.
+- Return consistent error format: `{ error: string, code?: string }`
+
+## Security Checklist
+- Use helmet middleware for security headers
+- Validate all inputs with Zod/Joi
+- Never commit .env files
+- Use parameterized queries to prevent SQL injection
+- Rate limit public endpoints
+- Log security events (failed logins, permission denied)

package/knowledge/frontend/react.md

@@ -12,16 +12,70 @@ priority: high
 - Use `useContext` or global stores (Zustand/Redux) when prop drilling exceeds 3 levels.
 - Never store derived data in state. Compute it on the fly during render.
 - Never store API responses in Redux if a Server State tool (React Query/SWR) is available.
+- For forms: Use React Hook Form + Zod for validation, NOT useState for each field.
 
 ## Hooks Best Practices
 - **useEffect:** Avoid using `useEffect` for data transformation or syncing state. Only use it for actual side effects (subscriptions, API calls, manual DOM mutations).
 - **useMemo / useCallback:** Only use when passing props to heavily memoized child components or when the computation is extremely expensive. Do not use them blindly.
 - **Custom Hooks:** Extract complex logic out of UI components into custom hooks. Prefix them with `use` (e.g., `useUserAuth`).
+- **Custom Hook Pattern:**
+  ```ts
+  // useApi.ts - Generic API hook
+  export function useApi<T>(url: string) {
+    const [data, setData] = useState<T | null>(null);
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState<string | null>(null);
+    
+    useEffect(() => {
+      fetchData();
+    }, [url]);
+  }
+  ```
 
 ## Component Boundaries
 - Follow Single Responsibility Principle. A component should either handle logic (Container) or handle rendering UI (Presentational), ideally not both if it's complex.
 - Keep files under 300 lines. If a file is larger, break it down.
+- **Component Hierarchy:**
+  - `components/shared/` - Reusable, no business logic
+  - `features/<domain>/components/` - Feature-specific components
+  - `layouts/` - Page layouts and wrappers
 
 ## Performance Gotchas
 - Stale Closures: Always include all reactive variables in the dependency array of `useEffect` or `useCallback`.
 - Keys in Lists: Always use unique IDs for `key` props. Never use array indices unless the list is completely static.
+- **Re-render Detection:**
+  ```ts
+  // Use console.log inside component to detect renders
+  // Wrap child in React.memo if unnecessary re-renders occur
+  export const MemoizedChild = React.memo(ChildComponent);
+  ```
+
+## Error Handling Patterns
+```ts
+// API Error Boundary
+class ErrorBoundary extends React.Component {
+  state = { hasError: false };
+  static getDerivedStateFromError() {
+    return { hasError: true };
+  }
+}
+
+// Hook error handling
+const { data, error, isLoading } = useQuery(['key'], fetchFn);
+if (error) return <ErrorMessage error={error} />;
+if (isLoading) return <LoadingSpinner />;
+```
+
+## Testing Patterns
+```tsx
+// Component test with React Testing Library
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+test('handles user interaction', async () => {
+  render(<LoginForm />);
+  const button = screen.getByRole('button', { name: /login/i });
+  await userEvent.click(button);
+  await waitFor(() => expect(mockSubmit).toHaveBeenCalled());
+});
+```

package/package.json

@@ -1,34 +1,44 @@
-{
-  "name": "ai-developer-skill-os",
-  "version": "3.0.0",
-  "description": "Multi-agent skill package cho AI coding agents (Claude, Cursor, Windsurf, Antigravity) với 23 skills chuyên nghiệp.",
-  "main": "bin/install.js",
-  "bin": {
-    "ai-developer-skill-os": "bin/install.js",
-    "ai-skill": "bin/install.js"
-  },
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/phamquangkhanh2999/ai-developer-skill-os.git"
-  },
-  "keywords": [
-    "ai",
-    "claude",
-    "cursor",
-    "windsurf",
-    "skills",
-    "developer",
-    "agent",
-    "prompts",
-    "framework"
-  ],
-  "author": "Quang Khánh",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/phamquangkhanh2999/ai-developer-skill-os/issues"
-  },
-  "homepage": "https://github.com/phamquangkhanh2999/ai-developer-skill-os#readme"
-}
+{
+  "name": "ai-developer-skill-os",
+  "version": "3.1.1",
+  "description": "Multi-agent skill package cho AI coding agents (Claude, Cursor, Windsurf, Antigravity) với 23 skills chuyên nghiệp.",
+  "main": "bin/install.js",
+  "bin": {
+    "ai-developer-skill-os": "bin/install.js",
+    "ai-skill": "bin/install.js"
+  },
+  "type": "module",
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:registry": "vitest run --config vitest.config.js",
+    "lint": "echo \"No linter configured\" && exit 0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/phamquangkhanh2999/ai-developer-skill-os.git"
+  },
+  "keywords": [
+    "ai",
+    "claude",
+    "cursor",
+    "windsurf",
+    "skills",
+    "developer",
+    "agent",
+    "prompts",
+    "framework"
+  ],
+  "author": "Quang Khánh",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/phamquangkhanh2999/ai-developer-skill-os/issues"
+  },
+  "homepage": "https://github.com/phamquangkhanh2999/ai-developer-skill-os#readme",
+  "devDependencies": {
+    "vitest": "^2.1.0",
+    "fast-glob": "^3.3.0",
+    "gray-matter": "^4.0.0",
+    "js-yaml": "^4.1.0"
+  }
+}

package/skills/qk-access-policy/SKILL.md

@@ -1,9 +1,11 @@
 ---
 name: qk-access-policy
-version: 3.0.0
+version: 3.1.0
 updated: 2026-07-02
 description: Manage RBAC, ABAC, and security boundaries.
 category: security
+behavior: static-analysis
+intent: review-code
 priority: high
 tags: [security, rbac, auth, permissions]
 platforms: [claude-code, cursor, windsurf, gemini-cli]
@@ -19,6 +21,7 @@ pipeline: [analyze, implement, engineering-standard, validate, complete]
 > **Goal:** "Bảo vệ cổng" (Security Guard). Xác định xem người dùng có đủ thẩm quyền để truy cập vào một Component UI hoặc một Endpoint API hay không.
 
 ## 🔄 1. Chain of Thought (SOP)
+
 1. **Analyze (Role Assessment):**
    - Identify the user roles (Guest, User, Admin, SuperAdmin).
 2. **Implement (Boundary Definition):**
@@ -28,13 +31,17 @@ pipeline: [analyze, implement, engineering-standard, validate, complete]
    - Ensure you didn't grant broad access by default.
 
 ## 🛡️ 2. Constraints & Rules
+
 - **Full Stack Protection:** Never hide UI elements without also securing the corresponding backend API.
 
 ## 🤝 3. Handoff Pipeline
+
 1. `validate`: Trigger `qk-validation-gate` to check for security flaws.
 2. `complete`: Generate the Access Control Report.
 
 ## 📝 4. Output Format
+
 Vui lòng trả kết quả bằng Tiếng Việt.
+
 - **Tóm tắt (Summary):** Các role vừa được setup.
 - **Chi tiết (Changes):** UI và API nào đã được bảo vệ.

package/skills/qk-ai-builder/SKILL.md

@@ -1,9 +1,11 @@
 ---
 name: qk-ai-builder
-version: 3.0.0
+version: 3.1.0
 updated: 2026-07-02
 description: Design AI Logic, Prompts, RAG pipelines, and Agents.
 category: ai
+behavior: development
+intent: implement-feature
 priority: medium
 tags: [ai, llm, prompt-engineering, rag, agents]
 platforms: [claude-code, cursor, windsurf, gemini-cli]
@@ -19,6 +21,7 @@ pipeline: [analyze, design, implement, validate, complete]
 > **Goal:** "AI Engineer". Xây dựng các tính năng thông minh bằng LLM (Chatbot, RAG pipeline, Agent workflows).
 
 ## 🔄 1. Chain of Thought (SOP)
+
 1. **Analyze (Task Breakdown):**
    - Determine the AI use case (Classification, Generation, Chat, Search).
 2. **Design (Prompt Engineering):**
@@ -29,13 +32,17 @@ pipeline: [analyze, design, implement, validate, complete]
    - Ensure API keys are not hardcoded.
 
 ## 🛡️ 2. Constraints & Rules
+
 - **JSON Parsing:** Always enforce JSON outputs if the AI response is consumed by the app, and handle parse errors.
 
 ## 🤝 3. Handoff Pipeline
+
 1. `validate`: Send to validation gate.
 2. `complete`: Output the AI Integration Report.
 
 ## 📝 4. Output Format
+
 Vui lòng trả kết quả bằng Tiếng Việt.
+
 - **Tóm tắt (Summary):** Luồng AI đã thiết lập.
 - **Chi tiết (Changes):** Prompt và logic gọi API.

package/skills/qk-api-lifecycle/SKILL.md

@@ -1,9 +1,11 @@
 ---
 name: qk-api-lifecycle
-version: 3.0.0
+version: 3.1.0
 updated: 2026-07-02
 description: Design, implement, and integrate API endpoints.
 category: engineering
+behavior: development
+intent: implement-feature
 priority: high
 tags: [api, backend, frontend-integration, endpoints]
 platforms: [claude-code, cursor, windsurf, gemini-cli]
@@ -19,6 +21,7 @@ pipeline: [analyze, implement, engineering-standard, validate, complete]
 > **Goal:** Quản lý toàn bộ vòng đời của một API, từ việc thiết kế Spec (Swagger/Types) cho đến khi Backend code xong và Frontend gọi thành công.
 
 ## 🔄 1. Chain of Thought (SOP)
+
 1. **Analyze (Contract Definition):**
    - Read the user requirements.
    - Define the exact API contract (Request Body, Query Params, Response DTO) in TypeScript interfaces or OpenAPI spec.
@@ -34,10 +37,12 @@ pipeline: [analyze, implement, engineering-standard, validate, complete]
    - Ensure loading states are managed on the frontend.
 
 ## 🛡️ 2. Constraints & Rules
+
 - **No Hardcoded URLs:** Never hardcode `http://localhost:3000` inside frontend components. Always use environment variables (`process.env.API_URL`).
 - **Separation of Concerns:** Do NOT write `fetch` or `axios.get` directly inside a React UI component. Extract it to a custom hook or an API service file.
 
 ## 🌳 3. Decision Tree
+
 ```text
 Is this a Backend or Frontend task?
   ├── BACKEND → Does the API need Database access?
@@ -49,12 +54,15 @@ Is this a Backend or Frontend task?
 ```
 
 ## 🤝 4. Handoff Pipeline
+
 1. `engineering-standard`: Verify API naming conventions (e.g., `GET /users` instead of `POST /getUsers`).
 2. `validate`: Run API tests and Type-checks.
 3. `complete`: Generate the final report.
 
 ## 📝 5. Output Format
+
 Vui lòng trả kết quả bằng Tiếng Việt. Sử dụng template chuẩn của hệ thống:
+
 - **Tóm tắt (Summary):** Các endpoint đã tạo hoặc tích hợp.
 - **Chi tiết (Changes):** File nào chứa logic API.
 - **Kiến trúc (Reasoning):** Lý do chọn thư viện hoặc cách bắt lỗi (Error handling).

package/skills/qk-bug-resolution/SKILL.md

@@ -1,9 +1,11 @@
 ---
 name: qk-bug-resolution
-version: 3.0.0
+version: 3.1.0
 updated: 2026-07-02
 description: Fix bugs and prevent regressions.
 category: engineering
+behavior: development
+intent: fix-bug
 priority: high
 tags: [bug, debug, regression]
 platforms: [claude-code, cursor, windsurf, gemini-cli]
@@ -19,6 +21,7 @@ pipeline: [analyze, implement, engineering-standard, validate, complete]
 > **Goal:** Định vị nguyên nhân, sửa lỗi triệt để, và đảm bảo lỗi không bị lặp lại (Regression Prevention).
 
 ## 🔄 1. Chain of Thought (SOP)
+
 1. **Analyze (Root Cause Analysis):**
    - Read the provided error log or bug description.
    - Trace the error to the exact file and line of code.
@@ -33,12 +36,14 @@ pipeline: [analyze, implement, engineering-standard, validate, complete]
    - Provide steps to test the fix.
    - Ensure backward compatibility.
 
-## 🛡️ 2. Constraints & Rules
+## 🛡️ 3. Constraints & Rules
+
 - **No Guesses:** Do not assume the shape of an API response. Print it or read the type definitions first.
 - **Minimal Fix:** Always prefer a 1-line fix over a 100-line refactor, unless the architecture is fundamentally broken.
 - **Clean Up:** Remove any `console.log()` or debugger statements introduced during the debugging process.
 
 ## 🌳 3. Decision Tree
+
 ```text
 Is there a Stack Trace?
   ├── YES → Use grep_search to find the exact file and line number.
@@ -50,13 +55,17 @@ Is the bug related to State/Re-rendering?
 ```
 
 ## 🤝 4. Handoff Pipeline
+
 After implementing the fix, map to the pipeline:
+
 1. `engineering-standard`: Ensure the fix follows naming and architecture rules.
 2. `validate`: Run linters and tests (via `qk-validation-gate` equivalent).
 3. `complete`: Output the final report.
 
 ## 📝 5. Output Format
+
 Vui lòng sử dụng template `templates/bug-report.md` (Báo Cáo Xử Lý Lỗi) để phản hồi lại cho người dùng bằng Tiếng Việt. Nội dung bao gồm:
+
 - Summary
 - Changes
 - Root Cause

package/skills/qk-context-loader/SKILL.md

@@ -1,9 +1,11 @@
 ---
 name: qk-context-loader
-version: 3.0.0
+version: 3.1.0
 updated: 2026-07-02
 description: Load relevant files and map the dependency graph for a task.
 category: utilities
+behavior: static-analysis
+intent: review-code
 priority: medium
 tags: [context, filesystem, dependencies, graph]
 platforms: [claude-code, cursor, windsurf, gemini-cli]
@@ -19,6 +21,7 @@ pipeline: [analyze, implement, complete]
 > **Goal:** "Người thu thập tình báo". Đảm bảo AI hiểu rõ môi trường xung quanh một file code trước khi tiến hành sửa nó, tránh lỗi thiếu context.
 
 ## 🔄 1. Chain of Thought (SOP)
+
 1. **Analyze (Target Identification):**
    - Identify the main file that needs modification.
 2. **Implement (Graph Traversal):**
@@ -29,9 +32,11 @@ pipeline: [analyze, implement, complete]
    - Build a mental map of how the data flows.
 
 ## 🛡️ 2. Constraints & Rules
+
 - **Token Optimization:** Do not load `node_modules` or massive minified build files. Extract only the exact logic needed.
 
 ## 🌳 3. Decision Tree
+
 ```text
 Is the target file a UI Component?
   ├── YES → Load its CSS/Theme tokens and any nested Child components.
@@ -39,9 +44,12 @@ Is the target file a UI Component?
 ```
 
 ## 🤝 4. Handoff Pipeline
+
 1. `complete`: Provide the context map to the Orchestrator or Target Skill.
 
 ## 📝 5. Output Format
+
 Vui lòng trả kết quả bằng Tiếng Việt.
+
 - **Tóm tắt (Summary):** Đã nạp thành công ngữ cảnh.
 - **Chi tiết (Changes):** Các file có liên quan trực tiếp.

package/skills/qk-data-lifecycle/SKILL.md

@@ -1,9 +1,11 @@
 ---
 name: qk-data-lifecycle
-version: 3.0.0
+version: 3.1.0
 updated: 2026-07-02
 description: Manage Database Schema, Migrations, and Repositories.
 category: database
+behavior: development
+intent: implement-feature
 priority: medium
 tags: [database, sql, migration, schema, orm]
 platforms: [claude-code, cursor, windsurf, gemini-cli]
@@ -19,6 +21,7 @@ pipeline: [analyze, design, implement, engineering-standard, validate, complete]
 > **Goal:** Quản lý an toàn vòng đời dữ liệu, đảm bảo Schema chuẩn xác, Migration có thể Rollback và Query tối ưu.
 
 ## 🔄 1. Chain of Thought (SOP)
+
 1. **Analyze (Requirements):**
    - Understand the entities and their relationships (1:1, 1:N, N:N).
    - Identify the ORM/Query Builder used in the project (e.g., Prisma, TypeORM, Drizzle).
@@ -33,11 +36,13 @@ pipeline: [analyze, design, implement, engineering-standard, validate, complete]
    - Review the migration script for destructive operations (e.g., `DROP TABLE`, `DROP COLUMN`).
 
 ## 🛡️ 2. Constraints & Rules
+
 - **No Data Loss:** NEVER execute a migration that drops data on Production without explicit User approval and a backup plan.
 - **Decoupling:** Do not write SQL queries directly in Controllers. Always use the Repository or DAO pattern.
 - **Index Rule:** Any column used in a `WHERE`, `JOIN`, or `ORDER BY` clause should be evaluated for an index.
 
 ## 🌳 3. Decision Tree
+
 ```text
 Is this modifying an existing table in Production?
   ├── YES → Does it drop a column or change a data type destructively?
@@ -47,12 +52,15 @@ Is this modifying an existing table in Production?
 ```
 
 ## 🤝 4. Handoff Pipeline
+
 1. `engineering-standard`: Verify naming conventions (e.g., snake_case for DB columns if required).
 2. `validate`: Run dry-run migrations or unit tests.
 3. `complete`: Generate the Database report.
 
 ## 📝 5. Output Format
+
 Vui lòng trả kết quả bằng Tiếng Việt.
+
 - **Tóm tắt (Summary):** Bảng nào được tạo/sửa.
 - **Chi tiết (Changes):** File migration và Model đã sinh ra.
 - **Kiến trúc (Reasoning):** Lý do thiết kế quan hệ bảng và các Index.

package/skills/qk-design-to-code/SKILL.md

@@ -1,9 +1,11 @@
 ---
 name: qk-design-to-code
-version: 3.0.0
+version: 3.1.0
 updated: 2026-07-02
 description: Convert Figma/Images to semantic, pixel-perfect code components.
 category: frontend
+behavior: development
+intent: implement-feature
 priority: high
 tags: [ui, figma, frontend, styling, css]
 platforms: [claude-code, cursor, windsurf, gemini-cli]
@@ -19,6 +21,7 @@ pipeline: [analyze, implement, engineering-standard, validate, complete]
 > **Goal:** Dịch thiết kế (Mockups/Images) thành mã nguồn (React, Vue, HTML/CSS) với độ chính xác Pixel-Perfect.
 
 ## 🔄 1. Chain of Thought (SOP)
+
 1. **Analyze (Deconstruct Design):**
    - Look at the provided mockup.
    - Break it down from Outside-In (Container -> Rows -> Columns -> Elements).
@@ -31,16 +34,20 @@ pipeline: [analyze, implement, engineering-standard, validate, complete]
    - Ensure the component uses relative units where necessary and scales on mobile.
 
 ## 🛡️ 2. Constraints & Rules
+
 - **No Magic Values:** Do not use random hex codes or pixel values if a Design System is available.
 - **Accessibility:** Always include `alt` for images and `aria-label` for icon-only buttons.
 
 ## 🤝 3. Handoff Pipeline
+
 1. `engineering-standard`: Ensure the UI component has no business logic.
 2. `validate`: Trigger `qk-ui-audit` checks.
 3. `complete`: Generate the UI Component Report.
 
 ## 📝 4. Output Format
+
 Vui lòng trả kết quả bằng Tiếng Việt.
+
 - **Tóm tắt (Summary):** Tên Component vừa tạo.
 - **Chi tiết (Changes):** File chứa component.
 - **Rủi ro (Risks):** Vấn đề responsive nếu có.

package/skills/qk-docs/SKILL.md

@@ -1,9 +1,11 @@
 ---
 name: qk-docs
-version: 3.0.0
+version: 3.1.0
 updated: 2026-07-02
 description: Write and maintain human-readable project documentation.
 category: documentation
+behavior: static-analysis
+intent: maintain
 priority: low
 tags: [docs, markdown, jsdoc, readme]
 platforms: [claude-code, cursor, windsurf, gemini-cli]
@@ -19,6 +21,7 @@ pipeline: [analyze, implement, validate, complete]
 > **Goal:** Đóng vai trò là "Technical Writer". Viết tài liệu (README, API Docs, Code Comments) rõ ràng, dễ hiểu cho con người.
 
 ## 🔄 1. Chain of Thought (SOP)
+
 1. **Analyze (Context Extraction):**
    - Read the target source code to understand its Inputs, Outputs, and side effects.
 2. **Implement (Drafting):**
@@ -30,10 +33,12 @@ pipeline: [analyze, implement, validate, complete]
    - Ensure proper Markdown syntax (bolding, code blocks with languages).
 
 ## 🛡️ 2. Constraints & Rules
+
 - **Human Friendly:** Avoid overly academic language. Explain it as if explaining to a junior developer.
 - **Language Hybrid:** If writing Vietnamese documentation, keep technical keywords (props, state, endpoint, fetch) in English.
 
 ## 🌳 3. Decision Tree
+
 ```text
 Is this an API Documentation?
   ├── YES → Use standard REST/GraphQL documentation layout (Endpoint, Method, Body, Response).
@@ -43,10 +48,13 @@ Is this an API Documentation?
 ```
 
 ## 🤝 4. Handoff Pipeline
+
 1. `complete`: Generate the Docs and save them to the project files.
 
 ## 📝 5. Output Format
+
 Vui lòng trả kết quả bằng Tiếng Việt.
+
 - **Tóm tắt (Summary):** Tài liệu nào đã được tạo/cập nhật.
 - **Chi tiết (Changes):** Cấu trúc tài liệu.
 - **Xác thực (Verification):** Yêu cầu User đọc lướt qua tài liệu.

package/skills/qk-documentation-system/SKILL.md

@@ -1,9 +1,11 @@
 ---
 name: qk-documentation-system
-version: 3.0.0
+version: 3.1.0
 updated: 2026-07-02
 description: Maintain system-level architecture docs and DevOps runbooks.
 category: documentation
+behavior: static-analysis
+intent: maintain
 priority: low
 tags: [architecture, diagrams, mermaid, runbooks]
 platforms: [claude-code, cursor, windsurf, gemini-cli]
@@ -19,6 +21,7 @@ pipeline: [analyze, design, implement, complete]
 > **Goal:** Quản lý tài liệu cấp hệ thống (System Architecture, Sequence Diagrams, Runbooks).
 
 ## 🔄 1. Chain of Thought (SOP)
+
 1. **Analyze (System Flow):**
    - Understand the flow of data across microservices or complex components.
 2. **Design (Diagramming):**
@@ -27,12 +30,16 @@ pipeline: [analyze, design, implement, complete]
    - Save the documentation into the `/docs/` folder.
 
 ## 🛡️ 2. Constraints & Rules
+
 - **Syntax Check:** Ensure Mermaid diagrams are syntactically valid before saving.
 
 ## 🤝 3. Handoff Pipeline
+
 1. `complete`: Output the System Documentation Report.
 
 ## 📝 4. Output Format
+
 Vui lòng trả kết quả bằng Tiếng Việt.
+
 - **Tóm tắt (Summary):** Tài liệu kiến trúc nào đã được tạo.
 - **Chi tiết (Changes):** Đường dẫn file.