@techwavedev/agi-agent-kit 1.1.7 → 1.2.1

package/templates/base/execution/session_init.py

@@ -0,0 +1,320 @@
+#!/usr/bin/env python3
+"""
+Script: session_init.py
+Purpose: Bootstrap script for AI agent sessions. Checks prerequisites and
+         initializes Qdrant collections with correct dimensions for the
+         configured embedding provider (defaults to Ollama/768d).
+
+Usage:
+    # Full initialization (check + create collections)
+    python3 execution/session_init.py
+
+    # Check only (no collection creation)
+    python3 execution/session_init.py --check-only
+
+    # Force re-initialization
+    python3 execution/session_init.py --force
+
+Environment Variables:
+    EMBEDDING_PROVIDER  - "ollama" (default), "openai", or "bedrock"
+    OLLAMA_URL          - Ollama server URL (default: http://localhost:11434)
+    QDRANT_URL          - Qdrant server URL (default: http://localhost:6333)
+
+Exit Codes:
+    0 - Success (all systems ready)
+    1 - Partial success (some checks failed but non-critical)
+    2 - Critical failure (Qdrant or embeddings not available)
+"""
+
+import argparse
+import json
+import os
+import sys
+from urllib.request import Request, urlopen
+from urllib.error import URLError, HTTPError
+
+# Resolve path to qdrant-memory scripts
+SKILL_SCRIPTS_DIR = os.path.join(
+    os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
+    "skills",
+    "qdrant-memory",
+    "scripts",
+)
+sys.path.insert(0, SKILL_SCRIPTS_DIR)
+
+from embedding_utils import (
+    check_embedding_service,
+    get_embedding_dimension,
+    EMBEDDING_PROVIDER,
+    EMBEDDING_MODEL,
+)
+from init_collection import create_collection, create_payload_index
+
+# Configuration
+QDRANT_URL = os.environ.get("QDRANT_URL", "http://localhost:6333")
+COLLECTIONS = ["agent_memory", "semantic_cache"]
+
+
+def check_qdrant() -> dict:
+    """Check if Qdrant is running and accessible."""
+    try:
+        req = Request(f"{QDRANT_URL}/collections", method="GET")
+        with urlopen(req, timeout=10) as response:
+            data = json.loads(response.read().decode())
+            existing = [
+                c["name"] for c in data.get("result", {}).get("collections", [])
+            ]
+            return {"status": "ok", "url": QDRANT_URL, "existing_collections": existing}
+    except URLError as e:
+        return {
+            "status": "error",
+            "url": QDRANT_URL,
+            "message": str(e),
+            "fix": "docker run -d -p 6333:6333 -p 6334:6334 -v qdrant_storage:/qdrant/storage qdrant/qdrant",
+        }
+
+
+def check_ollama() -> dict:
+    """Check if Ollama is running and has the embedding model."""
+    embed_status = check_embedding_service()
+
+    if embed_status.get("status") == "ok":
+        return embed_status
+
+    if embed_status.get("status") == "missing_model":
+        embed_status["fix"] = f"ollama pull {EMBEDDING_MODEL}"
+        return embed_status
+
+    if embed_status.get("status") == "connection_error":
+        embed_status["fix"] = "Install and start Ollama: https://ollama.ai"
+        return embed_status
+
+    return embed_status
+
+
+def init_collections(force: bool = False) -> list:
+    """Initialize required Qdrant collections with correct dimensions."""
+    dimension = get_embedding_dimension()
+    results = []
+
+    for collection_name in COLLECTIONS:
+        # Check if collection already exists
+        try:
+            req = Request(f"{QDRANT_URL}/collections/{collection_name}", method="GET")
+            with urlopen(req, timeout=10) as response:
+                data = json.loads(response.read().decode())
+                existing_dim = (
+                    data.get("result", {})
+                    .get("config", {})
+                    .get("params", {})
+                    .get("vectors", {})
+                    .get("size")
+                )
+
+                if existing_dim and existing_dim != dimension and force:
+                    # Delete and recreate with correct dimensions
+                    del_req = Request(
+                        f"{QDRANT_URL}/collections/{collection_name}", method="DELETE"
+                    )
+                    urlopen(del_req, timeout=10)
+                    print(
+                        f"  Deleted {collection_name} (was {existing_dim}d, need {dimension}d)"
+                    )
+                elif existing_dim == dimension:
+                    results.append(
+                        {
+                            "collection": collection_name,
+                            "status": "exists",
+                            "dimension": existing_dim,
+                        }
+                    )
+                    continue
+                elif existing_dim and existing_dim != dimension and not force:
+                    results.append(
+                        {
+                            "collection": collection_name,
+                            "status": "dimension_mismatch",
+                            "current": existing_dim,
+                            "expected": dimension,
+                            "fix": f"Run with --force to recreate with {dimension}d",
+                        }
+                    )
+                    continue
+        except HTTPError as e:
+            if e.code != 404:
+                results.append(
+                    {
+                        "collection": collection_name,
+                        "status": "error",
+                        "message": str(e),
+                    }
+                )
+                continue
+        except URLError:
+            results.append(
+                {
+                    "collection": collection_name,
+                    "status": "error",
+                    "message": "Cannot connect to Qdrant",
+                }
+            )
+            continue
+
+        # Create collection
+        try:
+            create_result = create_collection(
+                QDRANT_URL, collection_name, dimension, "cosine"
+            )
+
+            # Create standard payload indexes
+            indexes = [
+                ("type", "keyword"),
+                ("project", "keyword"),
+                ("timestamp", "datetime"),
+                ("tags", "keyword"),
+                ("model", "keyword"),
+                ("token_count", "integer"),
+            ]
+
+            for field, field_type in indexes:
+                create_payload_index(QDRANT_URL, collection_name, field, field_type)
+
+            results.append(
+                {
+                    "collection": collection_name,
+                    "status": "created",
+                    "dimension": dimension,
+                    "indexes": len(indexes),
+                }
+            )
+        except Exception as e:
+            results.append(
+                {"collection": collection_name, "status": "error", "message": str(e)}
+            )
+
+    return results
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Initialize AI agent session (Qdrant + Ollama check + collection setup)"
+    )
+    parser.add_argument(
+        "--check-only",
+        action="store_true",
+        help="Only check prerequisites, don't create collections",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Force re-initialization (recreate collections)",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output as JSON only (no human-readable messages)",
+    )
+    args = parser.parse_args()
+
+    report = {
+        "provider": EMBEDDING_PROVIDER,
+        "model": EMBEDDING_MODEL,
+        "dimension": get_embedding_dimension(),
+        "qdrant": {},
+        "embeddings": {},
+        "collections": [],
+        "ready": False,
+    }
+
+    # Step 1: Check Qdrant
+    if not args.json:
+        print(f"Checking Qdrant at {QDRANT_URL}...")
+    qdrant_status = check_qdrant()
+    report["qdrant"] = qdrant_status
+
+    if qdrant_status["status"] != "ok":
+        if not args.json:
+            print(f"  FAILED: {qdrant_status.get('message', 'Unknown error')}")
+            print(f"  FIX: {qdrant_status.get('fix', 'Check Qdrant installation')}")
+        if args.json:
+            print(json.dumps(report, indent=2))
+        sys.exit(2)
+    else:
+        if not args.json:
+            print(f"  OK. Collections: {qdrant_status.get('existing_collections', [])}")
+
+    # Step 2: Check embedding service
+    if not args.json:
+        print(f"Checking embedding service ({EMBEDDING_PROVIDER}/{EMBEDDING_MODEL})...")
+    embed_status = check_ollama()
+    report["embeddings"] = embed_status
+
+    if embed_status.get("status") != "ok":
+        if not args.json:
+            print(f"  FAILED: {embed_status.get('message', 'Unknown error')}")
+            if embed_status.get("fix"):
+                print(f"  FIX: {embed_status['fix']}")
+        if args.json:
+            print(json.dumps(report, indent=2))
+        sys.exit(2)
+    else:
+        if not args.json:
+            print(f"  OK. Model: {EMBEDDING_MODEL} ({get_embedding_dimension()}d)")
+
+    # Step 3: Initialize collections
+    if not args.check_only:
+        if not args.json:
+            print(
+                f"Initializing collections (dimension={get_embedding_dimension()})..."
+            )
+        collection_results = init_collections(force=args.force)
+        report["collections"] = collection_results
+
+        for cr in collection_results:
+            if not args.json:
+                status = cr["status"]
+                name = cr["collection"]
+                if status == "created":
+                    print(
+                        f"  CREATED: {name} ({cr['dimension']}d, {cr['indexes']} indexes)"
+                    )
+                elif status == "exists":
+                    print(f"  EXISTS: {name} ({cr['dimension']}d)")
+                elif status == "dimension_mismatch":
+                    print(
+                        f"  MISMATCH: {name} (current={cr['current']}d, expected={cr['expected']}d)"
+                    )
+                    print(f"    FIX: {cr.get('fix', '')}")
+                else:
+                    print(f"  ERROR: {name} - {cr.get('message', '')}")
+    else:
+        if not args.json:
+            print("Skipping collection initialization (--check-only)")
+
+    # Final status
+    all_ok = qdrant_status["status"] == "ok" and embed_status.get("status") == "ok"
+
+    if not args.check_only:
+        all_ok = all_ok and all(
+            cr["status"] in ("created", "exists")
+            for cr in report.get("collections", [])
+        )
+
+    report["ready"] = all_ok
+
+    if not args.json:
+        if all_ok:
+            print(f"\nSession initialized. Memory system ready.")
+            print(f"  Provider: {EMBEDDING_PROVIDER} ({EMBEDDING_MODEL})")
+            print(f"  Dimension: {get_embedding_dimension()}")
+            print(f"  Qdrant: {QDRANT_URL}")
+        else:
+            print(f"\nSession initialization incomplete. See errors above.")
+    else:
+        print(json.dumps(report, indent=2))
+
+    sys.exit(0 if all_ok else 1)
+
+
+if __name__ == "__main__":
+    main()

