@moon791017/neo-skills 1.1.11 → 1.1.13

package/skills/neo-agentic-design/references/resilience-hitl.md

@@ -0,0 +1,105 @@
+# Resilience, Exceptions & HITL
+
+This document provides conceptual designs for system resilience, human interaction, and knowledge grounding, covering exception handling, Human-in-the-Loop (HITL) gates, and Retrieval-Augmented Generation (RAG).
+
+---
+
+## Chapter 12: Exception Handling and Recovery
+
+### 1. Definition
+Designs automatic detection, retry, fallback, and state rollback mechanisms for exceptions that may occur during agent execution (such as API timeouts, network disconnections, LLM format errors, and invalid tool parameters).
+
+### 2. Problems Addressed
+* System fragility: Prevents long-cycle workflows from breaking due to transient network or API issues.
+* Format pollution: Guides the LLM to self-heal when its output does not conform to the expected JSON schema.
+
+### 3. Workflow
+```mermaid
+graph TD
+    Step[Execute Tool / Call LLM] --> Success{Successful?}
+    Success -->|Yes| Next[Proceed to Next Step]
+    Success -->|No: Exception| Detector[Exception Detector]
+    Detector --> RuleCheck{Evaluate Exception Type}
+    RuleCheck -->|Network/Timeout| Retry[Auto Retry with Backoff]
+    RuleCheck -->|Format Error| Refine[Guide LLM to Self-Correct]
+    RuleCheck -->|Tool Failure| Fallback[Route to Fallback/Alternative Tool]
+    RuleCheck -->|Critical Error| Rollback[Rollback State to Checkpoint]
+    Retry --> Step
+    Refine --> Step
+    Fallback --> Step
+    Rollback --> UserEscalation[Human Intervention]
+```
+
+### 4. Trade-offs
+* **Pros**: Improves system robustness and reduces manual maintenance costs.
+* **Cons**: Excessive retries or fallbacks can mask underlying bugs or quietly degrade output quality.
+
+---
+
+## Chapter 13: Human-in-the-Loop (HITL)
+
+### 1. Definition
+Strategically embeds human review, intervention, and authorization mechanisms into the agent's autonomous decision-making workflow, combining human common sense, ethics, and legal judgment with AI automation.
+
+### 2. Problems Addressed
+* High-risk operations: Prevents agent errors when performing large financial transactions, deleting sensitive data, or executing legally sensitive actions.
+* Automation boundaries: Requests human guidance when decision confidence falls below a set threshold.
+
+### 3. Three Core Interaction Modes
+````carousel
+### 1. Human-in-the-Loop (HITL)
+* **Mechanism**: The agent pauses when reaching a high-risk step (e.g., large bank transfer), suspends the task, and sends it to a pending review queue.
+* **Workflow**: Agent pauses -> Human reviews (Approve/Reject/Modify) -> Agent receives input and resumes execution.
+* **Key Characteristic**: Human approval is a mandatory gate.
+<!-- slide -->
+### 2. Human-on-the-Loop (HOTL)
+* **Mechanism**: The agent executes tasks autonomously while a human supervisor monitors and adjusts strategies.
+* **Workflow**: Human sets macro rules (e.g., transaction limits) -> Agent trades automatically -> Human monitors metrics -> Human intervenes via a Kill Switch if necessary.
+* **Key Characteristic**: Human does not intervene in individual decisions but maintains macro-level oversight.
+<!-- slide -->
+### 3. Decision Augmentation
+* **Mechanism**: The agent acts as an analytical assistant, gathering data and presenting candidates. Decision-making and execution are performed entirely by a human.
+* **Workflow**: Human asks query -> Agent collects and analyzes data -> Agent proposes options A, B, and C with pros/cons -> Human selects and executes.
+* **Key Characteristic**: Agent provides cognitive augmentation without execution authority.
+````
+
+### 4. Trade-offs
+* **Pros**: Provides a safety net and compliance guarantee for high-risk decisions; collects human feedback to optimize agent alignment.
+* **Cons**: Human intervention limits system scalability and speed; designing human-in-the-loop review queues increases development costs.
+
+---
+
+## Chapter 14: Knowledge Retrieval / RAG
+
+### 1. Definition
+Retrieves relevant information from a knowledge base before the LLM generates a response, injecting the retrieved text chunks into the prompt context to guide the LLM toward producing factually grounded answers.
+
+### 2. Advanced Agentic RAG Variants
+```mermaid
+graph TD
+    subgraph Traditional RAG
+        Query[User Query] --> VectorSearch[Vector Similarity Search]
+        VectorSearch --> Context[Concatenate Context Chunks]
+        Context --> LLMGen[LLM Generates Response]
+    end
+    subgraph Graph RAG
+        GQuery[User Query] --> GraphSearch[Navigate Knowledge Graph Nodes & Edges]
+        GraphSearch --> UnifiedContext[Cross-document Context Linkage]
+    end
+    subgraph Agentic RAG
+        AQuery[User Query] --> AgentLayer[Agent Decision Layer]
+        AgentLayer -->|1. Decompose Task| SubQueries[Multi-step Sub-retrieval Tasks]
+        AgentLayer -->|2. Self-Reflection| SourceVal[Source Timeliness & Quality Check]
+        AgentLayer -->|3. Resolve Conflicts| ConflictRecon[Active Conflict Reconciliation]
+        AgentLayer -->|4. Tool Call| WebSearch[Web Search for Knowledge Gaps]
+    end
+```
+
+### 3. Problems Addressed
+* Outdated knowledge: Bypasses the temporal limits of static training data.
+* Hallucination: Restricts the model within factual boundaries using verified document contexts.
+* Fragmented information: Resolves vector search limitations that struggle to answer comprehensive questions spanning multiple documents.
+
+### 4. Trade-offs
+* **Pros**: Minimizes factual errors; supports precise citations; imports private knowledge without retraining models.
+* **Cons**: Highly sensitive to the quality of text chunking and embeddings; multi-step reasoning in Agentic RAG increases response latency.

