@votruongdanh/ai-agent-skills 3.3.2 → 3.3.4

package/.agents/.skills-version

@@ -0,0 +1 @@
+3.3.3

package/{.kiro → .agents}/skills/agents/SKILL.md

@@ -75,6 +75,9 @@ For complex requests that span domains:
 4. Execute sequentially, sharing state via `.ai-memory.md`
 5. Merge results with consistency checks
 
+- [ ] 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 any routed task, read `.kiro/skills/_scripts/checklist.md` for cross-cutting quality checks.
 

package/{.kiro → .agents}/skills/brainstorm/SKILL.md

@@ -50,6 +50,9 @@ If any answer is unclear, ASK before proceeding.
 - [ ] 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.

package/{.kiro → .agents}/skills/clean/SKILL.md

@@ -73,6 +73,9 @@ Proceed with deletion? (y/n)
 - [ ] .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.
 

package/{.kiro → .agents}/skills/create/SKILL.md

@@ -46,6 +46,9 @@ If any answer is unclear, ASK before proceeding.
 - [ ] 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.

package/{.kiro → .agents}/skills/debug/SKILL.md

@@ -24,16 +24,17 @@ 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.
+4. List the top hypotheses ranked by likelihood. **Eliminate previously failed hypotheses immediately.**
 5. Eliminate hypotheses using direct evidence.
-6. Identify the root cause.
-7. Propose the smallest safe fix.
+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`.
@@ -41,23 +42,28 @@ If any answer is missing, ASK before proceeding.
 ## Output format
 - Symptom
 - Evidence collected
+- Failed Attempts (to avoid repetition)
 - Hypotheses (ranked by likelihood)
 - Root cause
-- Fix (smallest safe change)
+- Fix (Clean code & complete file updates)
 - Verification steps
 - Regression prevention
 
 ## Checklist
 - [ ] Bug clearly described (expected vs actual)
-- [ ] Evidence gathered (logs, stacktrace, code)
+- [ ] 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 minimal and safe
+- [ ] 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.

package/{.kiro → .agents}/skills/deploy/SKILL.md

@@ -53,6 +53,9 @@ If any answer is unclear, ASK before proceeding.
 - [ ] 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.

package/{.kiro → .agents}/skills/enhance/SKILL.md

@@ -45,6 +45,9 @@ If any answer is unclear, ASK before proceeding.
 - [ ] 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.

package/{.kiro → .agents}/skills/explain/SKILL.md

@@ -56,6 +56,9 @@ If any answer is unclear, ASK before proceeding.
 - [ ] 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.

package/{.kiro → .agents}/skills/integrate/SKILL.md

@@ -18,6 +18,9 @@ Before editing, verify these inputs exist. If any is missing or ambiguous, ASK:
 2. The **target location** in this project (file/module/feature area).
 3. Constraints: must keep API stable? must keep UI stable? backward compatible?
 
+- [ ] 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 (Blast-radius control)
 - Touch the **smallest** possible set of files.
 - Do **not** reformat or restructure unrelated code.

package/{.kiro → .agents}/skills/motion-ui/SKILL.md

@@ -341,6 +341,9 @@ If any answer is unclear, ASK before proceeding.
 - [ ] Color contrast verified (WCAG AA)
 - [ ] 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
 - Motion should enhance, not distract.
 - Keep animations subtle and purposeful.

package/{.kiro → .agents}/skills/orchestrate/SKILL.md

@@ -59,6 +59,9 @@ If any answer is unclear, ASK before proceeding.
 - [ ] Done criteria set
 - [ ] 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
 - Keep plans realistic for the current project.
 - Surface unknowns early.

package/{.kiro → .agents}/skills/plan/SKILL.md

@@ -54,6 +54,9 @@ If any answer is unclear, ASK before proceeding.
 - [ ] First action 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
 - Plans should be specific enough to execute.
 - Prefer task sizes that can be completed and reviewed quickly.

package/{.kiro → .agents}/skills/preview/SKILL.md

@@ -40,6 +40,9 @@ If any answer is unclear, ASK before proceeding.
 - [ ] Implementation differences noted
 - [ ] 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
 - Keep previews realistic and consistent with the current project.
 - Label illustrative content clearly when it is mock data.

package/{.kiro → .agents}/skills/status/SKILL.md

@@ -42,6 +42,9 @@ Summarize where things stand right now, leveraging the memory file for deep cont
 - [ ] Next priority recommended
 - [ ] Memory file updated with status snapshot
 
+- [ ] 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
 - Be specific and evidence-based.
 - Separate facts from inference.

package/{.kiro → .agents}/skills/test/SKILL.md

@@ -45,6 +45,9 @@ If any answer is unclear, ASK before proceeding.
 - [ ] Run instructions 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 stable tests over brittle tests.
 - Cover both happy path and key edge cases.

package/{.kiro → .agents}/skills/ui-ux-pro-max/SKILL.md

@@ -52,6 +52,9 @@ If any answer is unclear, ASK before proceeding.
 - [ ] Brand consistency maintained
 - [ ] 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
 - Optimize for clarity before decoration.
 - Respect existing brand and component patterns when present.

package/.kiro/.skills-version

@@ -0,0 +1 @@
+3.3.3

package/README.md

@@ -110,6 +110,16 @@ The `add` command:
 
 Native skill targets keep the full skill directory. Generated compatibility targets (Cursor `.mdc` rules, Antigravity workflows) only render `SKILL.md` content — companion `scripts/`, `references/`, and `assets/` remain native-only.
 
+## For AI Agents & Developers: How to Edit Skills
+
+All skills are now stored in the `skills/` directory at the root of the project. This is the **canonical source of truth**.
+
+When you need to edit, update, or add a new skill:
+1. Edit the Markdown files directly in the `skills/` directory.
+2. Run `npm run sync:all` to automatically synchronize your changes to all supported IDE formats (Cursor, Kiro, Antigravity, VS Code, Codex, etc.).
+
+**Note:** DO NOT manually edit the generated files in `.agent/workflows/`, `.cursor/rules/`, or similar IDE-specific folders, as your changes will be overwritten upon sync.
+
 ## Available Skills (16)
 
 | Skill | Description |
@@ -169,16 +179,17 @@ The router handles keyword matching, Vietnamese triggers, compound keywords, and
 ## How the Package is Structured
 
 ```
