---
id: 10489
title: Unify Agent Skills Directory to `.agents` Standard
state: CLOSED
labels:
  - ai
  - refactoring
  - architecture
assignees: []
createdAt: '2026-04-29T11:42:12Z'
updatedAt: '2026-04-29T13:15:49Z'
githubUrl: 'https://github.com/neomjs/neo/issues/10489'
author: neo-gemini-pro
commentsCount: 0
parentIssue: null
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-04-29T13:15:49Z'
---
# Unify Agent Skills Directory to `.agents` Standard

## Context
We currently maintain an `.agent/` folder that symlinks to the `.agents/` directory. This was implemented as a fast hack to support Codex Desktop seamlessly while avoiding breaking Claude's configuration (which expects `.agent/`) during a period when Claude was unavailable due to rate limits.

## The Problem
While using symlinks ensures the single-source-of-truth is not technically violated, maintaining an unnecessary second top-level repository folder (`.agent`) is cumbersome and clutters the root directory.

## The Architectural Reality
Empirical verification confirms that as of April 2026, the Antigravity IDE natively recognizes and supports the `.agents/` (plural) folder standard for dotagents configurations. There is no technical limitation blocking us from migrating fully to the plural standard.

## The Fix
Unify the skill directory structure entirely under `.agents/`. All agent harnesses (Claude, Codex, Antigravity) must point to this canonical location.

## Acceptance Criteria
- [ ] Update Claude's environment configurations to natively target `.agents/` rather than `.agent/`.
- [ ] Delete the deprecated `.agent/` symlink/directory entirely.
- [ ] Ensure all `settings.json` or workspace configurations reference the `.agents/` structure.

## Out of Scope
- Rewriting or refactoring the actual markdown skills inside the folders; this is purely a directory normalization task.

## Avoided Traps / Gold Standards Rejected
- **Symlinking the roots:** Keeping both folders as "symlinked aliases" of each other. This is rejected because it pollutes the repository root and causes confusion for IDE file watchers and vector ingestion.

Origin Session ID: 240ae149-d3ba-4d68-9b4f-be2a359937e7

## Timeline

- 2026-04-29T11:42:13Z @neo-gemini-pro added the `ai` label
- 2026-04-29T11:42:13Z @neo-gemini-pro added the `refactoring` label
- 2026-04-29T11:42:13Z @neo-gemini-pro added the `architecture` label
- 2026-04-29T12:05:32Z @neo-gemini-pro cross-referenced by PR #10491
- 2026-04-29T12:06:05Z @neo-gemini-pro referenced in commit `4242a3d` - "chore(agents): unify skills directory under .agents/ standard (#10489)

Deletes the deprecated .agent/ symlink hack and moves all skill directories
natively into the plural .agents/ standard. Updates all references in AGENTS.md,
IDE configurations, and framework documentation."
- 2026-04-29T12:38:41Z @neo-gemini-pro referenced in commit `6e0d432` - "chore: migrate .agent to .agents directory (#10489)"
- 2026-04-29T12:46:03Z @neo-gemini-pro referenced in commit `2549aee` - "chore(agents): migrate .agent to .agents directory (#10489)"
- 2026-04-29T13:02:31Z @neo-gemini-pro referenced in commit `1464392` - "chore(agents): migrate .agent to .agents directory (#10489)"
- 2026-04-29T13:05:37Z @neo-gemini-pro referenced in commit `0e08376` - "chore(agents): migrate .agent to .agents directory (#10489)"
- 2026-04-29T13:10:51Z @neo-gemini-pro referenced in commit `5851ab7` - "chore(agents): migrate .agent to .agents directory (#10489)"
- 2026-04-29T13:15:49Z @tobiu referenced in commit `2003dca` - "chore(agents): migrate .agent to .agents directory (#10489) (#10491)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-04-29T13:15:50Z @tobiu closed this issue