package/skills/neo-agentic-design/references/system-components.md

@@ -0,0 +1,93 @@
+# System Components & Protocols
+
+This document provides conceptual designs for system architecture components, resources, and protocols, covering memory management, learning and adaptation, Model Context Protocol (MCP), and goal setting and monitoring.
+
+---
+
+## Chapter 8: Memory Management
+
+### 1. Definition
+Provides agents with the ability to store and retrieve information across sessions and tasks through persistence mechanisms. The memory system is generally divided into short-term and long-term memory, managed by a unified Memory Service.
+
+### 2. Memory Classification
+| Memory Type | Medium | Function | Eviction & Retrieval Mechanism |
+| :--- | :--- | :--- | :--- |
+| **Short-term** | Current Context Window | Stores current conversation context and task execution trajectory | Sliding window, context pruning, and summarization |
+| **Long-term Semantic** | Vector Database / Knowledge Base | Retains factual knowledge, concepts, and external rules | Vector semantic retrieval based on user input |
+| **Long-term Episodic** | Structured Database / Log Store | Records past task execution experiences and outcomes | Used for few-shot learning or similar scenario matching |
+| **Long-term Procedural**| Codebase / Tool Definitions / Prompt Templates | Records Standard Operating Procedures (SOPs) and toolbox definitions for specific tasks | Dynamically loaded based on task type |
+
+### 3. Problems Addressed
+* Amnesia (Context limits): Prevents long conversations from causing the LLM to lose critical history.
+* Repeated errors: Ensures the agent learns from past executions to improve decision success rates.
+
+---
+
+## Chapter 9: Learning and Adaptation
+
+### 1. Definition
+Enables the agent to autonomously modify prompts or self-modify execution code in a code sandbox (SICA - Self-Improving Coding Agent) by collecting behavioral feedback and rewards from interactions with the environment, users, or other agents.
+
+### 2. Problems Addressed
+* Static configuration lag: Solves the issue of agents failing to adjust when environmental rules change.
+* High development cost: Eliminates the manual process of fine-tuning prompts.
+
+### 3. Workflow
+```mermaid
+graph TD
+    Interaction[Agent-Environment Interaction] --> Result[Execution Results & Metrics]
+    Result --> evaluator[Evaluator / Scoring System]
+    evaluator -->|Feedback/Score| Learner[Learning Engine]
+    Learner -->|Self-Optimize Prompts or Refactor Code| AgentUpgrade[Upgraded Agent]
+    AgentUpgrade -->|Next Task Turn| Interaction
+```
+
+### 4. Trade-offs
+* **Pros**: High potential for long-term self-evolution; can discover high-quality logic not designed by humans in specific vertical disciplines (e.g., mathematical proofs, code generation).
+* **Cons**: Unpredictable evolution paths, which may generate harmful mutations; self-modifying prompts can lead to privilege escalation or security vulnerabilities; extremely high overhead for training and testing iterations.
+
+---
+
+## Chapter 10: Model Context Protocol (MCP)
+
+### 1. Definition
+A standardized **Client-Server communication protocol** that establishes a plug-and-play integration standard between LLMs/Agents (Clients) and external data sources, development tools, and API services (Servers). MCP standardizes three core types of context exchange: **Resources**, **Prompts**, and **Tools**.
+
+```mermaid
+graph LR
+    subgraph Agentic Client
+        Agent[AI Agent / LLM]
+    end
+    subgraph MCP Server
+        Res[Resources: Files/Databases]
+        Pmt[Prompts: Templates]
+        Tls[Tools: APIs/Sandboxes]
+    end
+    Agent <-->|Standard JSON-RPC 2.0| MCP_Link[MCP Protocol Layer]
+    MCP_Link <--> Res
+    MCP_Link <--> Pmt
+    MCP_Link <--> Tls
+```
+
+### 2. Problems Addressed
+* Tedious integration: Avoids repeatedly writing custom wrapper code when developing new agents or integrating new tools.
+* Fragmented context acquisition: Provides external data and actions to the model in a unified interface format.
+
+### 3. Trade-offs
+* **Pros**: Reduces integration costs for multiple tools and data sources; decouples data sources from reasoning entities; supports dynamic discovery.
+* **Cons**: Protocol serialization and JSON-RPC wrapping introduce minor performance overhead; requires tool providers to actively adopt the protocol.
+
+---
+
+## Chapter 11: Goal Setting and Monitoring
+
+### 1. Definition
+Sets structured and quantifiable goals (SMART principles) before agent initialization, and introduces an independent monitor during the execution phase to observe progress in real time (Progress Checkpoints), detect blocks, and trigger human-agent collaboration escalation when necessary.
+
+### 2. Problems Addressed
+* Blind execution: Prevents agents from entering infinite retry loops when encountering logical obstacles, wasting budget.
+* Lack of observability: Solves the black-box execution problem, providing a clear progress path.
+
+### 3. Use Cases
+* Automated marketing campaign execution.
+* Long-cycle autonomous codebase refactoring.

