Agents and Skills Guidance

AI Context Files for Data Pipelines

This guide explains what are AGENTS.md,CLAUDE.md,skill.md, and how to write and use them. This section borrows from the AI Powered Data Pipelines presentation, prepared by the "Best Practices for Scientific Workflows" team, and the sections on which data tasks are accelerated by AI, where models succeed or fail, and what context improves outcomes.

Why These Files Matter

In scientific workflows, AI is already being used to accelerate data-related tasks such as: cleaning and preprocessing data, identifying or detecting features, optimizing or controlling processes, other data tasks such as detection and segmentation. A substantial 34% of AI-accelerated scientific workflow tasks involve data, according to the Genesis Mission AI workflow survey. However the skills needed to do this are often domain specific. Published benchmark results also show a clear pattern that motivates the importance of appropriate context for tasks:

• general-purpose Python data-analysis tasks succeed about 70% of the time when frontier models are given tool access and enough turns ^[1]

• domain-specific analysis tasks that require specialized vocabulary or scientific background can drop to about 60% without additional domain context ^[2]

• providing domain-specific tools and documentation can raise performance to roughly 90% on those kinds of tasks ^[3]

• parallel and distributed programming tasks are harder, with reported correctness in the roughly 42-60% range on realistic tasks and performance sometimes up to 70% slower than hand-tuned code ^{[4] [5]}

These results support a practical conclusion: AI-assisted data work performs best when tasks are narrowed, domain assumptions are made explicit, and acceptance criteria are concrete. These context files are how you provide that guidance.

Understanding skill.md, CLAUDE.md, and AGENTS.md

These three file types solve related but different problems--they are complementary components. A vendor-agnostic setup usually works best:

Start with AGENTS.md for instructions that should apply to almost any coding agent working in the repository. Add a tool-specific file only when one agent gains clear value from its native format, such as CLAUDE.md importing @AGENTS.md and layering in Claude-specific behavior. Use skill.md for reusable domain workflows, tool recipes, and specialized analysis procedures that should load on demand rather than in every session. For most teams, the simplest pattern is shared repository rules in AGENTS.md, optional tool-specific overlays where needed, and one or more skill.md files for specialized data workflows.

Other Context Mechanisms Worth Using

• Scoped rule files: relevant when instructions should apply only to part of a repository, such as a subdirectory, language, or monorepo package.

• Model Context Protocol (MCP): relevant when the model needs reliable, structured access to tools, data services, databases, browsers, or workflow systems.

• Hooks and enforcement rules: relevant when guidance must be enforced, such as blocking destructive commands, requiring approvals, or running validation automatically.

• OpenAI skills and plugins: relevant when reusable workflows need to be packaged with instructions, resources, connected tools, or installable integrations.

• Existing project docs such as README.md, schema docs, API specs, and runbooks: relevant when the information already exists and should remain the shared source of truth for both humans and agents.

Suggested Layout

repo/
├── AGENTS.md
├── CLAUDE.md
├── README.md
├── schemas/
├── scripts/
│   └── validate_schema.py
└── .claude/
    ├── rules/
    │   └── testing.md
    └── skills/
        └── clean-instrument-data/skill.md

A practical CLAUDE.md for mixed-tool environments can be very small:

@@AGENTS.md

## Claude Code Notes
- Use plan mode before changing pipeline orchestration code.
- Prefer .claude/rules/ for path-specific instructions.

That avoids duplicating repository guidance while still giving Claude Code native context.

Best Practices for Data Tasks

Three practical methods improve AI performance on data tasks. Those methods translate directly into these files.

1. Translate Work Into Easier Tasks

Models do better on tasks that are:

• specific rather than ambiguous

• standard rather than bespoke

• translation or adaptation rather than invention from scratch

• broken into concrete steps rather than broad goals

Write your context files so the agent is asked to do things like:

• convert this CSV cleaning script into a reusable function

• load this HDF5 file and validate these required columns

• rewrite this notebook step as a tested Python module

• apply the existing schema mapping to these new files

Avoid vague instructions like:

• clean this dataset

• make the pipeline faster

• analyze these results

2. Provide Explicit Context

Explicit context is a major quality lever. In practice, that means your files should include:

• correct examples and incorrect examples

• implied assumptions written out directly

• definitions of specialized terms

• known edge cases in the data

• clear acceptance criteria

For example, instead of saying:

• standardize the metadata

say:

• standardize metadata to the lab schema in schemas/sample_metadata.json

• required fields are sample_id, instrument_id, timestamp, and units

• reject records with missing sample_id

• convert timestamps to ISO 8601 UTC

• output must pass pytest tests/test_metadata_schema.py

That kind of specificity helps the model handle domain-specific work more reliably.

3. Refine and Validate

Advanced refinement and judging techniques improve outcomes. Even if you do not build a full evaluation harness, your context files should push the agent toward validation.

Useful guidance includes:

• run tests after each significant change

• compare generated output to a known-good example

• validate schema, shape, and units before writing results

• prefer small incremental edits over large rewrites

• use automated acceptance criteria whenever possible

For data pipelines, this is especially important because plausible-looking output can still be wrong.

Recommended Structure for skill.md and related files

When in doubt, include these five things:

1. what the task is

2. when the agent should use this guidance

3. examples of correct behavior

4. constraints and common failure modes

5. explicit tests or acceptance checks

That pattern aligns well with the training guidance on easier task framing, explicit context, and automated validation.

Better context usually beats longer prompting. Clear examples, explicit assumptions, and testable acceptance criteria are the most reliable way to improve AI performance on scientific data pipeline work.

Example skill.md file

References

^[1] R. Ma et al., "Can AI Agents Answer Your Data Questions? A Benchmark for Data Agents," Mar. 21, 2026, arXiv: arXiv:2603.20576. doi: 10.48550/arXiv.2603.20576.

^[2] L. Mitchener et al., "BixBench: a Comprehensive Benchmark for LLM-based Agents in Computational Biology," Mar. 08, 2025, arXiv: arXiv:2503.00096. doi: 10.48550/arXiv.2503.00096.

^[3] jaechang-hits, jaechang-hits/SciAgent-Skills. Apr. 25, 2026. Python. Accessed: Apr. 25, 2026. [Online]. Available: https://github.com/jaechang-hits/SciAgent-Skills

^[4] D. Nichols, J. H. Davis, Z. Xie, A. Rajaram, and A. Bhatele, "Can Large Language Models Write Parallel Code?," in Proceedings of the 33rd International Symposium on High-Performance Parallel and Distributed Computing, in HPDC '24. New York, NY, USA: Association for Computing Machinery, Aug. 2024, pp. 281-294. doi: 10.1145/3625549.3658689.

^[5] J. Zhu et al., "CUDABench: Benchmarking LLMs for Text-to-CUDA Generation," Feb. 13, 2026, arXiv: arXiv:2603.02236. doi: 10.48550/arXiv.2603.02236.