Skip to content

AGENTS.md: add comprehensive guide for AI assistants#21163

Open
FazleArefin wants to merge 6 commits intotldr-pages:mainfrom
FazleArefin:chore/skills
Open

AGENTS.md: add comprehensive guide for AI assistants#21163
FazleArefin wants to merge 6 commits intotldr-pages:mainfrom
FazleArefin:chore/skills

Conversation

@FazleArefin
Copy link
Member

@FazleArefin FazleArefin commented Feb 17, 2026

Description

This PR adds a generic AGENTS.md file to help AI coding assistants (Claude Code, GitHub Copilot, etc.) contribute effectively to tldr-pages.

Why this helps the project

Reduces review burden: AI assistants with access to our style guidelines will create PRs that require fewer corrections, saving maintainer time.

Improves contribution quality: New contributors using AI tools will get accurate, context-aware guidance specific to our format.

Assists PR reviewers: Maintainers and reviewers can use AI assistants with this guide to automatically verify PRs against project standards—checking format compliance, placeholder syntax, imperative mood usage, and platform directory rules—making reviews faster and more consistent.

Complements existing docs: This doesn't duplicate CONTRIBUTING.md or the style guide—it's a condensed reference optimized for quick parsing by AI assistants, with practical templates and examples.

What's included

  • Page format specification with examples
  • Platform directory rules
  • Placeholder and option syntax conventions
  • Language-specific translation rules
  • Testing procedures (tldr-lint)
  • Quick reference templates for common page types
  • "Common Tasks for AI Assistants" section

Why a separate file?

  • Discoverability: AI tools can find and read AGENTS.md automatically
  • Tool-agnostic: Works with any AI assistant, not tied to a specific platform
  • Maintainable: Single file, easy to update when guidelines change
  • Optional: Doesn't affect existing contributors who prefer the full docs

Testing

  • File follows markdown linting rules
  • Content aligns with current style guide and CONTRIBUTING.md
  • Commit message follows project convention

This makes the repository more accessible to the growing number of contributors using AI coding assistants while maintaining our quality standards.


Checklist

  • I have read and understood the Contributing Guidelines
  • I have linted the new file with tldr-lint (if applicable)
  • The commit message follows our guidelines
  • The changes are focused and don't include unrelated modifications

Add a generic skills file to help AI assistants (Claude Code, opencode,
etc.) understand and work with the tldr-pages repository effectively.

The guide includes:
- Project overview and structure
- Page format specification and style guidelines
- Platform directory rules and placeholder conventions
- Testing and linting procedures
- Language-specific translation rules
- Quick reference templates
- Common tasks for AI assistants

This makes the repository more accessible to contributors using
AI coding assistants.
@github-actions github-actions bot added the documentation Issues/PRs modifying the documentation. label Feb 17, 2026
@kbdharun kbdharun self-assigned this Feb 17, 2026
@FazleArefin FazleArefin changed the title SKILLS.md: add comprehensive guide for AI assistants AGENTS.md: add comprehensive guide for AI assistants Feb 18, 2026
@FazleArefin
Copy link
Member Author

FazleArefin commented Feb 18, 2026

After evaluation, I renamed SKILLS.md to AGENTS.md.

AGENTS.md is an emerging convention for providing instructions to AI coding agents. It is increasingly recognized by a growing ecosystem of tools such as OpenAI Codex, Cursor, GitHub Copilot, and other agent-based development environments. While some tools use vendor-specific files (for example, Claude Code uses CLAUDE.md), AGENTS.md serves as a vendor-neutral and tool-agnostic instruction entry point for repository-level AI guidance.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Issues/PRs modifying the documentation.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants

Comments