package/skills/neo-opentelemetry/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: neo-opentelemetry
+description: >
+  Use this skill when explaining OpenTelemetry concepts, choosing telemetry signals,
+  planning or reviewing Collector architectures and declarative configuration,
+  operating or troubleshooting telemetry pipelines, securing telemetry data,
+  evaluating zero-code instrumentation, or planning Prometheus, OpenCensus, or
+  OpenTracing interoperability and migration. Do not use it to write language SDK/API
+  instrumentation code or custom Collector components.
+compatibility: No runtime required. Network access is required to verify current versions, component status, security advisories, and other time-sensitive claims.
+metadata:
+  version: "1.0.0"
+  pattern: "tool-wrapper,pipeline"
+  domain: "observability-operations"
+  source-revision: "b18eb4d01fab9be2c5c22b1aaafdeb23ba97e3d4"
+---
+
+# Neo OpenTelemetry
+
+Provide source-grounded OpenTelemetry guidance for concepts and operations without generating programming-language instrumentation code.
+
+## Scope boundary
+
+In scope:
+
+- Observability concepts, telemetry signals, correlation, resources, semantic conventions, and sampling.
+- Collector pipelines, components, deployment patterns, declarative configuration, scaling, resiliency, internal telemetry, transformation, and troubleshooting.
+- Kubernetes, FaaS, OpenTelemetry Operator, OBI, and other zero-code operational approaches.
+- Security, sensitive-data handling, Prometheus interoperability, and OpenCensus/OpenTracing migration planning.
+
+Out of scope:
+
+- Language-specific SDK/API usage, manual instrumentation, source-code examples, and library integration code.
+- Building the Collector from source or developing custom receivers, processors, exporters, connectors, or extensions.
+- Vendor pricing, backend-specific query languages, and backend product administration unless needed only as context for an OpenTelemetry decision.
+
+If the request crosses the boundary, answer the in-scope operational portion and identify the excluded portion. Point to the appropriate official language or component-development documentation instead of inventing code.
+
+## Workflow
+
+1. Classify the request as explanation, architecture decision, configuration review, security review, migration, or troubleshooting.
+2. Load `references/sources-and-scope.md` whenever the answer depends on source coverage, current status, or an excluded area.
+3. Load only the references required by the request:
+   - Foundations and terminology: `references/foundations.md`
+   - Signals and sampling: `references/signals-and-sampling.md`
+   - Collector topology and configuration: `references/collector-architecture-and-configuration.md`
+   - Collector operations and troubleshooting: `references/collector-operations.md`
+   - Kubernetes, FaaS, Operator, and zero-code: `references/platforms-and-zero-code.md`
+   - Security and sensitive data: `references/security.md`
+   - Prometheus, migration, and deployment guidance: `references/compatibility-and-guidance.md`
+4. Inspect user-provided configuration and environment evidence before recommending changes. Never assume topology, volume, failure tolerance, trust boundaries, or backend capabilities.
+5. Verify time-sensitive facts against official OpenTelemetry sources. If verification is unavailable, identify the snapshot revision and state that current status cannot be confirmed.
+6. Produce the smallest useful response and cite the official page supporting material claims.
+
+## Decision rules
+
+- Treat OpenTelemetry as a telemetry generation, collection, processing, and export framework, not as a storage or visualization backend.
+- Default to the simplest deployment pattern that satisfies the stated requirements. Add gateways, stateful routing, persistent queues, or external message queues only for an identified need.
+- Separate symptoms by pipeline stage: generation, reception, processing, queuing, export, network, or backend.
+- Treat sampling, filtering, redaction, and transformation as data-loss or data-quality decisions. State what is intentionally discarded or changed.
+- Never recommend scaling Collectors before checking whether the bottleneck is the Collector, network, or backend.
+- Never place credentials, tokens, personal data, or other sensitive values in examples.
+- Prefer least privilege, restricted listener addresses, authenticated and encrypted network paths, data minimization, and Collector self-observability.
+
+## Response contracts
+
+For explanations, provide:
+
+1. Direct answer.
+2. Relevant OpenTelemetry concepts and boundaries.
+3. Official source links.
+
+For architecture or configuration reviews, provide:
+
+1. Observed requirements or configuration facts.
+2. Findings ordered by impact.
+3. Recommended topology or declarative changes with trade-offs.
+4. Capacity, resiliency, security, and validation checks.
+5. Official source links.
+
+For troubleshooting, provide:
+
+1. Observed symptom and missing evidence.
+2. Most likely pipeline stage based on supplied evidence; label this as an inference.
+3. Non-destructive checks ordered from source to destination.
+4. Remediation only after the failing stage is isolated.
+5. Verification signals and official source links.
+
+## Fact-check gate
+
+- Distinguish verified source facts from recommendations and inferences.
+- Do not convert documentation examples into universal defaults.
+- Do not state version numbers, maturity levels, component availability, default ports, default limits, or CVE status without checking the current official source when the answer depends on them.
+- Say that data is insufficient when the request lacks evidence needed for a safe operational conclusion.

