@musashishao/agent-kit 1.2.2

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/skills/database-design/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: database-design
+description: Database design principles and decision-making. Schema design, indexing strategy, ORM selection, serverless databases.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# Database Design
+
+> **Learn to THINK, not copy SQL patterns.**
+
+## 🎯 Selective Reading Rule
+
+**Read ONLY files relevant to the request!** Check the content map, find what you need.
+
+| File | Description | When to Read |
+|------|-------------|--------------|
+| `database-selection.md` | PostgreSQL vs Neon vs Turso vs SQLite | Choosing database |
+| `orm-selection.md` | Drizzle vs Prisma vs Kysely | Choosing ORM |
+| `schema-design.md` | Normalization, PKs, relationships | Designing schema |
+| `indexing.md` | Index types, composite indexes | Performance tuning |
+| `optimization.md` | N+1, EXPLAIN ANALYZE | Query optimization |
+| `migrations.md` | Safe migrations, serverless DBs | Schema changes |
+
+---
+
+## ⚠️ Core Principle
+
+- ASK user for database preferences when unclear
+- Choose database/ORM based on CONTEXT
+- Don't default to PostgreSQL for everything
+
+---
+
+## Decision Checklist
+
+Before designing schema:
+
+- [ ] Asked user about database preference?
+- [ ] Chosen database for THIS context?
+- [ ] Considered deployment environment?
+- [ ] Planned index strategy?
+- [ ] Defined relationship types?
+
+---
+
+## Anti-Patterns
+
+❌ Default to PostgreSQL for simple apps (SQLite may suffice)
+❌ Skip indexing
+❌ Use SELECT * in production
+❌ Store JSON when structured data is better
+❌ Ignore N+1 queries

package/.agent/skills/database-design/database-selection.md

@@ -0,0 +1,43 @@
+# Database Selection (2025)
+
+> Choose database based on context, not default.
+
+## Decision Tree
+
+```
+What are your requirements?
+│
+├── Full relational features needed
+│   ├── Self-hosted → PostgreSQL
+│   └── Serverless → Neon, Supabase
+│
+├── Edge deployment / Ultra-low latency
+│   └── Turso (edge SQLite)
+│
+├── AI / Vector search
+│   └── PostgreSQL + pgvector
+│
+├── Simple / Embedded / Local
+│   └── SQLite
+│
+└── Global distribution
+    └── PlanetScale, CockroachDB, Turso
+```
+
+## Comparison
+
+| Database | Best For | Trade-offs |
+|----------|----------|------------|
+| **PostgreSQL** | Full features, complex queries | Needs hosting |
+| **Neon** | Serverless PG, branching | PG complexity |
+| **Turso** | Edge, low latency | SQLite limitations |
+| **SQLite** | Simple, embedded, local | Single-writer |
+| **PlanetScale** | MySQL, global scale | No foreign keys |
+
+## Questions to Ask
+
+1. What's the deployment environment?
+2. How complex are the queries?
+3. Is edge/serverless important?
+4. Vector search needed?
+5. Global distribution required?

package/.agent/skills/database-design/indexing.md

@@ -0,0 +1,39 @@
+# Indexing Principles
+
+> When and how to create indexes effectively.
+
+## When to Create Indexes
+
+```
+Index these:
+├── Columns in WHERE clauses
+├── Columns in JOIN conditions
+├── Columns in ORDER BY
+├── Foreign key columns
+└── Unique constraints
+
+Don't over-index:
+├── Write-heavy tables (slower inserts)
+├── Low-cardinality columns
+├── Columns rarely queried
+```
+
+## Index Type Selection
+
+| Type | Use For |
+|------|---------|
+| **B-tree** | General purpose, equality & range |
+| **Hash** | Equality only, faster |
+| **GIN** | JSONB, arrays, full-text |
+| **GiST** | Geometric, range types |
+| **HNSW/IVFFlat** | Vector similarity (pgvector) |
+
+## Composite Index Principles
+
+```
+Order matters for composite indexes:
+├── Equality columns first
+├── Range columns last
+├── Most selective first
+└── Match query pattern
+```

package/.agent/skills/database-design/migrations.md

