@namch/agent-assistant 1.0.0 → 1.0.2

package/skills/prompt-engineering/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: prompt-engineering
+description: Expert guide on prompt engineering patterns, best practices, and optimization techniques. Use when user wants to improve prompts, learn prompting strategies, or debug agent behavior.
+---
+
+# Prompt Engineering Patterns
+
+Advanced prompt engineering techniques to maximize LLM performance, reliability, and controllability.
+
+## Core Capabilities
+
+### 1. Few-Shot Learning
+
+Teach the model by showing examples instead of explaining rules. Include 2-5 input-output pairs that demonstrate the desired behavior. Use when you need consistent formatting, specific reasoning patterns, or handling of edge cases. More examples improve accuracy but consume tokens—balance based on task complexity.
+
+**Example:**
+
+```markdown
+Extract key information from support tickets:
+
+Input: "My login doesn't work and I keep getting error 403"
+Output: {"issue": "authentication", "error_code": "403", "priority": "high"}
+
+Input: "Feature request: add dark mode to settings"
+Output: {"issue": "feature_request", "error_code": null, "priority": "low"}
+
+Now process: "Can't upload files larger than 10MB, getting timeout"
+```
+
+### 2. Chain-of-Thought Prompting
+
+Request step-by-step reasoning before the final answer. Add "Let's think step by step" (zero-shot) or include example reasoning traces (few-shot). Use for complex problems requiring multi-step logic, mathematical reasoning, or when you need to verify the model's thought process. Improves accuracy on analytical tasks by 30-50%.
+
+**Example:**
+
+```markdown
+Analyze this bug report and determine root cause.
+
+Think step by step:
+
+1. What is the expected behavior?
+2. What is the actual behavior?
+3. What changed recently that could cause this?
+4. What components are involved?
+5. What is the most likely root cause?
+
+Bug: "Users can't save drafts after the cache update deployed yesterday"
+```
+
+### 3. Prompt Optimization
+
+Systematically improve prompts through testing and refinement. Start simple, measure performance (accuracy, consistency, token usage), then iterate. Test on diverse inputs including edge cases. Use A/B testing to compare variations. Critical for production prompts where consistency and cost matter.
+
+**Example:**
+
+```markdown
+Version 1 (Simple): "Summarize this article"
+→ Result: Inconsistent length, misses key points
+
+Version 2 (Add constraints): "Summarize in 3 bullet points"
+→ Result: Better structure, but still misses nuance
+
+Version 3 (Add reasoning): "Identify the 3 main findings, then summarize each"
+→ Result: Consistent, accurate, captures key information
+```
+
+### 4. Template Systems
+
+Build reusable prompt structures with variables, conditional sections, and modular components. Use for multi-turn conversations, role-based interactions, or when the same pattern applies to different inputs. Reduces duplication and ensures consistency across similar tasks.
+
+**Example:**
+
+```python
+# Reusable code review template
+template = """
+Review this {language} code for {focus_area}.
+
+Code:
+{code_block}
+
+Provide feedback on:
+{checklist}
+"""
+
+# Usage
+prompt = template.format(
+    language="Python",
+    focus_area="security vulnerabilities",
+    code_block=user_code,
+    checklist="1. SQL injection\n2. XSS risks\n3. Authentication"
+)
+```
+
+### 5. System Prompt Design
+
+Set global behavior and constraints that persist across the conversation. Define the model's role, expertise level, output format, and safety guidelines. Use system prompts for stable instructions that shouldn't change turn-to-turn, freeing up user message tokens for variable content.
+
+**Example:**
+
+```markdown
+System: You are a senior backend engineer specializing in API design.
+
+Rules:
+
+- Always consider scalability and performance
+- Suggest RESTful patterns by default
+- Flag security concerns immediately
+- Provide code examples in Python
+- Use early return pattern
+
+Format responses as:
+
+1. Analysis
+2. Recommendation
+3. Code example
+4. Trade-offs
+```
+
+## Key Patterns
+
+### Progressive Disclosure
+
+Start with simple prompts, add complexity only when needed:
+
+1. **Level 1**: Direct instruction
+
+   - "Summarize this article"
+
+2. **Level 2**: Add constraints
+
+   - "Summarize this article in 3 bullet points, focusing on key findings"
+
+3. **Level 3**: Add reasoning
+
+   - "Read this article, identify the main findings, then summarize in 3 bullet points"
+
+4. **Level 4**: Add examples
+   - Include 2-3 example summaries with input-output pairs
+
+### Instruction Hierarchy
+
+```
+[System Context] → [Task Instruction] → [Examples] → [Input Data] → [Output Format]
+```
+
+### Error Recovery
+
+Build prompts that gracefully handle failures:
+
+- Include fallback instructions
+- Request confidence scores
+- Ask for alternative interpretations when uncertain
+- Specify how to indicate missing information
+
+## Best Practices
+
+1. **Be Specific**: Vague prompts produce inconsistent results
+2. **Show, Don't Tell**: Examples are more effective than descriptions
+3. **Test Extensively**: Evaluate on diverse, representative inputs
+4. **Iterate Rapidly**: Small changes can have large impacts
+5. **Monitor Performance**: Track metrics in production
+6. **Version Control**: Treat prompts as code with proper versioning
+7. **Document Intent**: Explain why prompts are structured as they are
+
+## Common Pitfalls
+
+- **Over-engineering**: Starting with complex prompts before trying simple ones
+- **Example pollution**: Using examples that don't match the target task
+- **Context overflow**: Exceeding token limits with excessive examples
+- **Ambiguous instructions**: Leaving room for multiple interpretations
+- **Ignoring edge cases**: Not testing on unusual or boundary inputs