package/templates/base/skill-creator/SKILL_skillcreator.md

@@ -1,6 +1,6 @@
 ---
 name: skill-creator
-description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends the agent's capabilities with specialized knowledge, workflows, or tool integrations.
+description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
 license: Complete terms in LICENSE.txt
 ---
 
@@ -10,9 +10,9 @@ This skill provides guidance for creating effective skills.
 
 ## About Skills
 
-Skills are modular, self-contained packages that extend the agent's capabilities by providing
+Skills are modular, self-contained packages that extend Claude's capabilities by providing
 specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific
-domains or tasks—they transform the agent from a general-purpose agent into a specialized agent
+domains or tasks—they transform Claude from a general-purpose agent into a specialized agent
 equipped with procedural knowledge that no model can fully possess.
 
 ### What Skills Provide
@@ -26,9 +26,9 @@ equipped with procedural knowledge that no model can fully possess.
 
 ### Concise is Key
 
-The context window is a public good. Skills share the context window with everything else the agent needs: system prompt, conversation history, other Skills' metadata, and the actual user request.
+The context window is a public good. Skills share the context window with everything else Claude needs: system prompt, conversation history, other Skills' metadata, and the actual user request.
 
-**Default assumption: the agent is already very smart.** Only add context the agent doesn't already have. Challenge each piece of information: "Does the agent really need this explanation?" and "Does this paragraph justify its token cost?"
+**Default assumption: Claude is already very smart.** Only add context Claude doesn't already have. Challenge each piece of information: "Does Claude really need this explanation?" and "Does this paragraph justify its token cost?"
 
 Prefer concise examples over verbose explanations.
 