@@ -0,0 +1,48 @@
+# Migration Principles
+
+> Safe migration strategy for zero-downtime changes.
+
+## Safe Migration Strategy
+
+```
+For zero-downtime changes:
+│
+├── Adding column
+│   └── Add as nullable → backfill → add NOT NULL
+│
+├── Removing column
+│   └── Stop using → deploy → remove column
+│
+├── Adding index
+│   └── CREATE INDEX CONCURRENTLY (non-blocking)
+│
+└── Renaming column
+    └── Add new → migrate data → deploy → drop old
+```
+
+## Migration Philosophy
+
+- Never make breaking changes in one step
+- Test migrations on data copy first
+- Have rollback plan
+- Run in transaction when possible
+
+## Serverless Databases
+
+### Neon (Serverless PostgreSQL)
+
+| Feature | Benefit |
+|---------|---------|
+| Scale to zero | Cost savings |
+| Instant branching | Dev/preview |
+| Full PostgreSQL | Compatibility |
+| Autoscaling | Traffic handling |
+
+### Turso (Edge SQLite)
+
+| Feature | Benefit |
+|---------|---------|
+| Edge locations | Ultra-low latency |
+| SQLite compatible | Simple |
+| Generous free tier | Cost |
+| Global distribution | Performance |

package/.agent/skills/database-design/optimization.md

@@ -0,0 +1,36 @@
+# Query Optimization
+
+> N+1 problem, EXPLAIN ANALYZE, optimization priorities.
+
+## N+1 Problem
+
+```
+What is N+1?
+├── 1 query to get parent records
+├── N queries to get related records
+└── Very slow!
+
+Solutions:
+├── JOIN → Single query with all data
+├── Eager loading → ORM handles JOIN
+├── DataLoader → Batch and cache (GraphQL)
+└── Subquery → Fetch related in one query
+```
+
+## Query Analysis Mindset
+
+```
+Before optimizing:
+├── EXPLAIN ANALYZE the query
+├── Look for Seq Scan (full table scan)
+├── Check actual vs estimated rows
+└── Identify missing indexes
+```
+
+## Optimization Priorities
+
+1. **Add missing indexes** (most common issue)
+2. **Select only needed columns** (not SELECT *)
+3. **Use proper JOINs** (avoid subqueries when possible)
+4. **Limit early** (pagination at database level)
+5. **Cache** (when appropriate)

package/.agent/skills/database-design/orm-selection.md

@@ -0,0 +1,30 @@
+# ORM Selection (2025)
+
+> Choose ORM based on deployment and DX needs.
+
+## Decision Tree
+
+```
+What's the context?
+│
+├── Edge deployment / Bundle size matters
+│   └── Drizzle (smallest, SQL-like)
+│
+├── Best DX / Schema-first
+│   └── Prisma (migrations, studio)
+│
+├── Maximum control
+│   └── Raw SQL with query builder
+│
+└── Python ecosystem
+    └── SQLAlchemy 2.0 (async support)
+```
+
+## Comparison
+
+| ORM | Best For | Trade-offs |
+|-----|----------|------------|
+| **Drizzle** | Edge, TypeScript | Newer, less examples |
+| **Prisma** | DX, schema management | Heavier, not edge-ready |
+| **Kysely** | Type-safe SQL builder | Manual migrations |
+| **Raw SQL** | Complex queries, control | Manual type safety |

package/.agent/skills/database-design/schema-design.md

@@ -0,0 +1,56 @@
+# Schema Design Principles
+
+> Normalization, primary keys, timestamps, relationships.
+
+## Normalization Decision
+
+```
+When to normalize (separate tables):
+├── Data is repeated across rows
+├── Updates would need multiple changes
+├── Relationships are clear
+└── Query patterns benefit
+
+When to denormalize (embed/duplicate):
+├── Read performance critical
+├── Data rarely changes
+├── Always fetched together
+└── Simpler queries needed
+```
+
+## Primary Key Selection
+
+| Type | Use When |
+|------|----------|
+| **UUID** | Distributed systems, security |
+| **ULID** | UUID + sortable by time |
+| **Auto-increment** | Simple apps, single database |
+| **Natural key** | Rarely (business meaning) |
+
+## Timestamp Strategy
+
+```
+For every table:
+├── created_at → When created
+├── updated_at → Last modified
+└── deleted_at → Soft delete (if needed)
+
+Use TIMESTAMPTZ (with timezone) not TIMESTAMP
+```
+
+## Relationship Types
+
+| Type | When | Implementation |
+|------|------|----------------|
+| **One-to-One** | Extension data | Separate table with FK |
+| **One-to-Many** | Parent-children | FK on child table |
+| **Many-to-Many** | Both sides have many | Junction table |
+
+## Foreign Key ON DELETE
+
+```
+├── CASCADE → Delete children with parent
+├── SET NULL → Children become orphans
+├── RESTRICT → Prevent delete if children exist
+└── SET DEFAULT → Children get default value
+```