AGENTS.md vs SKILL.md: Distinguishing Instruction Files for AI Agents

X postJaydeepDiscussion

A post by Jaydeep raises the question of the difference between AGENTS.md and SKILL.md, prompting developers to debate their roles in steering AI coding agents.

Key points

  1. Jaydeep questions the distinction between AGENTS.md and SKILL.md.
  2. Community members such as Anupam Haldkar characterise AGENTS.md as an always-on project handbook covering repo conventions, architecture, and commands placed at the start of the LLM context.
  3. SKILL.md is described as an on-demand task playbook loaded dynamically when a specific task or feature matches.

Why it matters

Effective context management is critical when using AI coding assistants. Distinguishing persistent repository rules from modular, task-specific skill instructions helps optimize token usage and model attention.

Analysis

The original post is minimal, presenting solely the question. Value comes from the community replies, which converge on viewing AGENTS.md as the baseline repository guidance and router, whereas SKILL.md serves as reusable, function-like task prompts.

Original post

Jaydeep

@_jaydeepkarale · 30 August 2026

AGENTS. md vs SKILL. md What's the difference? t.co/gbCAnmIiNj

849 likes15 replies1k bookmarks97.7k views

View on X
More posts in the thread (1)
  1. @juvfbmoiy Thank you
Selected replies (5)
  • @patilvishi @_jaydeepkarale They solve different problems... I was actually exploring this recently in our project, especially the AGENTS.md file inside Cursor, and that's where the distinction became clearer to me... AGENTS.md → tells the AI how to work in your project Coding conventions, architecture
  • @gsemetfr @_jaydeepkarale The main difference between t.co/kBHe1DncPs and SKILL.md is the content of AGENTS.md is always at the start of the context, so in the « attention zone » of the LLM. it usually point to other resources than the agent will load when needed.
  • @AnupamHaldkar @_jaydeepkarale AGENTS. md is the always-on project handbook (repo rules, commands, conventions) SKILL. md is the on-demand playbook the agent loads only when the specific task matches.
  • @vivek_naskar @_jaydeepkarale AGENTS.md is like the project instructions to work in a particular repo. Whereas, SKILLS.md is like the set of instructions for doing tasks.
  • @Official_m9g @_jaydeepkarale They're just reproducible requirements docs in markdown. What if I just name it README.md and let my LLM read and follow the rules? It'll be the same as agent.md or skill.md.

Mentioned links

Links and tools from this entry

Summary generated by AI (Gemini 3.8 Flash, 27 September 2026). It may contain errors – the original source is authoritative.

Related entries

Similar in content, found by the AI search.

  • X post:PostHog

    The Evolving Role of AGENTS.md and CLAUDE.md Context Files

    This discussion explores the effectiveness of using context files like AGENTS.md or CLAUDE.md to guide AI coding assistants. While some developers find them essential for project-specific instructions, others argue they often become technical debt that grows stale and hinders model performance.

    1.1kbookmarks48kviews

    AI & LLMs

  • X post:Kun Chen

    Treating AGENTS.md like a neural net: Kun Chen's guide to agent memory files

    Kun Chen proposes an engineering framework for managing AGENTS.md and CLAUDE.md files: user-level preferences should be handwritten, while repository-level instructions should be treated like a neural network with a strict token budget and refined via backward passes on real session transcripts.

    2.8kbookmarks93.5kviews

    AI & LLMs· Opinion

  • Repository:coleam00/skills

    Cole's AI Skills: Modular Skill Files for Coding Agents

    The GitHub repository 'coleam00/skills' provides a collection of 33 practical skills designed for AI coding agents such as Claude Code. Instead of maintaining a monolithic 2,000-line CLAUDE.md instruction file, each skill resides in a standalone folder with a SKILL.md file and is loaded on demand. The set revolves around a standard development cycle: prime, plan, implement, validate, review, commit, and PR.

    482starsPython

    AI & LLMs· Tool

  • Link:Anthropic

    Agent Skills: An Open Standard for Modular AI Agent Capabilities

    Agent Skills is an open format designed to equip AI agents with specialised domain knowledge and repeatable workflows. Centred around a directory containing a SKILL.md file, it relies on progressive disclosure to keep context overhead minimal.

    AI & LLMs· Resource

  • Article:Anthropic

    How Claude Code Retains Project Context: CLAUDE.md and Auto Memory Explained

    Anthropic outlines the memory architecture of Claude Code. Because every session starts with a clean context window, the CLI tool relies on two complementary systems: user-defined CLAUDE.md files for explicit instructions and an auto memory feature that records learnings from user feedback.

    AI & LLMs· Resource

Back to the knowledge base

Let's talk about your project

Get in touch

Locations

  • Mattersburg
    Johann Nepomuk Bergerstraße 7/2/14
    7210 Mattersburg, Austria
  • Vienna
    Ungargasse 64-66/3/404
    1030 Wien, Austria

Parts of this content were created with the assistance of AI.