@agentskillkit/agent-skills 1.0.1 → 3.2.1

package/.agent/skills/context-engineering/references/context-optimization.md

@@ -1,82 +0,0 @@
-# Context Optimization
-
-Extend effective context capacity through strategic techniques.
-
-## Four Core Strategies
-
-| Strategy | Target | Reduction | When to Use |
-|----------|--------|-----------|-------------|
-| **Compaction** | Full context | 50-70% | Approaching limits |
-| **Observation Masking** | Tool outputs | 60-80% | Verbose outputs >80% |
-| **KV-Cache Optimization** | Repeated prefixes | 70%+ hit | Stable prompts |
-| **Context Partitioning** | Work distribution | N/A | Parallelizable tasks |
-
-## Compaction
-
-Summarize context when approaching limits.
-
-**Priority**: Tool outputs → Old turns → Retrieved docs → Never: System prompt
-
-```python
-if context_tokens / context_limit > 0.8:
-    context = compact_context(context)
-```
-
-**Preserve**: Key findings, decisions, commitments (remove supporting details)
-
-## Observation Masking
-
-Replace verbose tool outputs with compact references.
-
-```python
-if len(observation) > max_length:
-    ref_id = store_observation(observation)
-    return f"[Obs:{ref_id}. Key: {extract_key(observation)}]"
-```
-
-**Never mask**: Current task critical, most recent turn, active reasoning
-**Always mask**: Repeated outputs, boilerplate, already summarized
-
-## KV-Cache Optimization
-
-Reuse cached Key/Value tensors for identical prefixes.
-
-```python
-# Cache-friendly ordering (stable first)
-context = [system_prompt, tool_definitions]  # Cacheable
-context += [unique_content]                   # Variable last
-```
-
-**Tips**: Avoid timestamps in stable sections, consistent formatting, stable structure
-
-## Context Partitioning
-
-Split work across sub-agents with isolated contexts.
-
-```python
-result = await sub_agent.process(subtask, clean_context=True)
-coordinator.receive(result.summary)  # Only essentials
-```
-
-## Decision Framework
-
-| Dominant Component | Apply |
-|-------------------|-------|
-| Tool outputs | Observation masking |
-| Retrieved docs | Summarization or partitioning |
-| Message history | Compaction + summarization |
-| Multiple | Combine strategies |
-
-## Guidelines
-
-1. Measure before optimizing
-2. Apply compaction before masking
-3. Design for cache stability
-4. Partition before context problematic
-5. Monitor effectiveness over time
-6. Balance savings vs quality
-
-## Related
-
-- [Context Compression](./context-compression.md)
-- [Memory Systems](./memory-systems.md)

package/.agent/skills/context-engineering/references/evaluation.md

@@ -1,89 +0,0 @@
-# Evaluation
-
-Systematically assess agent performance and context engineering choices.
-
-## Key Finding: 95% Performance Variance
-
-- **Token usage**: 80% of variance
-- **Tool calls**: ~10% of variance
-- **Model choice**: ~5% of variance
-
-**Implication**: Token budgets matter more than model upgrades.
-
-## Multi-Dimensional Rubric
-
-| Dimension | Weight | Description |
-|-----------|--------|-------------|
-| Factual Accuracy | 30% | Ground truth verification |
-| Completeness | 25% | Coverage of requirements |
-| Tool Efficiency | 20% | Appropriate tool usage |
-| Citation Accuracy | 15% | Sources match claims |
-| Source Quality | 10% | Authority/credibility |
-
-## Evaluation Methods
-
-### LLM-as-Judge
-
-Beware biases:
-- **Position**: First position preferred
-- **Length**: Longer = higher score
-- **Self-enhancement**: Rating own outputs higher
-- **Verbosity**: Detailed = better
-
-**Mitigation**: Position swapping, anti-bias prompting
-
-### Pairwise Comparison
-
-```python
-score_ab = judge.compare(output_a, output_b)
-score_ba = judge.compare(output_b, output_a)
-consistent = (score_ab > 0.5) != (score_ba > 0.5)
-```
-
-### Probe-Based Testing
-
-| Probe | Tests | Example |
-|-------|-------|---------|
-| Recall | Facts | "What was the error?" |
-| Artifact | Files | "Which files modified?" |
-| Continuation | Planning | "What's next?" |
-| Decision | Reasoning | "Why chose X?" |
-
-## Test Set Design
-
-```python
-class TestSet:
-    def sample_stratified(self, n):
-        per_level = n // 3
-        return (
-            sample(self.simple, per_level) +
-            sample(self.medium, per_level) +
-            sample(self.complex, per_level)
-        )
-```
-
-## Production Monitoring
-
-```python
-class Monitor:
-    sample_rate = 0.01  # 1% sampling
-    alert_threshold = 0.85
-
-    def check(self, scores):
-        if avg(scores) < self.alert_threshold:
-            self.alert(f"Quality degraded: {avg(scores):.2f}")
-```
-
-## Guidelines
-
-1. Start with outcome evaluation, not step-by-step
-2. Use multi-dimensional rubrics
-3. Mitigate LLM-as-Judge biases
-4. Test with stratified complexity
-5. Implement continuous monitoring
-6. Focus on token efficiency (80% variance)
-
-## Related
-
-- [Context Compression](./context-compression.md)
-- [Tool Design](./tool-design.md)