@@ -42,7 +42,7 @@ Match the level of specificity to the task's fragility and variability:
 
 **Low freedom (specific scripts, few parameters)**: Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.
 
-Think of the agent as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).
+Think of Claude as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).
 
 ### Anatomy of a Skill
 
@@ -65,7 +65,7 @@ skill-name/
 
 Every SKILL.md consists of:
 
-- **Frontmatter** (YAML): Contains `name` and `description` fields. These are the only fields that the agent reads to determine when the skill gets used, thus it is very important to be clear and comprehensive in describing what the skill is, and when it should be used.
+- **Frontmatter** (YAML): Contains `name` and `description` fields. These are the only fields that Claude reads to determine when the skill gets used, thus it is very important to be clear and comprehensive in describing what the skill is, and when it should be used.
 - **Body** (Markdown): Instructions and guidance for using the skill. Only loaded AFTER the skill triggers (if at all).
 
 #### Bundled Resources (optional)
@@ -77,27 +77,27 @@ Executable code (Python/Bash/etc.) for tasks that require deterministic reliabil
 - **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed
 - **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks
 - **Benefits**: Token efficient, deterministic, may be executed without loading into context
-- **Note**: Scripts may still need to be read by the agent for patching or environment-specific adjustments
+- **Note**: Scripts may still need to be read by Claude for patching or environment-specific adjustments
 
 ##### References (`references/`)
 
-Documentation and reference material intended to be loaded as needed into context to inform the agent's process and thinking.
+Documentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking.
 
-- **When to include**: For documentation that the agent should reference while working
+- **When to include**: For documentation that Claude should reference while working
 - **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications
 - **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
-- **Benefits**: Keeps SKILL.md lean, loaded only when the agent determines it's needed
+- **Benefits**: Keeps SKILL.md lean, loaded only when Claude determines it's needed
 - **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md
 - **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.
 
 ##### Assets (`assets/`)
 
-Files not intended to be loaded into context, but rather used within the output the agent produces.
+Files not intended to be loaded into context, but rather used within the output Claude produces.
 
 - **When to include**: When the skill needs files that will be used in the final output
 - **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography
 - **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified
-- **Benefits**: Separates output resources from documentation, enables the agent to use files without loading them into context
+- **Benefits**: Separates output resources from documentation, enables Claude to use files without loading them into context
 
 #### What to Not Include in a Skill
 
@@ -117,7 +117,7 @@ Skills use a three-level loading system to manage context efficiently:
 
 1. **Metadata (name + description)** - Always in context (~100 words)
 2. **SKILL.md body** - When skill triggers (<5k words)
