@musashishao/agent-kit 1.0.1 → 1.1.0

package/.agent/FEATURE_ROADMAP.md

@@ -11,12 +11,12 @@
 |---------|-----------|-------------|-------------|---------------------|
 | Skills/Agents | 50+ skills, 45 agents | Task-focused | Plugins | 40 skills, 16 agents |
 | Marketplace | ✅ Plugin marketplace | ✅ npm package | ✅ Plugins dir | ❌ Manual install |
-| MCP Support | ✅ mcp-builder, mcp-management | ✅ MCP integration | ✅ Built-in | ❌ Missing |
+| MCP Support | ✅ mcp-builder, mcp-management | ✅ MCP integration | ✅ Built-in | ✅ mcp-builder skill |
 | CLI Tool | ❌ | ✅ task-master CLI | ✅ claude CLI | ⚠️ Basic (ag-kit) |
 | Task Management | ❌ | ✅ (Core feature) | ⚠️ Basic | ❌ Missing |
 | Web UI/Dashboard | ❌ | ❌ | ❌ | ⚠️ Docs only |
 | Multi-AI Support | ✅ Claude-focused | ✅ Any AI chat | ✅ Claude only | ✅ Gemini + others |
-| Problem-Solving Skills | ✅ 6 frameworks | ❌ | ❌ | ❌ Missing |
+| Problem-Solving Skills | ✅ 6 frameworks | ❌ | ❌ | ✅ 6 frameworks used |
 | Marketing Skills | ✅ 28 agents | ❌ | ❌ | ❌ Missing |
 
 ---
@@ -410,10 +410,10 @@ compatible_with:
 
 ## 🎯 Quick Wins (< 1 day each)
 
-1. **Add `mcp-builder` skill** - Port từ ClaudeKit
-2. **Add problem-solving skills** (6 frameworks)
+1. **Add `mcp-builder` skill** - Port từ ClaudeKit ✅ Done
+2. **Add problem-solving skills** (6 frameworks) ✅ Done
 3. **Add `mermaidjs` skill** for diagrams
-4. **Add `context-engineering` skill**
+4. **Add `context-engineering` skill** ✅ Done
 5. **Improve CLI với `ag-kit skills list`**
 6. **Add `/task` workflow** cho task management
 

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

@@ -0,0 +1,74 @@
+---
+name: context-engineering
+description: Advanced strategies to optimize LLM context window, reduce lost-in-the-middle phenomena, and improve reasoning through structured inputs.
+requirements:
+  - python >= 3.8
+  - tiktoken (for counting tokens)
+types:
+  - strategy
+  - optimization
+---
+
+# Context Engineering
+
+> **"Context is King."** - In the era of LLMs, managing the context window is the single most important factor for performance, accuracy, and cost efficiency.
+
+This skill provides a systematic approach to curating, structuring, and optimizing the information sent to AI models. It moves beyond simple "prompt engineering" into the architectural design of information flow.
+
+## 🧠 Core Philosophy: The 4 Pillars
+
+1.  **Context Curation (Signal-to-Noise Ratio):**
+    -   NEVER dump the entire codebase.
+    -   Use **Dependency Graphs** and **Symbol Jumping** to select only highly relevant files.
+    -   *Technique:* `RepoMap` (Tree structure) for high-level understanding + `Skeleton` (Signatures) for interface understanding.
+
+2.  **Context Structuring (XML & Framing):**
+    -   Use explicit XML tags (`<documents>`, `<instructions>`, `<history>`) to separate semantic zones.
+    -   **Prime Positioning:** Place critical instructions at the very end of the prompt (Recency Bias).
+    -   **Context Caching:** Structure static content (docs, rules) at the top to leverage API caching (Anthropic/Gemini).
+
+3.  **Context Compression (Information Density):**
+    -   **Skeletonization:** Replace function bodies with `...` or `pass` when only the interface is needed.
+    -   **Summarization:** Compress chat history into key architectural decisions, discarding "chit-chat".
+    -   **Token Budgeting:** Allocate tokens strictly: 40% Active Code, 30% Reference, 20% Reasoning buffer, 10% History.
+
+4.  **In-Context Guidance (Few-Shot & CoT):**
+    -   **Few-Shot Learning:** Include 2-3 examples of "Golden Code" (perfect code style for this project) to align style instantly.
+    -   **Chain-of-Thought (CoT):** Force the model to `<think>` before answering.
+
+## 📂 Skill Structure
+
+```text
+skills/context-engineering/
+├── SKILL.md                  # You are here
+├── strategies/
+│   ├── xml-framing.md        # How to organize the prompt payload
+│   ├── context-caching.md    # Optimizing for Anthropic/Gemini Cache
+│   ├── skeleton-code.md      # Technique to compress code reading
+│   └── few-shot-examples.md  # Constructing powerful examples
+└── scripts/
+    ├── token_counter.py      # Utility to estimate token usage
+    └── repo_mapper.py        # Generates a tree-view map of the project
+```
+
+## 🚀 How to Apply
+
+### 1. Before asking a complex question:
+- Run `repo_mapper.py` to give the AI a high-level map.
+- Decide which files are "Active" (need editing) vs "Reference" (need reading).
+- Use **Skeleton** mode for Reference files to save tokens.
+
+### 2. When writing instructions:
+- Wrap your request in standard XML structures.
+- Use the **Golden Rule of Positioning**:
+  - Top: Static Context (Docs, Project Rules) -> *Cached*
+  - Middle: Dynamic Context (Current Files, Chat History)
+  - Bottom: The Request (Instruction + Output Format)
+
+### 3. For Debugging & Architecture:
+- Enable **Chain-of-Thought**: Ask the AI to "Think step-by-step inside <thinking> tags".
+
+## 📚 References
+- **MemGPT:** Paging and eviction strategies (Working vs Reference memory).
+- **Anthropic Research:** Long-context prompting, finding the needle in a haystack.
+- **LlamaIndex:** Node parsing and index retrieval strategies.