package/.agent/skills/context-engineering/references/memory-systems.md

@@ -1,88 +0,0 @@
-# Memory Systems
-
-Architectures for persistent context beyond the window.
-
-## Memory Layer Architecture
-
-| Layer | Scope | Persistence | Use Case |
-|-------|-------|-------------|----------|
-| L1: Working | Current window | None | Active reasoning |
-| L2: Short-Term | Session | Session | Task continuity |
-| L3: Long-Term | Cross-session | Persistent | User preferences |
-| L4: Entity | Per-entity | Persistent | Consistency |
-| L5: Temporal Graph | Time-aware | Persistent | Evolving facts |
-
-## Benchmark Performance (DMR Accuracy)
-
-| System | Accuracy | Approach |
-|--------|----------|----------|
-| Zep | 94.8% | Temporal knowledge graphs |
-| MemGPT | 93.4% | Hierarchical memory |
-| GraphRAG | 75-85% | Knowledge graphs |
-| Vector RAG | 60-70% | Embedding similarity |
-
-## Vector Store with Metadata
-
-```python
-class MetadataVectorStore:
-    def add(self, text, embedding, metadata):
-        doc = {
-            "text": text, "embedding": embedding,
-            "entities": metadata.get("entities", []),
-            "timestamp": metadata.get("timestamp")
-        }
-        self.index_by_entity(doc)
-
-    def search_by_entity(self, entity, k=5):
-        return self.entity_index.get(entity, [])[:k]
-```
-
-## Temporal Knowledge Graph
-
-```python
-class TemporalKnowledgeGraph:
-    def add_fact(self, subject, predicate, obj, valid_from, valid_to=None):
-        self.facts.append({
-            "triple": (subject, predicate, obj),
-            "valid_from": valid_from,
-            "valid_to": valid_to or "current"
-        })
-
-    def query_at_time(self, subject, predicate, timestamp):
-        for fact in self.facts:
-            if (fact["triple"][0] == subject and
-                fact["valid_from"] <= timestamp <= fact["valid_to"]):
-                return fact["triple"][2]
-```
-
-## Memory Retrieval Patterns
-
-| Pattern | Query | Use Case |
-|---------|-------|----------|
-| Semantic | "Similar to X" | General recall |
-| Entity-based | "About user John" | Consistency |
-| Temporal | "Valid on date" | Evolving facts |
-| Hybrid | Combine above | Production |
-
-## File-System-as-Memory
-
-```
-memory/
-├── sessions/{id}/summary.md
-├── entities/{id}.json
-└── facts/{timestamp}_{id}.json
-```
-
-## Guidelines
-
-1. Start with file-system-as-memory (simplest)
-2. Add vector search for scale
-3. Use entity indexing for consistency
-4. Add temporal awareness for evolving facts
-5. Implement consolidation for health
-6. Measure retrieval accuracy
-
-## Related
-
-- [Context Fundamentals](./context-fundamentals.md)
-- [Multi-Agent Patterns](./multi-agent-patterns.md)

