Skip to content

docs(readme): drop the .agents/ multi-tool convention #11

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
WomB0ComB0 merged 1 commit into from
Apr 15, 2026
Merged

docs(readme): drop the .agents/ multi-tool convention #11

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
126 changes: 3 additions & 123 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,132 +88,12 @@ Common env vars across all of them:
| docs | MDX / Mintlify | `mintlify dev` |


## 🔧 AI-assisted development
## Contributor guide
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The header "Contributor guide" is missing an emoji, which is inconsistent with all other top-level headers in this README (e.g., ## ⚡ Onboarding, ## 📦 Repositories, ## 🛠 Standalone scripts). Adding an emoji like 🤝 would maintain the established visual style of the document.

Suggested change
## Contributor guide
## 🤝 Contributor guide


Every ResQ repo is structured for AI-assisted development. Human developers and AI tools (Claude Code, Cursor, Codex, Gemini, GitHub Copilot) share the same context through a standardized directory layout and canonical guidance files.
Every ResQ repo ships an `AGENTS.md` at the root — the canonical plain-text dev guide. That's where the build/test/lint commands, architecture notes, and standards for that specific repo live. Read it first.
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Since AGENTS.md is described as the "canonical plain-text dev guide" and the reader is encouraged to "Read it first", providing a direct link to the file improves navigation for developers exploring the repository.

Suggested change
Every ResQ repo ships an `AGENTS.md` at the root — the canonical plain-text dev guide. That's where the build/test/lint commands, architecture notes, and standards for that specific repo live. Read it first.
Every ResQ repo ships an [AGENTS.md](./AGENTS.md) at the root — the canonical plain-text dev guide. That's where the build/test/lint commands, architecture notes, and standards for that specific repo live. Read it first.


### The convention
Org-wide guidance (onboarding, hooks contract, commit format, PR process) lives in the `.github` org repo: [CONTRIBUTING.md](https://github.com/resq-software/.github/blob/main/CONTRIBUTING.md), [SECURITY.md](https://github.com/resq-software/.github/blob/main/SECURITY.md), [CODE_OF_CONDUCT.md](https://github.com/resq-software/.github/blob/main/CODE_OF_CONDUCT.md). Every public repo falls back to those automatically.

Inspired by [lobehub/lobehub](https://github.com/lobehub/lobehub), every repo follows this structure:

```
repo/
├── .agents/
│ └── skills/ # Source of truth for all AI skills
│ ├── <skill-name>/
│ │ └── SKILL.md # Self-contained skill definition
│ └── ...
│
├── .claude/ # Claude Code
│ ├── skills → ../.agents/skills # Symlink — shares skills
│ ├── commands/ # Slash commands (/command-name)
│ ├── prompts/ # Reusable prompt templates
│ └── settings.local.json # Permissions and tool config
│
├── .codex/ # OpenAI Codex
│ └── skills → ../.agents/skills # Symlink — shares skills
│
├── .cursor/ # Cursor IDE
│ ├── rules/ # Cursor-specific rules
│ └── docs/ # Reference docs for Cursor indexing
│
├── .gemini/ # Google Gemini
│
├── .github/
│ ├── agents/ # GitHub Copilot agent personas
│ ├── commands/ # Copilot slash commands
│ ├── rules/ # Copilot coding rules
│ ├── workflows/ # CI/CD pipelines
│ └── copilot-instructions.md # Copilot workspace instructions
│
├── .vscode/ # VS Code workspace settings
│
├── AGENTS.md # Canonical dev guide — THE source of truth
└── CLAUDE.md # Claude-specific (mirrors or extends AGENTS.md)
```

### Why `.agents/skills/` exists

Without it, the same skill gets copy-pasted into `.claude/skills/`, `.github/skills/`, `.cursor/skills/`, and `.codex/skills/`. They drift. Someone updates one, forgets the others. Now Claude knows about a pattern that Copilot doesn't.

`.agents/skills/` is the single authoring location. Each tool's directory symlinks to it:

```bash
# Every repo sets this up once
ln -s ../.agents/skills .claude/skills
ln -s ../.agents/skills .codex/skills
```

One edit, all tools see it.

### AGENTS.md contract

Every repo's `AGENTS.md` must contain these sections in this order:

```markdown
# <Repo Name> — Agent Guide

## Mission
One paragraph: what this repo does and why it exists.

## Workspace Layout
Directory tree with one-line descriptions of each top-level directory.

## Commands
The 5-8 commands a developer needs daily: build, test, lint, dev, deploy.

## 🏗 Architecture
Key design decisions: frameworks, patterns, data flow, boundaries.

## Standards
Conventions that apply to this repo: commit format, naming, linting rules,
what's forbidden (e.g., unsafe code, any types, mocks in integration tests).
```

`CLAUDE.md` can extend `AGENTS.md` with Claude-specific additions (tool permissions, slash commands, memory notes) but must not contradict it.

### Writing a skill

Skills live in `.agents/skills/<skill-name>/SKILL.md`. Each skill is a self-contained document that teaches an AI tool how to handle a specific domain or task.

```markdown
# <Skill Name>

## When to use
Describe the trigger: what task or file pattern activates this skill.

## Context
Background knowledge the AI needs before acting.

## Rules
Concrete, testable rules. Not vibes — things you can grep for in a diff.

## Examples
Before/after pairs or code snippets showing correct application.
```

**Repo-specific skills** go in that repo's `.agents/skills/`. For example, a UI library might have `component-authoring/SKILL.md` and `storybook-stories/SKILL.md`, while a Solana repo might have `anchor-accounts/SKILL.md`.

### Keeping things in sync

Every repo with both `AGENTS.md` and `CLAUDE.md` includes an `agent-sync.sh` script:

```bash
./agent-sync.sh --check # Verify they're in sync (CI runs this)
./agent-sync.sh # Sync CLAUDE.md from AGENTS.md
```

### Supported tools

| Tool | Config directory | Reads `AGENTS.md`? | Skill source |
|---|---|---|---|
| Claude Code | `.claude/` | Yes (via `CLAUDE.md`) | `.claude/skills → .agents/skills` |
| OpenAI Codex | `.codex/` | Yes | `.codex/skills → .agents/skills` |
| Cursor | `.cursor/` | Yes (via rules) | `.cursor/rules/` |
| Google Gemini | `.gemini/` | Yes | `.gemini/` |
| GitHub Copilot | `.github/` | Yes (via `copilot-instructions.md`) | `.github/agents/`, `.github/rules/` |

---

## 🔧 Toolchain

Expand Down
Loading