AGENTS.md Format Specification

AGENTS.md is a skill description file generated by OpenSkills that tells AI agents (such as Claude Code, Cursor, Windsurf, etc.) which skills are available and how to invoke them.

What You'll Learn

After completing this lesson, you will be able to:

• Understand the XML structure of AGENTS.md and the meaning of each tag
• Understand the field definitions and usage constraints of skill lists
• Know how to manually edit AGENTS.md (not recommended, but sometimes necessary)
• Understand how OpenSkills generates and updates this file

Complete Format Example

Below is a complete AGENTS.md file example:

# AGENTS

<skills_system priority="1">

## Available Skills

<!-- SKILLS_TABLE_START -->
<usage>
When users ask you to perform tasks, check if any of the available skills below can help complete task more effectively. Skills provide specialized capabilities and domain knowledge.

How to use skills:
- Invoke: `npx openskills read <skill-name>`
- For multiple: `npx openskills read skill-one,skill-two`
- The skill content will load with detailed instructions on how to complete task
- Base directory provided in output for resolving bundled resources (references/, scripts/, assets/)

Usage notes:
- Only use skills listed in <available_skills> below
- Do not invoke a skill that is already loaded in your context
- Each skill invocation is stateless
</usage>

<available_skills>

<skill>
<name>open-source-maintainer</name>
<description>End-to-end GitHub repository maintenance for open-source projects. Use when asked to triage issues, review PRs, analyze contributor activity, generate maintenance reports, or maintain a repository.</description>
<location>project</location>
</skill>

<skill>
<name>pdf</name>
<description>Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms.</description>
<location>global</location>
</skill>

</available_skills>
<!-- SKILLS_TABLE_END -->

</skills_system>

Tag Structure Explained

Outer Container: <skills_system>

<skills_system priority="1">
  <!-- Skill content -->
</skills_system>

• priority: Priority marker (fixed to "1"), tells AI agents the importance level of this skill system

Note

The priority attribute is reserved for future expansion. All AGENTS.md files use the fixed value "1".

Usage Instructions: <usage>

The <usage> tag contains guidance on how AI agents should use skills:

<usage>
When users ask you to perform tasks, check if any of the available skills below can help complete task more effectively. Skills provide specialized capabilities and domain knowledge.

How to use skills:
- Invoke: `npx openskills read <skill-name>`
  - For multiple: `npx openskills read skill-one,skill-two`
- The skill content will load with detailed instructions on how to complete task
- Base directory provided in output for resolving bundled resources (references/, scripts/, assets/)

Usage notes:
- Only use skills listed in <available_skills> below
- Do not invoke a skill that is already loaded in your context
- Each skill invocation is stateless
</usage>

Key Points:

• Trigger Condition: Check if the user's task can be completed more effectively using a skill
• Invocation Method: Use the npx openskills read <skill-name> command
• Batch Invocation: Supports comma-separated multiple skill names
• Base Directory: The output includes a base_dir field for resolving referenced files in skills (such as references/, scripts/, assets/)
• Usage Constraints:
  • Only use skills listed in <available_skills>
  • Do not reload skills that are already in context
  • Each skill invocation is stateless

Skill List: <available_skills>

<available_skills> contains a list of all available skills, with each skill defined by a <skill> tag:

<available_skills>

<skill>
<name>skill-name</name>
<description>Skill description...</description>
<location>project</location>
</skill>

<skill>
<name>another-skill</name>
<description>Another skill description...</description>
<location>global</location>
</skill>

</available_skills>

<skill> Tag Fields

Each <skill> contains the following required fields:

Field	Type	Valid Values	Description
<name>	string	-	Skill name (must match SKILL.md filename or name in YAML)
<description>	string	-	Skill description (from SKILL.md's YAML frontmatter)
<location>	string	project | global	Skill installation location marker (for AI agents to understand source)

Field Explanations:

• <name>: The unique identifier of the skill, used by AI agents to invoke the skill
• <description>: Detailed explanation of the skill's functionality and usage scenarios, helping AI determine whether this skill is needed
• <location>:
  • project: Installed locally in the project (.claude/skills/ or .agent/skills/)
  • global: Installed in the global directory (~/.claude/skills/)

Why do we need the location marker?

The <location> marker helps AI agents understand the visibility scope of skills:

• project skills are available only in the current project
• global skills are available in all projects This affects the AI agent's skill selection strategy.

Markup Methods

AGENTS.md supports two markup methods that OpenSkills automatically recognizes:

Method 1: XML Markup (Recommended)

<skills_system priority="1">
  <!-- Skill content -->
</skills_system>

This is the default method, using standard XML tags to mark the beginning and end of the skills system.

Method 2: HTML Comment Markup (Compatibility Mode)

<!-- SKILLS_TABLE_START -->

## Available Skills

<usage>
  <!-- Usage instructions -->
</usage>

<available_skills>
  <!-- Skill list -->
</available_skills>

<!-- SKILLS_TABLE_END -->

This format removes the outer <skills_system> container and only uses HTML comments to mark the beginning and end of the skill section.

OpenSkills Processing Logic

The replaceSkillsSection() function (src/utils/agents-md.ts:67-93) searches for markers in the following priority order:

1. First searches for <skills_system> XML marker
2. If not found, searches for <!-- SKILLS_TABLE_START --> HTML comment
3. If neither is found, appends content to the end of the file

How OpenSkills Generates AGENTS.md

When executing openskills sync, OpenSkills will:

1. Find all installed skills (findAllSkills())
2. Interactive skill selection (unless using the -y flag)
3. Generate XML content (generateSkillsXml())
   • Build <usage> instructions
   • Generate <skill> tags for each skill
4. Replace the skill section in the file (replaceSkillsSection())
   • Search for existing markers (XML or HTML comments)
   • Replace content between markers
   • If no markers exist, append to the end of the file

Source Code Locations

Function	File Path	Line Numbers
Generate XML	src/utils/agents-md.ts	23-62
Replace skill section	src/utils/agents-md.ts	67-93
Parse existing skills	src/utils/agents-md.ts	6-18

Manual Editing Considerations

Manual Editing Not Recommended

Although you can manually edit AGENTS.md, we recommend:

1. Use the openskills sync command to generate and update
2. Manually edited content will be overwritten during the next sync
3. If you need to customize the skill list, use interactive selection (without the -y flag)

If you do need to edit manually, please note:

1. Keep XML syntax correct: Ensure all tags are properly closed
2. Do not modify markers: Preserve <skills_system> or <!-- SKILLS_TABLE_START --> markers
3. Complete fields: Each <skill> must contain <name>, <description>, and <location> fields
4. No duplicate skills: Do not add skills with duplicate names

Common Questions

Q1: Why doesn't AGENTS.md sometimes have the <skills_system> tag?

A: This is compatibility mode. If your file uses HTML comment markers (<!-- SKILLS_TABLE_START -->), OpenSkills will also recognize it. It will automatically convert to XML markup during the next sync.

Q2: How do I delete all skills?

A: Execute openskills sync and deselect all skills in the interactive interface, or run:

openskills sync -y --output /dev/null

This will clear the skill section in AGENTS.md (but preserve the markers).

Q3: Does the location field have a practical impact on AI agents?

A: This depends on the specific AI agent implementation. Generally:

• location="project" indicates the skill is only meaningful in the current project context
• location="global" indicates the skill is a universal tool that can be used in any project

AI agents may adjust their skill loading strategy based on this marker, but most agents (like Claude Code) ignore this field and directly invoke openskills read.

Q4: How long should skill descriptions be?

A: Skill descriptions should:

• Concise but complete: Explain the skill's core functionality and main usage scenarios
• Avoid being too short: Single-line descriptions make it difficult for AI to understand when to use
• Avoid being too long: Overly long descriptions waste context, and AI won't read them carefully

Recommended length: 50-150 words.

Best Practices

1. Use the sync command: Always use openskills sync to generate AGENTS.md, not manual editing
2. Update regularly: After installing or updating skills, remember to run openskills sync
3. Select appropriate skills: Not all installed skills need to be in AGENTS.md; select based on project requirements
4. Check the format: If AI agents cannot recognize skills, check if the XML tags in AGENTS.md are correct

Up Next

In the next lesson, we'll learn File Structure.

You will learn:

• The directory and file structure generated by OpenSkills
• The purpose and location of each file
• How to understand and manage skill directories

---

Appendix: Source Code Reference

Click to expand source code locations

Updated: 2026-01-24

Function	File Path	Line Numbers
Generate skill XML	src/utils/agents-md.ts	23-62
Replace skill section	src/utils/agents-md.ts	67-93
Parse existing skills	src/utils/agents-md.ts	6-18
Skill type definition	src/types.ts	1-6

Key Constants:

• priority="1": Skills system priority marker (fixed value)

Key Functions:

• generateSkillsXml(skills: Skill[]): Generate XML-formatted skill list
• replaceSkillsSection(content: string, newSection: string): Replace or append skill section
• parseCurrentSkills(content: string): Parse enabled skill names from AGENTS.md