The Markdown files that help your coding agent work smarter: A Data Drills Challenge
If you use AI agents or large language models (LLMs) daily, or are still experimenting with them, you'll probably have noticed that getting good, consistent results can be hit and miss.
One way to improve consistency is to create agent specifications: documented instructions that tell an AI agent how to work.
Instead of repeatedly explaining your project, the rules it should follow, and how to perform particular tasks, you can put that information into reusable files.
Welcome to the world of agent specifications and reusable AI instructions.
From Simple Prompts to Agent Specifications
You've probably heard of prompt engineering: the practice of writing clear instructions for AI.
You may also have come across context engineering, which is about making sure an AI system has the right information available to complete a task.
Agent specification files build on both ideas. They let us document important project information and create reusable rules and workflows.
Think of it as onboarding a new colleague. Instead of explaining everything from scratch every morning, you give them a project brief, a handbook, and instructions for common tasks. These reusable files help your agent understand its working environment, the project's context, and the processes it should follow.
For this challenge, we'll explore three useful Markdown files.
Three Flavours of Markdown
AGENTS.md — The Project Handbook
This file contains project-level instructions. It defines how an AI coding agent should work within a project, including its objectives, tools, conventions, and rules.
For example, it might describe:
- The project's purpose and repository structure
- Coding conventions and preferred tools
- How to run tests
- Important constraints and things the agent must not do
AGENTS.md is an open format for communicating project-specific instructions to AI coding agents. Think of it as a README for your agent.
SKILL.md — The Specialist's Instructions
A SKILL.md file provides reusable instructions, workflows, and domain-specific knowledge for a particular task.
A skill might explain how to clean a dataset, evaluate a machine learning model, or analyse financial statements using relevant accounting principles.
Under the Agent Skills specification, a skill is typically stored in its own folder with a SKILL.md file, including YAML frontmatter, and may have supporting resources.
The project can change, but the skill can remain the same.
DESIGN.md — The Design Brief
What should your project look and feel like?
A DESIGN.md file can define the visual identity of a project, including colours, typography, layouts, chart styling, and design principles. It helps AI agents create consistent interfaces and visual outputs.
Google's Stitch has published a specification for its DESIGN.md approach.
An important distinction: AGENTS.md and Agent Skills (SKILL.md) have published open specifications. DESIGN.md is not a universal, cross-tool standard in the same way. For this challenge, we're using it as a practical design brief.
Today's Data Drills Challenge
You're a data analyst at a subscription business. Customer churn is climbing. The executive team wants answers by Friday.
You have an AI assistant, a messy customer dataset, and a choice: prompt it as usual, or give it a playbook.
In this drill, you'll give an LLM or AI agent a data analytics task and compare two approaches:
- Baseline: Use a simple prompt and assess the answer.
- Playbook: Use the same prompt with agent specification files and assess whether the results improve.
Observe the differences, score both outputs, and take notes.
One prompt. Two approaches. How different are the results?
Step 1 — Get Your Data
You'll work with a fictional subscription dataset of approximately 2,000 customers, including signup dates, plan tiers, monthly usage, support tickets, and cancellation flags.
The dataset is deliberately imperfect. It includes missing churn statuses, impossible signup dates, duplicated customer IDs, and inconsistent spellings of the "Basic" plan tier.
Don't clean it yet!
In the Resources section, you'll find a Python script to generate the dataset. These data-quality problems are intentional: a basic prompt may overlook them and produce misleading churn calculations.
For example, if a churn status is missing, silently dropping that customer from the calculation could change the reported churn rate. A more careful analysis should identify and report unknown statuses separately, then explain which records are included in the calculation and why.
Spoiler alert: A well-written SKILL.md should encourage the agent to look before it calculates.
That's the point of the challenge. The messy data is the trap; your playbook should help the agent spot it.
Step 2 — Establish Your Baseline
Open a fresh conversation with your AI tool of choice. Provide the dataset and paste this prompt verbatim:
Analyse this customer dataset, identify any data-quality issues, investigate customer churn and recommend three visualisations that would help the business understand its customers.
Save the output. Don't correct the AI or ask follow-up questions. This is your baseline.
Make a note of the following:
- What churn rate did it calculate? What did it assume "churned" meant?
- Did it identify the intended data-quality issues? Did it find any others?
- Which three visualisations did it recommend? Would they help the business make decisions?
Step 3 — Build Your Playbook
Now write three files. You'll find starter templates in the Resources section.
AGENTS.md — Define the project and its rules.
At minimum, include the business objective, the tools the agent should use, and one non-negotiable rule. For example:
Never modify the source CSV. Always state analytical assumptions explicitly.
SKILL.md — Define a reusable churn-analysis workflow.
This is the heart of the challenge. Write a skill that could work with any subscription business, not just this dataset.
Decide:
- What counts as a churned customer, and what doesn't?
- How should the churn rate be calculated consistently? What period and denominator are appropriate?
- How should missing, duplicate, or contradictory records be handled?
- How should the agent distinguish correlation from causation when discussing possible churn drivers?
- Which customer segments are worth comparing, and which comparisons could be misleading?
Remember: a skill can contain domain-specific knowledge and a repeatable process.
DESIGN.md — Define how the findings should look.
Choose a colour palette, decide how churned and retained customers should be visually distinguished, and set rules for chart titles, legends, labels, and accessibility.
Be specific enough that two people following your brief would produce reasonably consistent charts.
Step 4 — Test Your Playbook
Start a fresh conversation using the same AI model.
Provide the same dataset and the same baseline prompt, plus your three files. Add this instruction:
Follow AGENTS.md for project context and rules. Apply SKILL.md for the churn analysis. Follow DESIGN.md for any visualisations.
Run the analysis and save the answer.
Tip: If you're working in a chat interface rather than an agent-enabled coding environment, attach or paste the file contents. A plain chat may not automatically discover AGENTS.md or a skill folder.
Step 5 — Score Both Answers
Now compare the response from the basic prompt with the response produced using your playbook.
Score both outputs using the criteria in the image below:
Reflection questions
- Where did the playbook meaningfully improve the output?
- Where did it fail or produce worse results?
- How would you improve each file after reviewing the results?
Remember that agent specifications can improve consistency, but they don't guarantee correctness. Always verify the calculations and conclusions yourself.
Resources
Dataset
Starter templates
Specifications and references
These are starter files, not finished solutions. You'll get more value by using your judgement and domain knowledge to adapt them.
Creating an initial set of instructions takes time, but the files can be reused and improved across projects.
A Quick Note on YAML and Markdown
Markdown (.md) is a plain-text format that's easy to read and write. It's useful for describing an AI agent's role, goals, behaviour, and instructions. Think of it as an instruction manual.
YAML (.yaml or .yml) is a structured text format often used for configuration: models, tools, settings, and metadata. Configuration only has an effect if the software reading it understands those settings.
For this Data Drills challenge, the main content of your files will be written in Markdown. If you use the Agent Skills standard, however, the SKILL.md file also includes a small YAML frontmatter section for metadata such as the skill's name and description.
You don't need to build an agent platform to complete the challenge. Focus on writing clear instructions, testing them, and evaluating what actually improves.
Top comments (0)