-.kiro/skills/          # Canonical skill source (16 skills)
+skills/                # Canonical skill source (16 skills)
 .agents/skills/        # Cross-client interop root
 lib/skill-bundle.js    # Discovery, YAML parsing, catalog, render, install
 bin/cli.js             # Interactive CLI with colors, prompts, GitHub fetcher
 bin/install-skills.ps1 # Optional PowerShell wrapper
 scripts/render-targets.js  # Sample output renderer
+scripts/sync-all.js    # Script to sync 'skills/' to all IDE folders
 verify.js              # 44-check test suite
 ```
 
-- Canonical source prefers `.skills`, then falls back to `.kiro/skills`
+- Canonical source prefers `skills/`, then falls back to `.skills`
 - `lib/skill-bundle.js` contains all discovery, parsing, rendering, and install logic
 - `bin/cli.js` provides interactive install, GitHub `add`, list, status, and help commands
 - Each skill exposes: `slug`, `name`, `description`, `sourceRoot`, `hasScripts`, `hasReferences`, `hasAssets`, and per-target compatibility metadata

package/bin/cli.js

@@ -185,6 +185,7 @@ async function interactiveInit() {
   const supportedIDEOptions = [
     { label: 'Cursor', value: 'cursor', description: '.cursor/skills + .cursor/rules', recommended: true },
     { label: 'Kiro', value: 'kiro', description: '.kiro/skills' },
+    { label: 'Claude Code', value: 'claude-code', description: '.claude/skills' },
     { label: 'Antigravity', value: 'antigravity', description: '.agent/workflows' },
     { label: 'Codex', value: 'codex', description: '.agents/skills (+ AGENTS.md / memories)' },
     { label: 'VS Code', value: 'vscode', description: '.github/skills' },
@@ -416,6 +417,7 @@ async function addSkillFromGitHub() {
         const ideOptions = [
           { label: 'Cursor', value: 'cursor', description: '.cursor/skills', recommended: true },
           { label: 'Kiro', value: 'kiro', description: '.kiro/skills' },
+          { label: 'Claude Code', value: 'claude-code', description: '.claude/skills' },
           { label: 'Antigravity', value: 'antigravity', description: '.agent/workflows' },
           { label: 'Codex', value: 'codex', description: '.agents/skills (+ AGENTS.md / memories)' },
           { label: 'VS Code', value: 'vscode', description: '.github/skills' },
@@ -801,6 +803,7 @@ ${c.bold}Supported IDEs:${c.reset}
 
   ${c.cyan}cursor${c.reset}       ${c.dim}→ .cursor/skills + .cursor/rules${c.reset}
   ${c.cyan}kiro${c.reset}         ${c.dim}→ .kiro/skills${c.reset}
+  ${c.cyan}claude-code${c.reset}  ${c.dim}→ .claude/skills${c.reset}
   ${c.cyan}antigravity${c.reset}  ${c.dim}→ .agent/workflows${c.reset}
   ${c.cyan}codex${c.reset}        ${c.dim}→ .agents/skills (detected via AGENTS.md / memories)${c.reset}
   ${c.cyan}vscode${c.reset}       ${c.dim}→ .github/skills${c.reset}

package/lib/skill-bundle.js

@@ -6,8 +6,8 @@ const yaml = require('yaml');
 const PACKAGE_ROOT = path.join(__dirname, '..');
 const PORTABLE_SKILLS_DIR = path.join(PACKAGE_ROOT, '.skills');
 const LEGACY_CANONICAL_SKILLS_DIR = path.join(PACKAGE_ROOT, '.kiro', 'skills');
-const CANONICAL_SKILLS_DIR = LEGACY_CANONICAL_SKILLS_DIR;
-const CANONICAL_SKILL_ROOTS = ['.skills', '.agents/skills', '.kiro/skills'];
+const CANONICAL_SKILLS_DIR = path.join(PACKAGE_ROOT, 'skills');
+const CANONICAL_SKILL_ROOTS = ['skills', '.skills', '.agents/skills', '.kiro/skills'];
 const PORTABLE_ASSET_DIRS = ['scripts', 'references', 'assets', 'agents'];
 
 const IDE_ALIASES = {
@@ -166,10 +166,15 @@ function getCanonicalSkillRootDefinitions(options = {}) {
   const bundleRoot = path.resolve(options.bundleRoot || PACKAGE_ROOT);
 
   return [
+    {
+      sourceRoot: 'skills',
+      sourceDir: path.join(bundleRoot, 'skills'),
+      priority: 0,
+    },
     {
       sourceRoot: '.skills',
       sourceDir: path.join(bundleRoot, '.skills'),
-      priority: 0,
+      priority: 1,
     },
     {
       sourceRoot: '.agents/skills',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@votruongdanh/ai-agent-skills",
-  "version": "3.3.2",
+  "version": "3.3.4",
   "description": "Cross-IDE AI agent skills with native installers for Kiro, Cursor, Antigravity, and VS Code/Copilot",
   "main": "index.js",
   "bin": {
@@ -9,6 +9,7 @@
   "scripts": {
     "build:targets": "node scripts/render-targets.js",
     "test": "node verify.js",
+    "sync:all": "node scripts/sync-all.js",
     "release:patch": "npm version patch && git push origin main --tags",
     "release:minor": "npm version minor && git push origin main --tags",
     "release:major": "npm version major && git push origin main --tags"
@@ -43,6 +44,7 @@
   },
   "homepage": "https://github.com/votruongdanh/ai-agent-skills#readme",
   "files": [
+    "skills",
     ".skills",
     ".agents",
     ".kiro",

package/scripts/sync-all.js

@@ -0,0 +1,20 @@
+const { installBundle } = require('./lib/skill-bundle.js');
+const targets = ['cursor', 'antigravity', 'kiro', 'vscode', 'codex', 'claude-code'];
+const baseDir = __dirname;
+const pkg = require('./package.json');
+
+console.log('Syncing updated skills to all IDE targets...');
+for (const ide of targets) {
+  try {
+    const result = installBundle({
+      baseDir,
+      ide,
+      scope: 'project',
+      version: pkg.version,
+      includeCompatibilityAliases: true
+    });
+    console.log(`Successfully synced to ${result.ide} (${result.skillCount} skills)`);
+  } catch (err) {
+    console.error(`Failed for ${ide}:`, err.message);
+  }
+}

package/skills/_scripts/.ai-memory-template.md

@@ -0,0 +1,55 @@
+# Project Memory
+
+> This file is automatically maintained by AI Agent Skills.
+> It persists project understanding across conversations.
+> **Do NOT delete this file** — it helps AI give better, context-aware responses.
+
+## Codex Memory Structure (when available)
+- If the workspace has `memories/`, use it alongside this file.
+- `memories/` = persistent user-level notes.
+- `memories/session/` = temporary notes for current conversation.
+- `memories/repo/` = repository-scoped technical facts and conventions.
+- Keep `.ai-memory.md` as the cross-IDE source of truth; mirror only high-signal repo facts into `memories/repo/`.
+
+## Memory Compaction Rules (IMPORTANT)
+- **Write style**: concise bullets, no paragraphs. Prefer numbers, filenames, and nouns over prose.
+- **No duplication**: if a new note repeats an existing one, update the existing bullet instead of appending.
+- **Deduping rule (anti-duplicate)**:
+  - Before writing, **scan the target section** for a similar bullet.
+  - Consider bullets “similar” if they match after: lowercasing + trimming + collapsing whitespace + removing trailing punctuation.
+  - If similar: **merge into 1 bullet** (keep the most specific wording, add missing file paths/IDs).
+  - Never keep 2 bullets that describe the same decision/issue/work item.
+- **Hard limits**:
+  - Tech Stack: max 6 bullets
+  - Architecture: max 8 bullets
+  - Conventions: max 8 bullets
+  - Decisions: keep last 12 items
+  - Known Issues: keep last 20 items (closed issues can be removed once stable)
+  - Recent Work: keep last 15 items
+- **Per bullet**: aim ≤ 140 characters. If longer, split into 2 bullets.
+- **Always include**: files touched (paths), and why (1 short phrase).
+
+## Tech Stack
+- Language: (auto-detected on first use)
+- Framework: (auto-detected on first use)
+- Database: (if any)
+- Package manager: (auto-detected)
+
+## Architecture
+- Pattern: (discovered)
+- Key directories: (discovered)
+- Entry points: (discovered)
+
+## Conventions
+- Naming: (observed from codebase)
+- File structure: (observed)
+- Testing: (framework + patterns observed)
+
+## Decisions
+<!-- Format: - [YYYY-MM-DD] Decision description and rationale -->
+
+## Known Issues
+<!-- Format: - [status] Issue description -->
+
+## Recent Work
+<!-- Format: - [YYYY-MM-DD] What was done, files changed, outcome -->

package/skills/_scripts/checklist.md

@@ -0,0 +1,35 @@
+---
+name: checklist
+description: Reusable pre/post checklists for any skill execution
+---
+
+## Pre-Execution Checklist (Run before ANY skill)
+- [ ] Read `.ai-memory.md` from project root
+- [ ] Understand user intent (ask if unclear)
+- [ ] Check if similar work was done before (from memory)
+- [ ] Identify the correct agent for the domain
+- [ ] Minimize blast radius: identify the smallest set of files that must change
+- [ ] If any step is uncertain or could cause broad changes, ask before editing
+
+## Post-Execution Checklist (Run after ANY skill)
+- [ ] All checklist items from the skill are satisfied
+- [ ] No regressions introduced
+- [ ] Code follows existing project conventions
+- [ ] Update `.ai-memory.md` with findings (follow "Memory Compaction Rules")
+- [ ] Dedupe `.ai-memory.md` updates: merge similar bullets instead of appending duplicates
+- [ ] If `.ai-memory.md` exceeds 500 lines or sections exceed limits, compact it (see `.kiro/skills/_scripts/memory-compact.md`)
+- [ ] Suggest related next steps
+
+## Code Quality Checklist
+- [ ] No hardcoded secrets or credentials
+- [ ] Error handling at system boundaries
+- [ ] Input validation for user-facing code
+- [ ] Existing tests still pass
+- [ ] New code is covered by tests (if test framework exists)
+
+## Security Checklist
+- [ ] No SQL injection vectors
+- [ ] No XSS vulnerabilities
+- [ ] No exposed secrets in code or logs
+- [ ] Dependencies are up to date
+- [ ] Access controls are appropriate

package/skills/_scripts/memory-compact.md

@@ -0,0 +1,142 @@
+---
+name: memory-compact
+description: Procedure to compact `.ai-memory.md` when it grows too long
+---
+
+## When to compact
+Run this procedure when `.ai-memory.md` exceeds **500 lines** or when you notice:
+- Duplicate or near-duplicate bullets
+- Outdated information (old decisions, resolved issues, ancient work items)
+- Verbose bullets that could be shortened
+- Sections exceeding their hard limits (see Memory Compaction Rules)
+
+## Compaction procedure
+
+### 1. Check section limits (from `.ai-memory-template.md`)
+- **Tech Stack**: max 6 bullets
+- **Architecture**: max 8 bullets
+- **Conventions**: max 8 bullets
+- **Decisions**: keep last 12 items
+- **Known Issues**: keep last 20 items (remove resolved/closed)
+- **Recent Work**: keep last 15 items
+
+### 2. Dedupe within each section
+For each section:
+1. Read all bullets
+2. Group similar bullets (same topic, same file, same decision)
+3. Merge groups into single bullets:
+   - Keep most specific wording
+   - Preserve all file paths, dates, IDs
+   - Remove redundant phrases
+
+**Example:**
+```markdown
+Before:
+- [2024-01-15] Added auth middleware to protect routes
+- [2024-01-16] Implemented authentication middleware in src/middleware/auth.js
+- Auth middleware added for route protection
+
+After:
+- [2024-01-15] Added auth middleware (src/middleware/auth.js) to protect routes
+```
+
+### 3. Remove outdated items
+- **Decisions**: Keep only decisions still relevant to current architecture
+- **Known Issues**: Remove resolved/closed issues older than 30 days
+- **Recent Work**: Keep only last 15 items (remove older)
+
+### 4. Shorten verbose bullets
+Target: ≤ 140 characters per bullet
+
+**Techniques:**
+- Remove filler words: "basically", "essentially", "in order to"
+- Use abbreviations: "impl" for "implemented", "cfg" for "config"
+- Use file paths instead of descriptions: `src/auth.js` not "the authentication file"
+- Use symbols: `+` for "added", `~` for "updated", `-` for "removed"
+
+**Example:**
+```markdown
+Before:
+- [2024-01-15] We implemented a new authentication system that uses JWT tokens for user sessions in the backend API
+
+After:
+- [2024-01-15] + JWT auth system (src/api/auth.js) for user sessions
+```
+
+### 5. Enforce hard limits
+If a section still exceeds limits after deduping and shortening:
+- **Decisions**: Keep last 12, archive older ones in a comment
+- **Known Issues**: Keep last 20, remove oldest resolved
+- **Recent Work**: Keep last 15, remove oldest
+
+**Archive pattern:**
+```markdown
+## Decisions
+- [2024-03-01] Current decision 1
+- [2024-02-28] Current decision 2
+...
+
+<!-- Archived decisions (for reference):
+- [2024-01-15] Old decision that's no longer relevant
+-->
+```
+
+### 6. Verify compaction
+After compacting:
+- [ ] No section exceeds hard limits
+- [ ] No duplicate bullets
+- [ ] All bullets ≤ 140 characters (or split into 2)
+- [ ] File paths preserved
+- [ ] Dates preserved
+- [ ] Recent/important info retained
+
+## Quick compaction (when in a hurry)
+If you need to compact quickly:
+1. **Recent Work**: Keep last 15, delete rest
+2. **Known Issues**: Remove all resolved/closed, keep last 20
+3. **Decisions**: Keep last 12
+4. Run dedupe on remaining bullets (merge similar ones)
+
+## Automation tip
+When updating memory, always:
+1. Check if section is at limit BEFORE adding
+2. If at limit, remove oldest item OR merge with existing
+3. Never append if it creates a duplicate
+
+## Example: Full compaction
+
+**Before (verbose, duplicates, over limits):**
+```markdown
+## Recent Work
+- [2024-01-10] Added login page
+- [2024-01-11] Created login component
+- [2024-01-12] Implemented login functionality
+- [2024-01-13] Fixed login bug
+- [2024-01-14] Updated login styles
+- [2024-01-15] Added logout button
+- [2024-01-16] Implemented logout functionality
+- [2024-01-17] Fixed logout bug
+- [2024-01-18] Added user profile page
+- [2024-01-19] Created user profile component
+- [2024-01-20] Implemented profile edit
+- [2024-01-21] Fixed profile bug
+- [2024-01-22] Added settings page
+- [2024-01-23] Created settings component
+- [2024-01-24] Implemented settings save
+- [2024-01-25] Fixed settings bug
+- [2024-01-26] Added dashboard
+- [2024-01-27] Created dashboard component
+```
+
+**After (compact, deduped, within limits):**
+```markdown
+## Recent Work
+- [2024-01-27] + Dashboard (src/pages/Dashboard.jsx)
+- [2024-01-26] + Settings page (src/pages/Settings.jsx) with save functionality
+- [2024-01-22] + User profile page (src/pages/Profile.jsx) with edit feature
+- [2024-01-15] + Login/logout (src/pages/Login.jsx, src/components/LogoutBtn.jsx)
+```
+
+## Related
+- Read `.kiro/skills/_scripts/.ai-memory-template.md` for Memory Compaction Rules
+- Read `.kiro/skills/_scripts/memory-dedupe.md` for dedupe procedure

package/skills/_scripts/memory-dedupe.md

@@ -0,0 +1,26 @@
+---
+name: memory-dedupe
+description: Lightweight dedupe procedure for `.ai-memory.md` updates
+---
+
+## When to use
+Run mentally for every memory update, especially when adding items to **Decisions**, **Known Issues**, or **Recent Work**.
+
+## Dedupe procedure (fast)
+1. Pick the **target section** (Decisions / Known Issues / Recent Work / etc.).
+2. Before adding a new bullet, scan existing bullets for a near-match.
+3. Normalize both bullets and compare:
+   - lowercase
+   - trim
+   - collapse whitespace
+   - remove trailing punctuation (`.`, `;`, `,`)
+4. If it’s the same idea:
+   - **merge** into the existing bullet
+   - keep the most concrete version (file paths, error codes, IDs, dates)
+   - remove the redundant one
+5. Only append a new bullet if it’s clearly a new fact/event/decision.
+
+## Examples
+- Two bullets both say “Added auth middleware” → keep one, add the specific files touched.
+- “Fix login bug” and “Fixed login issue” → merge into one with the root cause or PR/files.
+