package/.agent/skills/context-engineering/examples/advanced_code_request.md

@@ -0,0 +1,73 @@
+# 🤖 Advanced Context-Engineered Prompt Template
+
+Copy this entire block and fill in the placeholders to experience "SOTA" (State-of-the-Art) AI coding.
+
+---
+
+```xml
+<system_context>
+    <role>
+        You are a Principal Software Architect at Google Deepmind, specialized in Next.js, TypeScript, and Shadcn UI.
+        Your goal is to write "Golden Code": secure, performant, readable, and perfectly typed.
+    </role>
+    <constraints>
+        1. NO "any" types. Use proper interfaces or generics.
+        2. Use functional components with hooks.
+        3. Prioritize "Composition over Inheritance".
+        4. Measure twice, cut once: Think before coding.
+    </constraints>
+</system_context>
+
+<project_structure>
+./
+    web/
+        src/
+            components/
+                ui/             # Base Shadcn components
+                layout/         # Structure components
+            app/
+                docs/           # Documentation pages
+            lib/
+                utils.ts        # Helper functions
+</project_structure>
+
+<reference_documents>
+    <!-- We inject the "Skeleton" of a relevant utility to save tokens -->
+    <document path="web/src/lib/utils.ts" type="skeleton">
+        export function cn(...inputs: ClassValue[]): string;
+        export function formatDate(date: Date): string;
+    </document>
+    
+    <!-- We inject the design system rules -->
+    <document path="web/tailwind.config.ts" type="summary">
+        Primary Color: HSL(222.2, 47.4%, 11.2%)
+        Border Radius: 0.5rem
+        Font: Inter
+    </document>
+</reference_documents>
+
+<user_instruction>
+    <task>
+        Create a new "FeatureCard" component in `web/src/components/ui/feature-card.tsx`.
+    </task>
+    
+    <requirements>
+        1. It must look premium (glassmorphism effect).
+        2. It should accept an Icon, Title, Description, and an optional "Learn More" link.
+        3. It must be responsive (stack on mobile, grid on desktop).
+        4. Use the `cn()` utility for class merging.
+    </requirements>
+
+    <example_output>
+        Provide the full code for `feature-card.tsx` and a usage example.
+    </example_output>
+</user_instruction>
+
+<thinking_process_guidance>
+    Before generating the code, you must perform a "Chain of Thought" analysis inside <thinking> tags:
+    1. Analyze the requirements.
+    2. Check the <reference_documents> for available tools (cn).
+    3. Plan the component API (Props interface).
+    4. Plan the Tailwind classes for "glassmorphism".
+</thinking_process_guidance>
+```

package/.agent/skills/context-engineering/scripts/repo_mapper.py

