The State of AI Instruction Quality: Q3 2026
91% of the most-starred repos on GitHub give their coding agent at least one instruction that never says which file, command or tool it means. In April we measured 28,721 repos, and our own limitations section admitted that a 10-star side project counted the same as a 50,000-star production repo.
This article analyzes the state of AI instruction quality in the most-starred GitHub repositories, highlighting issues such as vague instructions, inconsistent quality, and the lack of hooks to enforce compliance.
What happened
The article evaluates the quality of AI instruction files in the most-starred GitHub repositories, identifying common issues such as vague instructions, inconsistent formatting, and the lack of hooks to enforce compliance. It highlights that 91.1% of repos have at least one vague instruction, and sub-agent files score the lowest in quality.
Why it matters
This analysis is crucial for AI developers and tool creators who rely on clear, actionable instructions to ensure their agents perform effectively. Poorly written instructions can lead to inefficiencies, errors, and suboptimal results, making this a key area for improvement.
- Vague instructions are a common issue in AI instruction files.
- Star count does not correlate with instruction quality.
- Sub-agent files are the most problematic in terms of quality.
- Only a small percentage of repos use hooks to enforce compliance.
- The ails check tool can help identify and improve instruction quality.
The bigger picture
The findings suggest that many AI tools and repositories lack clear, actionable instructions, which can hinder the performance of coding agents. This highlights the need for better practices in writing and structuring AI instructions.
The article underscores the importance of clear, actionable instructions in AI tools and repositories, highlighting the need for better practices in writing and structuring these instructions to improve performance and reliability.
Technical details
- CORE:C:0042: Vague instruction flag.
- AGENTS.md: Common instruction file format.
- Sub-agent files: Files that define specialist agents.
- Agent hooks: Scripts that enforce compliance with instructions.
- ails check: Tool used to evaluate instruction quality.
FAQ
What is a vague instruction?
A vague instruction is a directive or constraint that names no file, command, or tool, often found in sections where other lines do.
How is instruction quality measured?
Instruction quality is measured using the ails check tool, which evaluates files for issues like vague instructions, short instructions, and hedged language.
Why do sub-agent files score the lowest?
Sub-agent files are often persona prompts that lack specific details about the project, leading to lower quality scores.
How can I check my repo's instruction quality?
You can run the ails check tool using the command 'npx @reporails/cli check' to evaluate your repo's instruction quality.
What is the most common instruction file format?
The most common instruction file format is AGENTS.md, which is used in 61.6% of repos.
This summary and analysis were generated with AI from the original article and may contain errors. Read the original for the full story.
Read the full story
Originally published by Dev.to AI on Oct 13, 2026.
Comments
Sign in to join the discussion.