Haystack

---
name: haystack
description: "Use Haystack to build, debug, evaluate, and maintain RAG, agent,
  pipeline, component, ingestion, retrieval, generator, tool-calling, and
  observability workflows for the haystack-ai package and repository."
disable-model-invocation: true
metadata:
  disco-role: operating
license: NOASSERTION
---

# Haystack

Use this skill when the task names Haystack, `haystack-ai`, `Pipeline`, `AsyncPipeline`, `Document`, Haystack components, document stores, retrievers, rankers, agents, tools, generators, embedders, evaluators, tracing, or repository development in this checkout.

## Route By Task

- **Pipeline mechanics and custom components**: use `sub-skills/pipelines-and-components/SKILL.md` for `Pipeline`, `AsyncPipeline`, `@component`, socket wiring, loop limits, serialization, breakpoints, snapshots, and `SuperComponent`.
- **Data ingestion and conversion**: use `sub-skills/data-ingestion/SKILL.md` for `Document`, `ByteStream`, file converters, cleaners, splitters, preprocessors, file/document/metadata routers, and fetch/cache checks.
- **Retrieval and RAG**: use `sub-skills/retrieval-and-rag/SKILL.md` for document stores, writers, BM25/embedding retrievers, metadata filters, rankers, joiners, readers, and local RAG skeletons.
- **Model-facing components**: use `sub-skills/generation-and-model-components/SKILL.md` for prompt builders, chat/text generators, embedders, classifiers, samplers, validators, provider credentials, and optional local/API model backends.
- **Agents, tools, and HITL**: use `sub-skills/agents-tools-and-hitl/SKILL.md` for `Agent`, `Tool`, `Toolset`, `ComponentTool`, `PipelineTool`, `ToolInvoker`, MCP/OpenAPI connectors, state, breakpoints, and human confirmation.
- **Evaluation and observability**: use `sub-skills/evaluation-and-observability/SKILL.md` for retrieval/answer evaluators, `EvaluationRunResult`, tracing, logging, telemetry, and pipeline debug outputs.
- **Repository development**: use `sub-skills/repo-development/SKILL.md` when modifying this Haystack checkout, selecting Hatch tests, formatting, type checks, release notes, or docs checks.

## Fast Start

1. Check the execution context. For package-user workflows, any Python environment with `haystack-ai` is enough for local smoke checks. For repository development inside the checkout, follow `AGENTS.md` and use Hatch.
2. Start with the workflow-owning sub-skill, then follow cross-links for adjacent concerns such as ingestion -> retrieval -> generation -> evaluation.
3. Keep provider credentials and model downloads explicit. Many generator, embedder, reader, and LLM evaluator components require optional dependencies or API keys.
4. For local validation, prefer in-memory stores, tiny `Document` lists, mocked or placeholder generators, and bundled smoke scripts before adding network or GPU dependencies.

## References

- `references/component-selection.md` maps common goals to sub-skills and component families.
- `references/troubleshooting.md` covers cross-cutting install/import, optional dependency, credential, pipeline, telemetry, and repository failures.
- `references/repo-provenance.md` records the source revision and extraction evidence.
- `scripts/haystack_smoke_check.py` validates basic public imports and a tiny custom component pipeline.

## Avoid

- Do not use repository Hatch commands for ordinary package-user examples unless the user is editing the checkout.
- Do not assume optional integrations are installed. Name the extra dependency or provider credential before recommending code that requires it.
- Do not route generic vector database, LangChain, LlamaIndex, or OpenAI-client tasks here unless Haystack is the orchestrating framework.