@@ -0,0 +1,27 @@
+import os
+import sys
+
+def generate_repo_map(root_dir, ignore_dirs=None):
+    if ignore_dirs is None:
+        ignore_dirs = {'.git', 'node_modules', 'dist', 'build', '.next', '__pycache__', '.agent'}
+    
+    repo_map = []
+    
+    for root, dirs, files in os.walk(root_dir):
+        # Modify dirs in-place to skip ignored directories
+        dirs[:] = [d for d in dirs if d not in ignore_dirs]
+        
+        level = root.replace(root_dir, '').count(os.sep)
+        indent = ' ' * 4 * (level)
+        repo_map.append(f'{indent}{os.path.basename(root)}/')
+        
+        subindent = ' ' * 4 * (level + 1)
+        for f in files:
+            if f.startswith('.'): continue
+            repo_map.append(f'{subindent}{f}')
+            
+    return '\n'.join(repo_map)
+
+if __name__ == "__main__":
+    path = sys.argv[1] if len(sys.argv) > 1 else "."
+    print(generate_repo_map(path))

package/.agent/skills/context-engineering/scripts/token_counter.py

@@ -0,0 +1,65 @@
+import sys
+import tiktoken
+import os
+
+def count_tokens(text):
+    """
+    Count tokens using cl100k_base encoding (used by GPT-4, Claude 3, Gemini).
+    This is an approximation for non-OpenAI models but generally accurate enough for budgeting.
+    """
+    try:
+        encoding = tiktoken.get_encoding("cl100k_base")
+        num_tokens = len(encoding.encode(text))
+        return num_tokens
+    except Exception as e:
+        print(f"Error initializing tokenizer: {e}")
+        return 0
+
+def estimate_cost(tokens, model="gpt-4o"):
+    # Approx prices per 1M tokens (as of late 2024/2025)
+    pricing = {
+        "gpt-4o": 5.00,       # Input
+        "claude-3-5-sonnet": 3.00,
+        "gemini-1.5-pro": 3.50
+    }
+    price_per_1m = pricing.get(model, 5.00)
+    cost = (tokens / 1_000_000) * price_per_1m
+    return cost
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("Usage: python token_counter.py <file_or_directory>")
+        sys.exit(1)
+
+    path = sys.argv[1]
+    total_tokens = 0
+    
+    if os.path.isfile(path):
+        with open(path, 'r', encoding='utf-8', errors='ignore') as f:
+            content = f.read()
+            total_tokens = count_tokens(content)
+            print(f"File: {path}")
+            print(f"Tokens: {total_tokens}")
+    elif os.path.isdir(path):
+        print(f"Scanning directory: {path} (ignoring hidden & node_modules)...")
+        for root, dirs, files in os.walk(path):
+            dirs[:] = [d for d in dirs if not d.startswith('.') and d != 'node_modules']
+            for file in files:
+                if file.startswith('.'): continue
+                if file.endswith(('.png', '.jpg', '.jpeg', '.gif', '.svg', '.ico', '.woff', '.ttf')): continue
+                
+                file_path = os.path.join(root, file)
+                try:
+                    with open(file_path, 'r', encoding='utf-8', errors='ignore') as f:
+                        content = f.read()
+                        tokens = count_tokens(content)
+                        total_tokens += tokens
+                        # Optional: Print large files
+                        if tokens > 5000:
+                            print(f"  - Large file: {file_path} ({tokens} tokens)")
+                except Exception as e:
+                    pass
+    
+    print("-" * 30)
+    print(f"TOTAL TOKENS: {total_tokens:,}")
+    print(f"Est. Input Cost (GPT-4o/Claude-3.5): ~${estimate_cost(total_tokens):.4f}")

package/.agent/skills/context-engineering/strategies/context-caching.md

@@ -0,0 +1,50 @@
+# Context Caching Strategy
+
+Context Caching is a game-changer for reducing latency and cost when dealing with large contexts (e.g., full documentation, design systems, or large codebases).
+
+## How it Works
+
+Most LLM providers (Anthropic, Google Gemini) process the prompt sequentially. If the first part of the prompt (the "prefix") is identical across multiple requests, the server can cache the computed attention states of that prefix.
+
+-   **Hit:** Instant processing, drastically reduced cost (usually ~10% of input price).
+-   **Miss:** Normal processing time and cost.
+
+## The "Static-First" Rule
+
+To maximize cache hits, you must structure your prompt so that **static content is always at the top**.
+
+### ✅ Optimized Structure (Cache-Friendly)
+
+```xml
+<!-- BLOCK 1: STATIC (Cached) -->
+<system_instructions>...</system_instructions>
+<project_rules>...</project_rules>
+<library_documentation>...</library_documentation>
+<design_system>...</design_system>
+
+<!-- BLOCK 2: DYNAMIC (Not Cached) -->
+<chat_history>
+    User: Hi
+    AI: Hello
+</chat_history>
+<current_file_content>...</current_file_content>
+<new_user_request>...</new_user_request>
+```
+
+### ❌ Bad Structure (Cache-Killer)
+
+```xml
+<chat_history>...</chat_history> <!-- Changes every turn! -->
+<system_instructions>...</system_instructions> <!-- Reformatted every time, cache miss! -->
+```
+
+## Implementation Guidelines
+
+1.  **Breakpoint Management:** Providers usually require a minimum token count to activate caching (e.g., 1024 tokens for Anthropic). Ensure your static block is large enough.
+2.  **Immutable Docs:** Treat your documentation and rules as "Immutable". Do not change them dynamically per request unless necessary.
+3.  **Cache Control:** Explicitly mark the boundary where caching should stop (if the API supports explicit cache control headers or breakpoints).
+
+## Provider Specifics
+
+-   **Anthropic:** Supports `cache_control: {"type": "ephemeral"}` on specific blocks.
+-   **Gemini:** Automatic prefix caching for high-volume endpoints (check current API docs).