package/skills/neo-opentelemetry/evals/eval_queries.json

@@ -0,0 +1,82 @@
+[
+  {
+    "query": "Explain when I should use traces, metrics, logs, and profiles together in OpenTelemetry.",
+    "should_trigger": true
+  },
+  {
+    "query": "Review our OpenTelemetry Collector YAML for missing queues, unsafe listeners, and processor ordering.",
+    "should_trigger": true
+  },
+  {
+    "query": "Should our Kubernetes telemetry pipeline use Collector agents, gateways, or both?",
+    "should_trigger": true
+  },
+  {
+    "query": "Our otel gateway queue keeps filling and spans are being dropped. Help me isolate the bottleneck.",
+    "should_trigger": true
+  },
+  {
+    "query": "Design a resilient OpenTelemetry Collector topology that can tolerate a backend outage.",
+    "should_trigger": true
+  },
+  {
+    "query": "Check whether our baggage and resource attributes could leak customer data.",
+    "should_trigger": true
+  },
+  {
+    "query": "Plan a zero-code observability rollout for Linux workloads using the Operator or OBI.",
+    "should_trigger": true
+  },
+  {
+    "query": "How should we migrate Prometheus metric collection into an OTLP and Collector architecture?",
+    "should_trigger": true
+  },
+  {
+    "query": "Create an operational migration plan from OpenTracing to OpenTelemetry without breaking dashboards.",
+    "should_trigger": true
+  },
+  {
+    "query": "Why are traces split after they cross a service boundary even though both services export spans?",
+    "should_trigger": true
+  },
+  {
+    "query": "Write C# ActivitySource instrumentation for my ASP.NET Core checkout endpoint.",
+    "should_trigger": false
+  },
+  {
+    "query": "Show me the Java OpenTelemetry SDK calls needed to create a custom histogram.",
+    "should_trigger": false
+  },
+  {
+    "query": "Implement a custom OpenTelemetry Collector receiver in Go.",
+    "should_trigger": false
+  },
+  {
+    "query": "Build the OpenTelemetry Collector from source with a custom exporter.",
+    "should_trigger": false
+  },
+  {
+    "query": "Write a PromQL query for calculating HTTP error rate in Grafana.",
+    "should_trigger": false
+  },
+  {
+    "query": "Troubleshoot why my Kubernetes Deployment cannot pull its application image.",
+    "should_trigger": false
+  },
+  {
+    "query": "Compare the current pricing of Datadog, New Relic, and Honeycomb.",
+    "should_trigger": false
+  },
+  {
+    "query": "Create OpenAPI documentation for my REST endpoints.",
+    "should_trigger": false
+  },
+  {
+    "query": "Help me submit a pull request to translate the OpenTelemetry website.",
+    "should_trigger": false
+  },
+  {
+    "query": "Design a generic application logging API that does not use OpenTelemetry.",
+    "should_trigger": false
+  }
+]