package/skills/prompt-library/SKILL.md

@@ -0,0 +1,322 @@
+---
+name: prompt-library
+description: "Curated collection of high-quality prompts for various use cases. Includes role-based prompts, task-specific templates, and prompt refinement techniques. Use when user needs prompt templates, role-play prompts, or ready-to-use prompt examples for coding, writing, analysis, or creative tasks."
+---
+
+# 📝 Prompt Library
+
+> A comprehensive collection of battle-tested prompts inspired by [awesome-chatgpt-prompts](https://github.com/f/awesome-chatgpt-prompts) and community best practices.
+
+## When to Use This Skill
+
+Use this skill when the user:
+
+- Needs ready-to-use prompt templates
+- Wants role-based prompts (act as X)
+- Asks for prompt examples or inspiration
+- Needs task-specific prompt patterns
+- Wants to improve their prompting
+
+## Prompt Categories
+
+### 🎭 Role-Based Prompts
+
+#### Expert Developer
+
+```
+Act as an expert software developer with 15+ years of experience. You specialize in clean code, SOLID principles, and pragmatic architecture. When reviewing code:
+1. Identify bugs and potential issues
+2. Suggest performance improvements
+3. Recommend better patterns
+4. Explain your reasoning clearly
+Always prioritize readability and maintainability over cleverness.
+```
+
+#### Code Reviewer
+
+```
+Act as a senior code reviewer. Your role is to:
+1. Check for bugs, edge cases, and error handling
+2. Evaluate code structure and organization
+3. Assess naming conventions and readability
+4. Identify potential security issues
+5. Suggest improvements with specific examples
+
+Format your review as:
+🔴 Critical Issues (must fix)
+🟡 Suggestions (should consider)
+🟢 Praise (what's done well)
+```
+
+#### Technical Writer
+
+```
+Act as a technical documentation expert. Transform complex technical concepts into clear, accessible documentation. Follow these principles:
+- Use simple language, avoid jargon
+- Include practical examples
+- Structure with clear headings
+- Add code snippets where helpful
+- Consider the reader's experience level
+```
+
+#### System Architect
+
+```
+Act as a senior system architect designing for scale. Consider:
+- Scalability (horizontal and vertical)
+- Reliability (fault tolerance, redundancy)
+- Maintainability (modularity, clear boundaries)
+- Performance (latency, throughput)
+- Cost efficiency
+
+Provide architecture decisions with trade-off analysis.
+```
+
+### 🛠️ Task-Specific Prompts
+
+#### Debug This Code
+
+```
+Debug the following code. Your analysis should include:
+
+1. **Problem Identification**: What exactly is failing?
+2. **Root Cause**: Why is it failing?
+3. **Fix**: Provide corrected code
+4. **Prevention**: How to prevent similar bugs
+
+Show your debugging thought process step by step.
+```
+
+#### Explain Like I'm 5 (ELI5)
+
+```
+Explain [CONCEPT] as if I'm 5 years old. Use:
+- Simple everyday analogies
+- No technical jargon
+- Short sentences
+- Relatable examples from daily life
+- A fun, engaging tone
+```
+
+#### Code Refactoring
+
+```
+Refactor this code following these priorities:
+1. Readability first
+2. Remove duplication (DRY)
+3. Single responsibility per function
+4. Meaningful names
+5. Add comments only where necessary
+
+Show before/after with explanation of changes.
+```
+
+#### Write Tests
+
+```
+Write comprehensive tests for this code:
+1. Happy path scenarios
+2. Edge cases
+3. Error conditions
+4. Boundary values
+
+Use [FRAMEWORK] testing conventions. Include:
+- Descriptive test names
+- Arrange-Act-Assert pattern
+- Mocking where appropriate
+```
+
+#### API Documentation
+
+```
+Generate API documentation for this endpoint including:
+- Endpoint URL and method
+- Request parameters (path, query, body)
+- Request/response examples
+- Error codes and meanings
+- Authentication requirements
+- Rate limits if applicable
+
+Format as OpenAPI/Swagger or Markdown.
+```
+
+### 📊 Analysis Prompts
+
+#### Code Complexity Analysis
+
+```
+Analyze the complexity of this codebase:
+
+1. **Cyclomatic Complexity**: Identify complex functions
+2. **Coupling**: Find tightly coupled components
+3. **Cohesion**: Assess module cohesion
+4. **Dependencies**: Map critical dependencies
+5. **Technical Debt**: Highlight areas needing refactoring
+
+Rate each area and provide actionable recommendations.
+```
+
+#### Performance Analysis
+
+```
+Analyze this code for performance issues:
+
+1. **Time Complexity**: Big O analysis
+2. **Space Complexity**: Memory usage patterns
+3. **I/O Bottlenecks**: Database, network, disk
+4. **Algorithmic Issues**: Inefficient patterns
+5. **Quick Wins**: Easy optimizations
+
+Prioritize findings by impact.
+```
+
+#### Security Review
+
+```
+Perform a security review of this code:
+
+1. **Input Validation**: Check all inputs
+2. **Authentication/Authorization**: Access control
+3. **Data Protection**: Sensitive data handling
+4. **Injection Vulnerabilities**: SQL, XSS, etc.
+5. **Dependencies**: Known vulnerabilities
+
+Classify issues by severity (Critical/High/Medium/Low).
+```
+
+### 🎨 Creative Prompts
+
+#### Brainstorm Features
+
+```
+Brainstorm features for [PRODUCT]:
+
+For each feature, provide:
+- Name and one-line description
+- User value proposition
+- Implementation complexity (Low/Med/High)
+- Dependencies on other features
+
+Generate 10 ideas, then rank top 3 by impact/effort ratio.
+```
+
+#### Name Generator
+
+```
+Generate names for [PROJECT/FEATURE]:
+
+Provide 10 options in these categories:
+- Descriptive (what it does)
+- Evocative (how it feels)
+- Acronyms (memorable abbreviations)
+- Metaphorical (analogies)
+
+For each, explain the reasoning and check domain availability patterns.
+```
+
+### 🔄 Transformation Prompts
+
+#### Migrate Code
+
+```
+Migrate this code from [SOURCE] to [TARGET]:
+
+1. Identify equivalent constructs
+2. Handle incompatible features
+3. Preserve functionality exactly
+4. Follow target language idioms
+5. Add necessary dependencies
+
+Show the migration step by step with explanations.
+```
+
+#### Convert Format
+
+```
+Convert this [SOURCE_FORMAT] to [TARGET_FORMAT]:
+
+Requirements:
+- Preserve all data
+- Use idiomatic target format
+- Handle edge cases
+- Validate the output
+- Provide sample verification
+```
+
+## Prompt Engineering Techniques
+
+### Chain of Thought (CoT)
+
+```
+Let's solve this step by step:
+1. First, I'll understand the problem
+2. Then, I'll identify the key components
+3. Next, I'll work through the logic
+4. Finally, I'll verify the solution
+
+[Your question here]
+```
+
+### Few-Shot Learning
+
+```
+Here are some examples of the task:
+
+Example 1:
+Input: [example input 1]
+Output: [example output 1]
+
+Example 2:
+Input: [example input 2]
+Output: [example output 2]
+
+Now complete this:
+Input: [actual input]
+Output:
+```
+
+### Persona Pattern
+
+```
+You are [PERSONA] with [TRAITS].
+Your communication style is [STYLE].
+You prioritize [VALUES].
+
+When responding:
+- [Behavior 1]
+- [Behavior 2]
+- [Behavior 3]
+```
+
+### Structured Output
+
+```
+Respond in the following JSON format:
+{
+  "analysis": "your analysis here",
+  "recommendations": ["rec1", "rec2"],
+  "confidence": 0.0-1.0,
+  "caveats": ["caveat1"]
+}
+```
+
+## Prompt Improvement Checklist
+
+When crafting prompts, ensure:
+
+- [ ] **Clear objective**: What exactly do you want?
+- [ ] **Context provided**: Background information included?
+- [ ] **Format specified**: How should output be structured?
+- [ ] **Examples given**: Are there reference examples?
+- [ ] **Constraints defined**: Any limitations or requirements?
+- [ ] **Success criteria**: How do you measure good output?
+
+## Resources
+
+- [awesome-chatgpt-prompts](https://github.com/f/awesome-chatgpt-prompts)
+- [prompts.chat](https://prompts.chat)
+- [Learn Prompting](https://learnprompting.org/)
+
+---
+
+> 💡 **Tip**: The best prompts are specific, provide context, and include examples of desired output.

package/skills/rag-engineer/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: rag-engineer
+description: "Expert in building Retrieval-Augmented Generation systems. Masters embedding models, vector databases, chunking strategies, and retrieval optimization for LLM applications. Use when: building RAG, vector search, embeddings, semantic search, document retrieval."
+source: vibeship-spawner-skills (Apache 2.0)
+---
+
+# RAG Engineer
+
+**Role**: RAG Systems Architect
+
+I bridge the gap between raw documents and LLM understanding. I know that
+retrieval quality determines generation quality - garbage in, garbage out.
+I obsess over chunking boundaries, embedding dimensions, and similarity
+metrics because they make the difference between helpful and hallucinating.
+
+## Capabilities
+
+- Vector embeddings and similarity search
+- Document chunking and preprocessing
+- Retrieval pipeline design
+- Semantic search implementation
+- Context window optimization
+- Hybrid search (keyword + semantic)
+
+## Requirements
+
+- LLM fundamentals
+- Understanding of embeddings
+- Basic NLP concepts
+
+## Patterns
+
+### Semantic Chunking
+
+Chunk by meaning, not arbitrary token counts
+
+```javascript
+- Use sentence boundaries, not token limits
+- Detect topic shifts with embedding similarity
+- Preserve document structure (headers, paragraphs)
+- Include overlap for context continuity
+- Add metadata for filtering
+```
+
+### Hierarchical Retrieval
+
+Multi-level retrieval for better precision
+
+```javascript
+- Index at multiple chunk sizes (paragraph, section, document)
+- First pass: coarse retrieval for candidates
+- Second pass: fine-grained retrieval for precision
+- Use parent-child relationships for context
+```
+
+### Hybrid Search
+
+Combine semantic and keyword search
+
+```javascript
+- BM25/TF-IDF for keyword matching
+- Vector similarity for semantic matching
+- Reciprocal Rank Fusion for combining scores
+- Weight tuning based on query type
+```
+
+## Anti-Patterns
+
+### ❌ Fixed Chunk Size
+
+### ❌ Embedding Everything
+
+### ❌ Ignoring Evaluation
+
+## ⚠️ Sharp Edges
+
+| Issue | Severity | Solution |
+|-------|----------|----------|
+| Fixed-size chunking breaks sentences and context | high | Use semantic chunking that respects document structure: |
+| Pure semantic search without metadata pre-filtering | medium | Implement hybrid filtering: |
+| Using same embedding model for different content types | medium | Evaluate embeddings per content type: |
+| Using first-stage retrieval results directly | medium | Add reranking step: |
+| Cramming maximum context into LLM prompt | medium | Use relevance thresholds: |
+| Not measuring retrieval quality separately from generation | high | Separate retrieval evaluation: |
+| Not updating embeddings when source documents change | medium | Implement embedding refresh: |
+| Same retrieval strategy for all query types | medium | Implement hybrid search: |
+
+## Related Skills
+
+Works well with: `ai-agents-architect`, `prompt-engineer`, `database-architect`, `backend`

package/skills/rag-implementation/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: rag-implementation
+description: "Retrieval-Augmented Generation patterns including chunking, embeddings, vector stores, and retrieval optimization Use when: rag, retrieval augmented, vector search, embeddings, semantic search."
+source: vibeship-spawner-skills (Apache 2.0)
+---
+
+# RAG Implementation
+
+You're a RAG specialist who has built systems serving millions of queries over
+terabytes of documents. You've seen the naive "chunk and embed" approach fail,
+and developed sophisticated chunking, retrieval, and reranking strategies.
+
+You understand that RAG is not just vector search—it's about getting the right
+information to the LLM at the right time. You know when RAG helps and when
+it's unnecessary overhead.
+
+Your core principles:
+1. Chunking is critical—bad chunks mean bad retrieval
+2. Hybri
+
+## Capabilities
+
+- document-chunking
+- embedding-models
+- vector-stores
+- retrieval-strategies
+- hybrid-search
+- reranking
+
+## Patterns
+
+### Semantic Chunking
+
+Chunk by meaning, not arbitrary size
+
+### Hybrid Search
+
+Combine dense (vector) and sparse (keyword) search
+
+### Contextual Reranking
+
+Rerank retrieved docs with LLM for relevance
+
+## Anti-Patterns
+
+### ❌ Fixed-Size Chunking
+
+### ❌ No Overlap
+
+### ❌ Single Retrieval Strategy
+
+## ⚠️ Sharp Edges
+
+| Issue | Severity | Solution |
+|-------|----------|----------|
+| Poor chunking ruins retrieval quality | critical | // Use recursive character text splitter with overlap |
+| Query and document embeddings from different models | critical | // Ensure consistent embedding model usage |
+| RAG adds significant latency to responses | high | // Optimize RAG latency |
+| Documents updated but embeddings not refreshed | medium | // Maintain sync between documents and embeddings |
+
+## Related Skills
+
+Works well with: `context-window-management`, `conversation-memory`, `prompt-caching`, `data-pipeline`