package/.agent/skills/context-engineering/references/multi-agent-patterns.md

@@ -1,90 +0,0 @@
-# Multi-Agent Patterns
-
-Distribute work across multiple context windows for isolation and scale.
-
-## Core Insight
-
-Sub-agents exist to **isolate context**, not anthropomorphize roles.
-
-## Token Economics
-
-| Architecture | Multiplier | Use Case |
-|--------------|------------|----------|
-| Single agent | 1x | Simple tasks |
-| Single + tools | ~4x | Moderate complexity |
-| Multi-agent | ~15x | Context isolation needed |
-
-**Key**: Token usage explains 80% of performance variance.
-
-## Patterns
-
-### Supervisor/Orchestrator
-
-```python
-class Supervisor:
-    def process(self, task):
-        subtasks = self.decompose(task)
-        results = [worker.execute(st, clean_context=True) for st in subtasks]
-        return self.aggregate(results)
-```
-
-**Pros**: Control, human-in-loop | **Cons**: Bottleneck, telephone game
-
-### Peer-to-Peer/Swarm
-
-```python
-def process_with_handoff(agent, task):
-    result = agent.process(task)
-    if "handoff" in result:
-        return process_with_handoff(select_agent(result["to"]), result["state"])
-    return result
-```
-
-**Pros**: No SPOF, scales | **Cons**: Complex coordination
-
-### Hierarchical
-
-Strategy → Planning → Execution layers
-**Pros**: Separation of concerns | **Cons**: Coordination overhead
-
-## Context Isolation Patterns
-
-| Pattern | Isolation | Use Case |
-|---------|-----------|----------|
-| Full delegation | None | Max capability |
-| Instruction passing | High | Simple tasks |
-| File coordination | Medium | Shared state |
-
-## Consensus Mechanisms
-
-```python
-def weighted_consensus(responses):
-    scores = {}
-    for r in responses:
-        weight = r["confidence"] * r["expertise"]
-        scores[r["answer"]] = scores.get(r["answer"], 0) + weight
-    return max(scores, key=scores.get)
-```
-
-## Failure Recovery
-
-| Failure | Mitigation |
-|---------|------------|
-| Bottleneck | Output schemas, checkpointing |
-| Overhead | Clear handoffs, batching |
-| Divergence | Boundaries, convergence checks |
-| Errors | Validation, circuit breakers |
-
-## Guidelines
-
-1. Use multi-agent for context isolation, not role-play
-2. Accept ~15x token cost for benefits
-3. Implement circuit breakers
-4. Use files for shared state
-5. Design clear handoffs
-6. Validate between agents
-
-## Related
-
-- [Context Optimization](./context-optimization.md)
-- [Evaluation](./evaluation.md)

package/.agent/skills/context-engineering/references/project-development.md