package/skills/neo-opentelemetry/evals/evals.json

@@ -0,0 +1,64 @@
+{
+  "skill_name": "neo-opentelemetry",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "We operate a checkout service and only have CPU dashboards. Explain which OpenTelemetry signals would help us detect reliability problems and determine why one request is slow. Do not provide instrumentation code.",
+      "expected_output": "A source-grounded explanation that distinguishes metrics, traces, logs, and profiles, describes correlation, and stays outside language SDK/API implementation.",
+      "assertions": [
+        "The response explains a distinct operational question answered by metrics, traces, logs, and profiles",
+        "The response explains that resource identity or trace context is needed for correlation",
+        "The response contains at least one official opentelemetry.io documentation link",
+        "The response contains no programming-language instrumentation code"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Plan an OpenTelemetry Collector deployment for 60 Kubernetes nodes. We need node logs and host metrics, centralized redaction, one controlled egress point, and tail sampling for traces. State assumptions where capacity data is missing.",
+      "expected_output": "An agent-to-gateway architecture with node-local agents, centralized gateway processing, trace-affine routing for tail sampling, explicit security and capacity caveats, and verification steps.",
+      "assertions": [
+        "The response assigns node logs and host metrics to node-local agents",
+        "The response assigns centralized redaction, credentials, and backend export to gateways",
+        "The response states that every span for a trace must reach the same tail-sampling instance",
+        "The response labels capacity recommendations as unresolved because telemetry volume is not provided",
+        "The response includes security, resiliency, and rollout verification checks"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Review this Collector configuration:\n\nreceivers:\n  otlp:\n    protocols:\n      grpc:\n        endpoint: 0.0.0.0:4317\nprocessors:\n  batch:\nexporters:\n  otlp:\n    endpoint: vendor.example:4317\n    headers:\n      api-key: hard-coded-example-secret\nservice:\n  pipelines:\n    traces:\n      receivers: [otlp]\n      processors: [batch]\n      exporters: [otlp]\n\nIdentify operational and security risks, but do not assume whether remote clients require the unrestricted listener.",
+      "expected_output": "A configuration review that identifies the unrestricted listener, embedded secret, missing memory protection, queue/retry and TLS questions, while treating topology-dependent changes as conditional.",
+      "assertions": [
+        "The response identifies the embedded credential as a critical issue and recommends protected runtime secret injection",
+        "The response identifies 0.0.0.0 as an exposure requiring topology evidence rather than replacing it unconditionally",
+        "The response checks memory limiting, batching, queueing, retries, TLS, and Collector self-observability",
+        "Findings are ordered by impact and distinguish facts from conditional recommendations",
+        "The response includes official Collector configuration and security links"
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "During a backend outage our Collector exporter queue reaches capacity, enqueue failures increase, and queued data disappears when gateway pods restart. Give us a diagnosis and a resilient remediation sequence.",
+      "expected_output": "A diagnosis grounded in queue saturation and in-memory loss, followed by bounded retry/queue tuning, persistent storage evaluation, monitoring, capacity checks, and an optional external queue only when stronger durability justifies it.",
+      "assertions": [
+        "The response identifies queue saturation and pod restart with in-memory buffering as observed loss mechanisms",
+        "The response recommends measuring arrival rate, outage duration, queue capacity, memory, disk, and backend recovery before sizing",
+        "The response discusses persistent sending queues and their disk and permission trade-offs",
+        "The response treats an external message queue as an optional higher-complexity durability layer",
+        "The response defines post-change verification using queue, failure, restart, and export evidence"
+      ]
+    },
+    {
+      "id": 5,
+      "prompt": "We want zero-code telemetry for mixed workloads: Kubernetes services, Linux VMs, and AWS Lambda. Produce a decision framework that covers the Operator, OBI, Collector agents, and Lambda layers. Current versions and runtime details are not supplied.",
+      "expected_output": "A platform-specific decision framework that compares supported zero-code approaches, flags missing compatibility evidence, includes least-privilege and rollout checks, and avoids unsupported version claims or language code.",
+      "assertions": [
+        "The response maps the Operator to Kubernetes, OBI or Collector agents to compatible Linux environments, and published layers to supported Lambda runtimes",
+        "The response states that runtime, kernel, architecture, region, artifact, and current-version compatibility must be verified",
+        "The response includes least-privilege, network, secret, performance, and rollback checks",
+        "The response identifies that zero-code methods cannot guarantee custom business telemetry",
+        "The response contains no manual instrumentation code"
+      ]
+    }
+  ]
+}

package/skills/neo-opentelemetry/references/collector-architecture-and-configuration.md

@@ -0,0 +1,138 @@
+# Collector Architecture and Configuration
+
+Use this reference to choose a Collector topology or review declarative Collector configuration. Component availability and configuration keys vary by distribution and version; verify them in the current component documentation.
+
+## Pipeline model
+
+A Collector pipeline moves one signal type through:
+
+1. Receivers that accept or obtain telemetry.
+2. Optional processors that transform, enrich, batch, sample, filter, or drop telemetry.
+3. Exporters that send telemetry to a destination.
+
+Connectors join two pipelines while acting as an exporter for one and a receiver for another. Extensions add operational capabilities such as health checks, storage, authentication, or service discovery and are enabled separately from telemetry pipelines.
+
+A minimal declarative shape is:
+
+```yaml
+receivers:
+  otlp:
+    protocols:
+      grpc:
+
+processors:
+  memory_limiter:
+    check_interval: 1s
+    limit_mib: 512
+  batch:
+
+exporters:
+  otlp:
+    endpoint: telemetry-backend.example:4317
+
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: [memory_limiter, batch]
+      exporters: [otlp]
+```
+
+This is a structural example, not a production-ready universal default. Authentication, TLS, listener addresses, queueing, resource limits, and component support must be decided for the target environment.
+
+## Configuration mechanics
+
+- Define components at the top level, then activate them by referencing them from a pipeline or the service extension list.
+- Use `type/name` identifiers when more than one instance of a component type is needed.
+- A defined component that is not referenced by `service` is not enabled.
+- Signal types in a pipeline must be supported by every referenced component.
+- Processor order is behaviorally significant.
+- Multiple configuration sources can be merged, but the merged result must still be complete.
+- Use environment-variable substitution for deployment-supplied values; never embed secrets in the Skill, repository examples, or review output.
+
+Validate before deployment:
+
+```shell
+otelcol validate --config=collector.yaml
+```
+
+Confirm the executable and subcommand for the selected Collector distribution rather than assuming every distribution uses the same binary name.
+
+## Reuse and fan-out gotcha
+
+A receiver can feed multiple pipelines and an exporter can receive from multiple pipelines. Receiver fan-out is synchronous: a blocking processor in one attached pipeline can block the other pipelines and the receiver. Do not reuse a receiver across pipelines without evaluating this failure coupling.
+
+Processors referenced by multiple pipelines use the same configuration but each pipeline gets its own processor instance and state.
+
+## Deployment patterns
+
+### No Collector
+
+Direct export has the fewest moving parts but couples telemetry delivery and backend changes to the instrumented workload. Use it for simple development or constrained cases only after accepting the limited processing, exporter, and operational flexibility.
+
+### Agent
+
+An agent runs close to workloads, commonly as a host process, sidecar, or Kubernetes DaemonSet.
+
+Choose an agent when you need:
+
+- Host-local metrics or logs.
+- Local enrichment with host or Kubernetes resource attributes.
+- A stable local telemetry destination.
+- Reduced application responsibility for credentials and backend export.
+
+Agents multiply configuration and resource overhead across hosts or workloads. Keep their processing focused.
+
+### Gateway
+
+A gateway is a standalone Collector service shared by multiple telemetry sources.
+
+Choose a gateway when you need:
+
+- Centralized credentials, filtering, transformation, or policy.
+- Central processing that must observe traffic from multiple sources.
+- Independent scaling of telemetry processing.
+- A controlled egress point to external backends.
+
+Gateways add a network hop and a shared failure domain. Load balance stateless gateways and monitor them as production services.
+
+### Agent to gateway
+
+Combine agents and gateways when both local collection and centralized processing are required. Typical separation:
+
+- Agents: local reception, host collection, resource detection, memory protection, and efficient forwarding.
+- Gateways: centralized filtering, tail sampling, batching, credentials, and resilient export.
+
+This pattern is justified by identified needs such as network isolation, host telemetry, central policy, trace-aware sampling, or scale. It is not the default for small deployments.
+
+## Stateful routing rules
+
+- Tail sampling requires all spans for a trace to reach the same decision-making instance.
+- Cumulative-to-delta conversion and some aggregation use cases also require data-aware routing.
+- Prometheus scraping requires target allocation or sharding to avoid duplicate collection.
+- Metric streams must preserve the single-writer principle and globally unique identities.
+- Standard layer-4 load balancing can be ineffective for persistent gRPC connections; verify that the load-balancing method distributes the actual connection pattern.
+
+## Configuration review checklist
+
+1. Identify each enabled pipeline and its signal type.
+2. Verify every referenced component exists in the selected distribution.
+3. Trace data from each receiver through processors to every exporter.
+4. Inspect processor order and intentional data drops.
+5. Check listener scope, authentication, TLS, and secret injection.
+6. Check memory limiting, batching, queueing, retry, and persistent storage requirements.
+7. Check stateful processors and their routing assumptions.
+8. Check resource identity and duplicate-writer risk.
+9. Check Collector internal telemetry, health checks, and alerting.
+10. Validate the merged configuration with the target executable.
+
+## Official sources
+
+- [Collector architecture](https://opentelemetry.io/docs/collector/architecture/)
+- [Collector configuration](https://opentelemetry.io/docs/collector/configuration/)
+- [Collector components](https://opentelemetry.io/docs/collector/components/)
+- [Choose a deployment pattern](https://opentelemetry.io/docs/collector/deploy/choose/)
+- [Agent deployment pattern](https://opentelemetry.io/docs/collector/deploy/agent/)
+- [Gateway deployment pattern](https://opentelemetry.io/docs/collector/deploy/gateway/)
+- [Agent-to-gateway deployment pattern](https://opentelemetry.io/docs/collector/deploy/other/agent-to-gateway/)
+- [No Collector](https://opentelemetry.io/docs/collector/deploy/other/no-collector/)