package/.agent/skills/context-engineering/strategies/few-shot-examples.md

@@ -0,0 +1,56 @@
+# Few-Shot Learning & In-Context Guidance
+
+"Show, Don't Tell". LLMs are excellent pattern matchers. Instead of writing 10 paragraphs of rules explaining your coding style, provide **2-3 examples** of code that follows those rules.
+
+## The Power of Few-Shot
+
+-   **Zero-Shot:** "Write a Python function to add numbers." -> *Generic output.*
+-   **Few-Shot:** "Here are 3 examples of our project's Python style. Now write a function to add numbers." -> *Output perfectly matches your project's error handling, typing, and docstring standards.*
+
+## Constructing "Golden Examples"
+
+A Golden Example should demonstrate the **Key Pillars** of your architecture.
+
+### Example: "The Robust Handler Pattern"
+
+If your project requires all API handlers to have Try-Catch, Logging, and Zod Validation, create an example like this:
+
+```xml
+<examples>
+    <example>
+        <input>Create a handler to update user profile.</input>
+        <output>
+            <thinking>
+                1. Validate input with Zod.
+                2. Use UserService for logic.
+                3. Wrap in try/catch for global error handler.
+            </thinking>
+            <code>
+                export const updateProfile = async (req: Request, res: Response) => {
+                    try {
+                        const schema = z.object({ name: z.string() });
+                        const data = schema.parse(req.body);
+                        const user = await UserService.update(req.user.id, data);
+                        return res.json({ success: true, data: user });
+                    } catch (error) {
+                        logger.error("Update profile failed", error);
+                        next(error);
+                    }
+                };
+            </code>
+        </output>
+    </example>
+</examples>
+```
+
+## When to use?
+
+1.  **New File Creation:** Essential. The AI needs to know the "boilerplate" feel.
+2.  **Complex Refactoring:** Useful to show "Before vs After" examples.
+3.  **Specific Libraries:** If using a niche library, provide examples of its usage.
+
+## Strategy: Dynamic Retrieval
+
+Don't stuff 50 examples into the context. Use **RAG (Retrieval Augmented Generation)** (or a simple grep-based selector) to find the *most relevant* example for the current task.
+-   Task: "Create React Component" -> Inject "React Component Example".
+-   Task: "Create SQL Query" -> Inject "SQL Query Example".

package/.agent/skills/context-engineering/strategies/skeleton-code.md

@@ -0,0 +1,59 @@
+# Skeleton Code Strategy
+
+**Context Compression** is vital. You rarely need the full implementation of imported modules to understand how to use them. You only need the **Interface** (signatures).
+
+## What is Skeleton Code?
+
+Skeleton code retains the structure but removes the logic implementation.
+
+### Original `auth.service.ts`:
+
+```typescript
+export class AuthService {
+  private apiUrl: string;
+
+  constructor(config: Config) {
+    this.apiUrl = config.apiUrl;
+  }
+
+  async login(credentials: Credentials): Promise<AuthResponse> {
+    if (!credentials.email || !credentials.password) {
+      throw new Error("Invalid input");
+    }
+    // ... 50 lines of logic ...
+    return response.data;
+  }
+
+  async logout(): Promise<void> {
+    // ... logic ...
+  }
+}
+```
+
+### Skeleton Version (Token Cost: ~10%):
+
+```typescript
+export class AuthService {
+  private apiUrl: string;
+  constructor(config: Config);
+  async login(credentials: Credentials): Promise<AuthResponse>;
+  async logout(): Promise<void>;
+}
+```
+
+## When to use?
+
+| File Type | Usage | Strategy |
+| :--- | :--- | :--- |
+| **Active File** | The file being edited | **Full Content** |
+| **Direct Import** | Used by Active File | **Skeleton** (usually) |
+| **Reference** | For understanding patterns | **Skeleton** or **Summary** |
+| **Config/Types** | TypeScript interfaces, Zod schemas | **Full Content** (Critical for correctness) |
+
+## Implementation Logic
+
+1.  Parse the AST (Abstract Syntax Tree) of the code.
+2.  Keep `class`, `function` definitions, `interface`, `type`.
+3.  Keep Docstrings/JSDoc (optional, usually helpful for semantics).
+4.  Remove function bodies `{ ... }`.
+5.  Remove private members (unless relevant for inheritance).