@@ -1,97 +0,0 @@
-# Project Development
-
-Design and build LLM-powered projects from ideation to deployment.
-
-## Task-Model Fit
-
-**LLM-Suited**: Synthesis, subjective judgment, NL output, error-tolerant batches
-**LLM-Unsuited**: Precise computation, real-time, perfect accuracy, deterministic output
-
-## Manual Prototype First
-
-Test one example with target model before automation.
-
-## Pipeline Architecture
-
-```
-acquire → prepare → process → parse → render
- (fetch)  (prompt)   (LLM)   (extract) (output)
-```
-
-Stages 1,2,4,5: Deterministic, cheap | Stage 3: Non-deterministic, expensive
-
-## File System as State
-
-```
-data/{id}/
-├── raw.json      # acquire done
-├── prompt.md     # prepare done
-├── response.md   # process done
-└── parsed.json   # parse done
-```
-
-```python
-def get_stage(id):
-    if exists(f"{id}/parsed.json"): return "render"
-    if exists(f"{id}/response.md"): return "parse"
-    # ... check backwards
-```
-
-**Benefits**: Idempotent, resumable, debuggable
-
-## Structured Output
-
-```markdown
-## SUMMARY
-[Overview]
-
-## KEY_FINDINGS
-- Finding 1
-
-## SCORE
-[1-5]
-```
-
-```python
-def parse(response):
-    return {
-        "summary": extract_section(response, "SUMMARY"),
-        "findings": extract_list(response, "KEY_FINDINGS"),
-        "score": extract_int(response, "SCORE")
-    }
-```
-
-## Cost Estimation
-
-```python
-def estimate(items, tokens_per, price_per_1k):
-    return len(items) * tokens_per / 1000 * price_per_1k * 1.1  # 10% buffer
-# 1000 items × 2000 tokens × $0.01/1k = $22
-```
-
-## Case Studies
-
-**Karpathy HN**: 930 items, $58, 1hr, 15 workers
-**Vercel d0**: 17→2 tools, 80%→100% success, 3.5x faster
-
-## Single vs Multi-Agent
-
-| Factor | Single | Multi |
-|--------|--------|-------|
-| Context | Fits window | Exceeds |
-| Tasks | Sequential | Parallel |
-| Tokens | Limited | 15x OK |
-
-## Guidelines
-
-1. Validate manually before automating
-2. Use 5-stage pipeline
-3. Track state via files
-4. Design structured output
-5. Estimate costs first
-6. Start single, add multi when needed
-
-## Related
-
-- [Context Optimization](./context-optimization.md)
-- [Multi-Agent Patterns](./multi-agent-patterns.md)

package/.agent/skills/context-engineering/references/tool-design.md

@@ -1,86 +0,0 @@
-# Tool Design
-
-Design effective tools for agent systems.
-
-## Consolidation Principle
-
-Single comprehensive tools > multiple narrow tools. **Target**: 10-20 tools max.
-
-## Architectural Reduction Evidence
-
-| Metric | 17 Tools | 2 Tools | Improvement |
-|--------|----------|---------|-------------|
-| Time | 274.8s | 77.4s | 3.5x faster |
-| Success | 80% | 100% | +20% |
-| Tokens | 102k | 61k | 37% fewer |
-
-**Key**: Good documentation replaces tool sophistication.
-
-## When Reduction Works
-
-**Prerequisites**: High docs quality, capable model, navigable problem
-**Avoid when**: Messy systems, specialized domain, safety-critical
-
-## Description Engineering
-
-Answer four questions:
-1. **What** does the tool do?
-2. **When** should it be used?
-3. **What inputs** does it accept?
-4. **What** does it return?
-
-### Good Example
-
-```json
-{
-  "name": "get_customer",
-  "description": "Retrieve customer profile by ID. Use for order processing, support. Returns 404 if not found.",
-  "parameters": {
-    "customer_id": {"type": "string", "pattern": "^CUST-[0-9]{6}$"},
-    "format": {"enum": ["concise", "detailed"]}
-  }
-}
-```
-
-### Poor Example
-
-```json
-{"name": "search", "description": "Search for things", "parameters": {"q": {}}}
-```
-
-## Error Messages
-
-```python
-def format_error(code, message, resolution):
-    return {
-        "error": {"code": code, "message": message,
-                  "resolution": resolution, "retryable": code in RETRYABLE}
-    }
-# "Use YYYY-MM-DD format, e.g., '2024-01-05'"
-```
-
-## Response Formats
-
-Offer concise vs detailed:
-
-```python
-def get_data(id, format="concise"):
-    if format == "concise":
-        return {"name": data.name}
-    return data.full()  # Detailed
-```
-
-## Guidelines
-
-1. Consolidate tools (target 10-20)
-2. Answer all four questions
-3. Use full parameter names
-4. Design errors for recovery
-5. Offer concise/detailed formats
-6. Test with agents before deploy
-7. Start minimal, add when proven
-
-## Related
-
-- [Context Fundamentals](./context-fundamentals.md)
-- [Multi-Agent Patterns](./multi-agent-patterns.md)