@techwavedev/agi-agent-kit 1.6.4 → 1.6.5

package/templates/skills/knowledge/ai-agents/SKILLS_CATALOG.md

@@ -0,0 +1,237 @@
+# Skills Catalog
+
+> **Auto-generated Documentation** — Last updated: 2026-03-14 21:14
+>
+> This catalog is automatically maintained. Update it by running:
+> ```bash
+> python skill-creator/scripts/update_catalog.py --skills-dir skills/
+> ```
+
+This document provides comprehensive documentation on available skills, how to use them, and when each skill should be triggered.
+
+---
+
+## Table of Contents
+
+- [What Are Skills?](#what-are-skills)
+- [Available Skills](#available-skills)
+  - [Agent Memory Systems](#agent-memory-systems)
+  - [Agent Tool Builder](#agent-tool-builder)
+  - [Ai Agents Architect](#ai-agents-architect)
+  - [Ai Engineer](#ai-engineer)
+  - [Autonomous Agent Patterns](#autonomous-agent-patterns)
+  - [Debug Llm](#debug-llm)
+  - [Mcp Builder](#mcp-builder)
+  - [Notebooklm Rag](#notebooklm-rag)
+  - [Parallel Agents](#parallel-agents)
+  - [Prompt Engineering Patterns](#prompt-engineering-patterns)
+- [Using Skills](#using-skills)
+- [Creating New Skills](#creating-new-skills)
+- [Maintenance](#maintenance)
+
+---
+
+## What Are Skills?
+
+**Skills** are modular, self-contained packages that extend the AI agent's capabilities with specialized knowledge, workflows, and tools.
+
+### Skill Structure
+
+```
+skill-name/
+├── SKILL.md           # (required) Main instruction file
+├── scripts/           # (optional) Executable scripts
+├── references/        # (optional) Documentation
+└── assets/            # (optional) Templates, images, etc.
+```
+
+---
+
+## Available Skills
+
+### Agent Memory Systems
+
+| Property | Value |
+| -------- | ----- |
+| **Name** | `agent-memory-systems` |
+| **Location** | `skills/agent-memory-systems/` |
+| **Type** | Standalone |
+
+**Description:** "Memory is the cornerstone of intelligent agents. Without it, every interaction starts from zero. This skill covers the architecture of agent memory: short-term (context window), long-term (vector stores), and the cognitive architectures that organize them.  Key insight: Memory isn't just storage - it's retrieval. A million stored facts mean nothing if you can't find the right one. Chunking, embedding, and retrieval strategies determine whether your agent remembers or forgets.  The field is fragm"
+
+---
+
+### Agent Tool Builder
+
+| Property | Value |
+| -------- | ----- |
+| **Name** | `agent-tool-builder` |
+| **Location** | `skills/agent-tool-builder/` |
+| **Type** | Standalone |
+
+**Description:** "Tools are how AI agents interact with the world. A well-designed tool is the difference between an agent that works and one that hallucinates, fails silently, or costs 10x more tokens than necessary.  This skill covers tool design from schema to error handling. JSON Schema best practices, description writing that actually helps the LLM, validation, and the emerging MCP standard that's becoming the lingua franca for AI tools.  Key insight: Tool descriptions are more important than tool implementa"
+
+---
+
+### Ai Agents Architect
+
+| Property | Value |
+| -------- | ----- |
+| **Name** | `ai-agents-architect` |
+| **Location** | `skills/ai-agents-architect/` |
+| **Type** | Standalone |
+
+**Description:** "Expert in designing and building autonomous AI agents. Masters tool use, memory systems, planning strategies, and multi-agent orchestration. Use when: build agent, AI agent, autonomous agent, tool use, function calling."
+
+---
+
+### Ai Engineer
+
+| Property | Value |
+| -------- | ----- |
+| **Name** | `ai-engineer` |
+| **Location** | `skills/ai-engineer/` |
+| **Type** | Standalone |
+
+**Description:** Build production-ready LLM applications, advanced RAG systems, and
+
+---
+
+### Autonomous Agent Patterns
+
+| Property | Value |
+| -------- | ----- |
+| **Name** | `autonomous-agent-patterns` |
+| **Location** | `skills/autonomous-agent-patterns/` |
+| **Type** | Standalone |
+
+**Description:** "Design patterns for building autonomous coding agents. Covers tool integration, permission systems, browser automation, and human-in-the-loop workflows. Use when building AI agents, designing tool APIs, implementing permission systems, or creating autonomous coding assistants."
+
+---
+
+### Debug Llm
+
+| Property | Value |
+| -------- | ----- |
+| **Name** | `debug-llm` |
+| **Location** | `skills/debug-llm/` |
+| **MCP Server** | `mcp_server.py` |
+| **Type** | Standalone |
+
+**Description:** *[Description not yet provided]*
+
+**References:**
+- `references/api_reference.md`
+
+---
+
+### Mcp Builder
+
+| Property | Value |
+| -------- | ----- |
+| **Name** | `mcp-builder` |
+| **Location** | `skills/mcp-builder/` |
+| **Type** | Standalone |
+
+**Description:** Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).
+
+---
+
+### Notebooklm Rag
+
+| Property | Value |
+| -------- | ----- |
+| **Name** | `notebooklm-rag` |
+| **Location** | `skills/notebooklm-rag/` |
+| **Type** | Standalone |
+
+**Description:** "Deep RAG layer powered by Google NotebookLM + Gemini. The agent autonomously manages notebooks via MCP tools — authentication, library management, querying, follow-ups, and caching. Opt-in for users with a Google account. Default RAG is qdrant-memory. Triggers on: '@notebooklm', 'research my docs', 'deep search', 'query my notebook', 'check my notebooks'."
+
+**Scripts:**
+
+| Script | Purpose |
+| ------ | ------- |
+| `scripts/ask_question.py` | *[See script for details]* |
+| `scripts/auth_manager.py` | *[See script for details]* |
+| `scripts/browser_utils.py` | *[See script for details]* |
+| `scripts/cleanup_manager.py` | *[See script for details]* |
+| `scripts/config.py` | *[See script for details]* |
+| `scripts/notebook_manager.py` | *[See script for details]* |
+| `scripts/run.py` | *[See script for details]* |
+| `scripts/setup_environment.py` | *[See script for details]* |
+
+---
+
+### Parallel Agents
+
+| Property | Value |
+| -------- | ----- |
+| **Name** | `parallel-agents` |
+| **Location** | `skills/parallel-agents/` |
+| **Type** | Standalone |
+
+**Description:** Platform-adaptive multi-agent orchestration. Uses Claude Code Agent Teams when available, subagents as fallback, and sequential persona switching on other platforms. Use when multiple independent tasks can run with different domain expertise or when comprehensive analysis requires multiple perspectives.
+
+---
+
+### Prompt Engineering Patterns
+
+| Property | Value |
+| -------- | ----- |
+| **Name** | `prompt-engineering-patterns` |
+| **Location** | `skills/prompt-engineering-patterns/` |
+| **Type** | Standalone |
+
+**Description:** Master advanced prompt engineering techniques to maximize LLM performance, reliability, and controllability in production. Use when optimizing prompts, improving LLM outputs, or designing production prompt templates.
+
+**Scripts:**
+
+| Script | Purpose |
+| ------ | ------- |
+| `scripts/optimize-prompt.py` | *[See script for details]* |
+
+**References:**
+- `references/chain-of-thought.md`
+- `references/few-shot-learning.md`
+- `references/prompt-optimization.md`
+- `references/prompt-templates.md`
+- `references/system-prompts.md`
+
+---
+## Using Skills
+
+Skills are automatically triggered based on the user's request matching the skill description. You can also explicitly invoke a skill:
+
+```
+"Use the <skill-name> skill to <task>"
+```
+
+---
+
+## Creating New Skills
+
+```bash
+# Initialize a new skill
+python skill-creator/scripts/init_skill.py my-new-skill --path skills/
+
+# Package the skill
+python skill-creator/scripts/package_skill.py skills/my-new-skill
+```
+
+For detailed guidance, see: `skill-creator/SKILL_skillcreator.md`
+
+---
+
+## Maintenance
+
+### Updating This Catalog
+
+**IMPORTANT:** This catalog must be updated whenever skills are created, modified, or deleted.
+
+```bash
+python skill-creator/scripts/update_catalog.py --skills-dir skills/
+```
+
+---
+
+*This catalog is part of the [3-Layer Architecture](../AGENTS.md) for reliable AI agent operations.*

package/templates/skills/knowledge/ai-agents/debug-llm/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: debug-llm
+description: "Instrument, trace, and monitor LLM calls securely inside a self-hosted Langfuse instance running via Docker Compose. Analyze agent performance, debug complex flows, and compute LLM costs natively. Default debug-llm locally deployed. Triggers on: '@debug-llm', 'monitor llm', 'trace my agent', 'langfuse local', 'see how it is performing'."
+---
+
+# Debug LLM (Self-hosted Langfuse)
+
+> **This is an Observability and Tracing tool.** The agent uses a self-hosted instance of Langfuse via Docker Compose to trace LLM calls, calculate performance, assess costs, and help you "see how it is performing".
+>
+> **Opt-in:** Fully local, fully self-hosted, your data never leaves the Docker container unless explicitly sent to your own keys.
+
+## Architecture
+
+```
+User question/command
+    ↓
+Agent checks Langfuse Health → not running? → start (docker-compose up)
+    ↓ running
+Agent provides Langfuse UI link (localhost:3000)
+    ↓
+Agent instruments requests via LiteLLM / Langfuse SDK wrappers
+    ↓
+Agent queries traces inside Langfuse (or reviews dashboard)
+    ↓
+Agent identifies bottlenecks, high costs, or failing traces
+    ↓
+Agent reports LLM performance metrics
+```
+
+## Quick Start
+
+### 1. Check if Langfuse is running
+
+```
+Agent calls: status
+If not running:
+  Agent calls: start (runs docker-compose up -d)
+  Wait for healthcheck (localhost:3000)
+```
+
+### 2. Configure Environment
+
+After starting Langfuse locally, the agent should configure the environment variables needed to push traces:
+
+* `LANGFUSE_PUBLIC_KEY`
+* `LANGFUSE_SECRET_KEY`
+* `LANGFUSE_HOST=http://localhost:3000`
+
+> Note: For automatic local telemetry, generate the keys inside the Langfuse local dashboard (username: admin@langfuse.com, password: randomly assigned or setup manually upon first startup).
+
+### 3. Trace
+
+Start observing any LLM agent logic using these environment variables, or through the python SDK:
+```python
+from langfuse import Langfuse
+langfuse = Langfuse(
+  secret_key="...",
+  public_key="...",
+  host="http://localhost:3000"
+)
+langfuse.auth_check()
+```
+
+## Agent Scripts Reference
+
+The agent has direct access to these scripts via `scripts/run.py`:
+
+| Tool     | When                           |
+| -------- | ------------------------------ |
+| `start`  | Bring up local Langfuse Docker |
+| `stop`   | Tear down Langfuse Docker      |
+| `status` | See if containers are running  |
+
+## Autonomous Workflow
+
+### Health Gate (Mandatory First Step)
+
+> [!CAUTION]
+> **ALWAYS check status before attempting to trace.** If `status: stopped`, propose `start` to the user before proceeding to link metrics.
+
+```
+run.py status → running?
+  → true:  proceed to query or show link
+  → false: tell user "Langfuse is not running. I will start it via Docker Compose."
+           → run.py start → Verify localhost:3000 is open
+```
+
+### On "Monitor LLM" or "See how it is performing":
+
+1. **Check if Langfuse container status is running** — `run.py status`. 
+2. **Launch Langfuse** — If down, `run.py start`.
+3. **Instruct the User** — Direct the user to go to `http://localhost:3000`, register an admin account (in local dev mode, first login creates the admin account), and generate API keys.
+4. **Hook it into the code** — Using the provided API keys, instrument the project code (via LiteLLM proxy, OpenAI SDK wrapper, or directly with Langfuse Python/TS SDKs).
+5. **Run tests/Agents** — Execute the standard project agent flow so traces start flowing.
+6. **Review Dashboard** — The user can verify LLM cost, generation latency, and full prompt structures via the trace Explorer.
+
+## Troubleshooting
+
+| Problem                  | Solution                                                |
+| ------------------------ | ------------------------------------------------------- |
+| Port 3000 blocked        | Edit `docker-compose.yml` mapped ports                  |
+| Docker not running       | Agent must prompt user to start Docker engine natively  |
+| Traces not captured      | Ensure `LANGFUSE_HOST` specifically says `http://` and points to the exposed port |
+| Database errors          | Container db `langfuse_db_data` might need to be erased. Stop and rm volumes. |
+
+## AGI Framework Integration
+
+### Qdrant Memory Integration
+
+Before running deep diagnostics:
+```bash
+python3 execution/memory_manager.py auto --query "Local Langfuse observability setup and tracing configuration"
+```
+
+If you fix an issue regarding missing traces or misconfigured environments, save the resolution:
+```bash
+python3 execution/memory_manager.py store \
+  --content "Resolved Langfuse trace missing by pointing LANGFUSE_HOST explicitly to http://localhost:3000 and removing trailing slash" \
+  --type error \
+  --tags debug-llm langfuse observability docker
+```

package/templates/skills/knowledge/ai-agents/debug-llm/assets/example_asset.txt

@@ -0,0 +1,24 @@
+# Example Asset File
+
+This placeholder represents where asset files would be stored.
+Replace with actual asset files (templates, images, fonts, etc.) or delete if not needed.
+
+Asset files are NOT intended to be loaded into context, but rather used within
+the output Claude produces.
+
+Example asset files from other skills:
+- Brand guidelines: logo.png, slides_template.pptx
+- Frontend builder: hello-world/ directory with HTML/React boilerplate
+- Typography: custom-font.ttf, font-family.woff2
+- Data: sample_data.csv, test_dataset.json
+
+## Common Asset Types
+
+- Templates: .pptx, .docx, boilerplate directories
+- Images: .png, .jpg, .svg, .gif
+- Fonts: .ttf, .otf, .woff, .woff2
+- Boilerplate code: Project directories, starter files
+- Icons: .ico, .svg
+- Data files: .csv, .json, .xml, .yaml
+
+Note: This is a text placeholder. Actual assets can be any file type.

package/templates/skills/knowledge/ai-agents/debug-llm/docker-compose.yml

@@ -0,0 +1,56 @@
+version: '3.8'
+
+services:
+  langfuse-server:
+    image: ghcr.io/langfuse/langfuse:latest
+    depends_on:
+      db:
+        condition: service_healthy
+      minio:
+        condition: service_started
+    ports:
+      - "3000:3000"
+    environment:
+      - DATABASE_URL=postgresql://postgres:postgres@db:5432/postgres
+      - NEXTAUTH_SECRET=myawesome-nextauth-secret
+      - SALT=myawesome-salt
+      - NEXTAUTH_URL=http://localhost:3000
+      - TELEMETRY_ENABLED=false
+      - LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES=true
+      - LANGFUSE_S3_MEDIA_BUCKET_NAME=langfuse
+      - LANGFUSE_S3_MEDIA_BUCKET_REGION=us-east-1
+      - LANGFUSE_S3_MEDIA_ENDPOINT=http://minio:9000
+      - LANGFUSE_S3_MEDIA_ACCESS_KEY_ID=minioadmin
+      - LANGFUSE_S3_MEDIA_SECRET_ACCESS_KEY=minioadmin
+
+  minio:
+    image: minio/minio:latest
+    ports:
+      - "9000:9000"
+      - "9001:9001"
+    environment:
+      - MINIO_ROOT_USER=minioadmin
+      - MINIO_ROOT_PASSWORD=minioadmin
+    command: server /data --console-address ":9001"
+    volumes:
+      - langfuse_minio_data:/data
+
+  db:
+    image: postgres:15
+    environment:
+      - POSTGRES_USER=postgres
+      - POSTGRES_PASSWORD=postgres
+      - POSTGRES_DB=postgres
+    ports:
+      - "5432:5432"
+    volumes:
+      - langfuse_db_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  langfuse_db_data:
+  langfuse_minio_data:

package/templates/skills/knowledge/ai-agents/debug-llm/references/api_reference.md

@@ -0,0 +1,34 @@
+# Reference Documentation for Debug Llm
+
+This is a placeholder for detailed reference documentation.
+Replace with actual reference content or delete if not needed.
+
+Example real reference docs from other skills:
+- product-management/references/communication.md - Comprehensive guide for status updates
+- product-management/references/context_building.md - Deep-dive on gathering context
+- bigquery/references/ - API references and query examples
+
+## When Reference Docs Are Useful
+
+Reference docs are ideal for:
+- Comprehensive API documentation
+- Detailed workflow guides
+- Complex multi-step processes
+- Information too lengthy for main SKILL.md
+- Content that's only needed for specific use cases
+
+## Structure Suggestions
+
+### API Reference Example
+- Overview
+- Authentication
+- Endpoints with examples
+- Error codes
+- Rate limits
+
+### Workflow Guide Example
+- Prerequisites
+- Step-by-step instructions
+- Common patterns
+- Troubleshooting
+- Best practices

package/templates/skills/knowledge/ai-agents/debug-llm/scripts/run.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""
+Script: run.py
+Purpose: Manage the local Langfuse Docker Compose stack for the debug-llm skill.
+
+Usage:
+    python scripts/run.py {start|stop|status}
+
+Arguments:
+    start   - Starts the Langfuse infrastructure via docker-compose
+    stop    - Stops the Langfuse infrastructure
+    status  - Checks the status of the containers
+"""
+
+import os
+import sys
+import subprocess
+from pathlib import Path
+
+def get_compose_file():
+    # assumes this is executed from root or correctly mapped
+    # script path: ai-agents/debug-llm/scripts/run.py
+    script_dir = Path(__file__).resolve().parent
+    return script_dir.parent / "docker-compose.yml"
+
+def run_compose(command):
+    compose_file = get_compose_file()
+    if not compose_file.exists():
+        print(f"Error: {compose_file} not found.", file=sys.stderr)
+        sys.exit(1)
+
+    cmd = ["docker", "compose", "-f", str(compose_file)] + command
+    try:
+        subprocess.run(cmd, check=True)
+    except subprocess.CalledProcessError as e:
+        print(f"Command failed with exit code {e.returncode}", file=sys.stderr)
+        sys.exit(e.returncode)
+    except FileNotFoundError:
+        print("Error: 'docker' or 'docker-compose' command not found. Please ensure Docker is installed.", file=sys.stderr)
+        sys.exit(1)
+
+def main():
+    if len(sys.argv) < 2:
+        print(__doc__)
+        sys.exit(1)
+
+    action = sys.argv[1].lower()
+
+    if action == "start":
+        print("Starting Langfuse locally...")
+        run_compose(["up", "-d"])
+        print("\nLangfuse is starting. It may take a minute for the DB to initialize.")
+        print("Once healthy, visit: http://localhost:3000")
+        print("You will need to create a new admin account on the first run.")
+
+    elif action == "stop":
+        print("Stopping Langfuse...")
+        run_compose(["down"])
+
+    elif action == "status":
+        print("Checking Langfuse status...")
+        run_compose(["ps"])
+
+    else:
+        print(f"Unknown action: {action}", file=sys.stderr)
+        print(__doc__)
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()