-3. **Bundled resources** - As needed by the agent (Unlimited because scripts can be executed without reading into context window)
+3. **Bundled resources** - As needed by Claude (Unlimited because scripts can be executed without reading into context window)
 
 #### Progressive Disclosure Patterns
 
@@ -142,7 +142,7 @@ Extract text with pdfplumber:
 - **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns
 ```
 
-The agent loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.
+Claude loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.
 
 **Pattern 2: Domain-specific organization**
 
@@ -158,7 +158,7 @@ bigquery-skill/
     └── marketing.md (campaigns, attribution)
 ```
 
-When a user asks about sales metrics, the agent only reads sales.md.
+When a user asks about sales metrics, Claude only reads sales.md.
 
 Similarly, for skills supporting multiple frameworks or variants, organize by variant:
 
@@ -171,7 +171,7 @@ cloud-deploy/
     └── azure.md (Azure deployment patterns)
 ```
 
-When the user chooses AWS, the agent only reads aws.md.
+When the user chooses AWS, Claude only reads aws.md.
 
 **Pattern 3: Conditional details**
 
@@ -192,12 +192,12 @@ For simple edits, modify the XML directly.
 **For OOXML details**: See [OOXML.md](OOXML.md)
 ```
 
-The agent reads REDLINING.md or OOXML.md only when the user needs those features.
+Claude reads REDLINING.md or OOXML.md only when the user needs those features.
 
 **Important guidelines:**
 
 - **Avoid deeply nested references** - Keep references one level deep from SKILL.md. All reference files should link directly from SKILL.md.
-- **Structure longer reference files** - For files longer than 100 lines, include a table of contents at the top so the agent can see the full scope when previewing.
+- **Structure longer reference files** - For files longer than 100 lines, include a table of contents at the top so Claude can see the full scope when previewing.
 
 ## Skill Creation Process
 
@@ -266,12 +266,6 @@ Usage:
 
 ```bash
 scripts/init_skill.py <skill-name> --path <output-directory>
-
-# Skip automatic catalog/docs updates
-scripts/init_skill.py <skill-name> --path <output-directory> --no-auto-update
-
-# Specify skills directory for catalog updates (if different from --path)
-scripts/init_skill.py <skill-name> --path <output-directory> --skills-dir skills/
 ```
 
 The script:
@@ -280,20 +274,16 @@ The script:
 - Generates a SKILL.md template with proper frontmatter and TODO placeholders
 - Creates example resource directories: `scripts/`, `references/`, and `assets/`
 - Adds example files in each directory that can be customized or deleted
-- **Auto-runs `update_catalog.py`** to regenerate `SKILLS_CATALOG.md` (default ON)
-- **Auto-runs `sync_docs.py`** to synchronize documentation (default ON, if documentation skill exists)
-
-> **Note:** Use `--no-auto-update` to skip automatic catalog and documentation updates.
 
 After initialization, customize or remove the generated SKILL.md and example files as needed.
 
 ### Step 4: Edit the Skill
 
-When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of the agent to use. Include information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another the agent instance execute these tasks more effectively.
+When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Claude to use. Include information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance execute these tasks more effectively.
 
 #### Learn Proven Design Patterns
 
-Consult these helpful guides based on your skill's needs:
+Refer to these helpful guides based on your skill's needs:
 
 - **Multi-step processes**: See references/workflows.md for sequential workflows and conditional logic
 - **Specific output formats or quality standards**: See references/output-patterns.md for template and example patterns
@@ -317,10 +307,10 @@ Any example files and directories not needed for the skill should be deleted. Th
 Write the YAML frontmatter with `name` and `description`:
 
 - `name`: The skill name
-- `description`: This is the primary triggering mechanism for your skill, and helps the agent understand when to use the skill.
+- `description`: This is the primary triggering mechanism for your skill, and helps Claude understand when to use the skill.
   - Include both what the Skill does and specific triggers/contexts for when to use it.
   - Include all "when to use" information here - Not in the body. The body is only loaded after triggering, so "When to Use This Skill" sections in the body are not helpful to Claude.
-  - Example description for a `docx` skill: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when the agent needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks"
+  - Example description for a `docx` skill: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when Claude needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks"
 
 Do not include any other fields in YAML frontmatter.
 
@@ -358,10 +348,7 @@ If validation fails, the script will report the errors and exit without creating
 
 **CRITICAL:** After any skill operation (create, modify, or delete), the Skills Catalog must be updated. This ensures all skills are discoverable and documented.
 
-> **For new skills:** `init_skill.py` now auto-runs catalog and documentation updates by default. Manual update is only needed when modifying or deleting existing skills.
-
 ```bash
-# Manual update (for modifications/deletions, or if --no-auto-update was used)
 scripts/update_catalog.py --skills-dir skills/
 ```