package/.agent/skills/context-engineering/strategies/xml-framing.md

@@ -0,0 +1,57 @@
+# XML Framing Strategy
+
+Use structured XML tags to clearly separate different types of information in the context. This helps the LLM distinguish between instructions, reference data, and user input.
+
+## Standard Prompt Structure
+
+```xml
+<system_context>
+    <role>You are a Senior Software Engineer specialized in [Domain].</role>
+    <rules>
+        <!-- Project-specific rules (GEMINI.md) -->
+    </rules>
+</system_context>
+
+<reference_documents>
+    <document path="docs/api_spec.md">
+        ... content ...
+    </document>
+    <document path="src/types.ts" mode="skeleton">
+        ... content ...
+    </document>
+</reference_documents>
+
+<project_structure>
+    <!-- Output of repo_mapper.py -->
+</project_structure>
+
+<chat_history>
+    <!-- Compressed history -->
+</chat_history>
+
+<user_request>
+    <instruction>
+        Refactor the login function to use the new AuthService.
+    </instruction>
+    <constraints>
+        - Do not change the function signature.
+        - Add comprehensive error handling.
+    </constraints>
+    <active_file path="src/auth.ts">
+        ... full content of the file to edit ...
+    </active_file>
+</user_request>
+
+<output_format>
+    Please provide the solution in the following format:
+    1. <thinking>: Analysis of the problem.
+    2. <plan>: Step-by-step implementation plan.
+    3. <code>: The modified code blocks.
+</output_format>
+```
+
+## Key Principles
+
+1.  **Wrappers matter:** `<code_block>` is better than just backticks for parsing.
+2.  **Attributes:** Use attributes like `<file path="...">` so the LLM knows the source.
+3.  **Nesting:** Don't go too deep (max 3 levels of nesting) to avoid confusing the attention mechanism.

package/.agent/workflows/context.md

@@ -0,0 +1,47 @@
+---
+description: Auto-generate optimized context for complex tasks using Context Engineering strategies.
+---
+
+# Context Optimization Workflow
+
+This workflow automates the "Context Engineering" process. It analyzes your request, maps the project structure, summarizes relevant files, and wraps everything in a high-performance XML prompt structure for the AI.
+
+**Trigger:** `/context [your task description]`
+
+## Steps
+
+1.  **Analyze Intent:**
+    Take the user's task description ("{{task_description}}") and identify key domains (e.g., frontend, auth, database).
+
+2.  **Generate Repo Map:**
+    // turbo
+    Run the repo mapper to see the current structure.
+    `python3 .agent/skills/context-engineering/scripts/repo_mapper.py .`
+
+3.  **Construct Optimized Prompt:**
+    Based on the repo map and task, construct the following `Advanced Context` block.
+    
+    **(Internal Instruction to AI):**
+    > You must now act as a Context Engineer. Do NOT just answer the user yet.
+    > Instead, OUTPUT a structured plan and code analysis using the gathered context.
+    > Use the `<thinking>` tag to analyze the Repo Map below.
+    > If the user's task matches specific files in the map, read them using `view_file`.
+    
+    **Structure to enforce:**
+    ```xml
+    <system_role>Senior Architect</system_role>
+    <project_context>
+        [Insert Output from Step 2 here]
+    </project_context>
+    <user_task>
+        {{task_description}}
+    </user_task>
+    <instruction>
+        1. Analyze the project structure above.
+        2. Identify ensuring files that need to be read or modified.
+        3. Proceed with solving the user's task using Chain-of-Thought (<thinking> tags).
+    </instruction>
+    ```
+
+4.  **Execute:**
+    Proceed to solve the user's request using the heightened context awareness.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@musashishao/agent-kit",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "AI Agent templates - Skills, Agents, and Workflows for enhanced coding assistance",
   "main": "index.js",
   "bin": {
@@ -40,4 +40,4 @@
   "engines": {
     "node": ">=16.0.0"
   }
-}
+}