| name | ai-self-improvement |
| description | Update, create, improve, and synchronise this repository's AI agent instructions and related assets (including skills). Use when the user asks to create or edit a skill/SKILL.md, modify the agent's own instructions/processes, restructure instruction governance, migrate instruction content into skills, or run/adjust the sync pipeline that publishes `.ai/` sources into agent-specific folders. Load this skill before writing any SKILL.md, .instructions.md, or touching any skills/ folder (.ai/, .claude/, .roo/, .github/). It tells you the correct location (.ai/) and the sync step, so files end up in the right place. |
AI Self-Improvement (Instructions + Skills + Agents)
Critical: .ai/ is the Primary Source for ALL Agents
The .ai/ folder is the single source of truth for all AI agent configurations in this repository. Agent definitions are stored in agents.json and the sync script propagates changes automatically.
What gets synced
| Asset | Source | Scope | Description |
|---|
| Instructions | .ai/*instructions.md | Project | Agent rules and guidelines |
| Skills | .ai/skills/ | Project | Reusable skill definitions |
| Custom agents | .ai/agents/ | Project | Agent prompt templates for this repository |
| Global agents | .ai/.global/agents/ | User | Agent prompt templates for ALL repositories (synced with -Global flag) |
Agent configuration (agents.json)
The file agents.json (next to this SKILL.md) defines each agent's sync targets:
| Agent | Instructions | Skills | Project Agents | Global Agents | Shared .agents/ |
|---|
| Cline | .clinerules/ (multiple) | — | — | — | ❌ |
| Roo Code ⚠️ sunset 2026-05-15 | .roo/rules/ (multiple) | .roo/skills/ | .roomodes (JSON) | {AppData}/.../custom_modes.yaml (JSON) | ✅ skills (project + user) |
| GitHub Copilot | .github/copilot-instructions.md (single) | .github/skills/ | .github/agents/ | — | ✅ skills (project + user) |
| OpenAI Codex | AGENTS.md (single) | — | — | — | ✅ skills (project + user) |
| Claude Code | .claude/ (multiple) | .claude/skills/ | .claude/commands/ | ~/.claude/commands/ | ❌ |
| Kilo Code | .kilo/rules/ (multiple) | .kilo/skills/ | .kilo/agents/ | ~/.config/kilo/agent/ | ✅ skills (project + user) |
| Gemini CLI | GEMINI.md (single) | .gemini/skills/ | .gemini/agents/ | ~/.gemini/agents/ | ✅ skills (project + user) |
Path arrays — primary + obsolete
skills and globalSkills in agents.json are ordered arrays:
- Position 0 is the PRIMARY target. The sync script mirrors only there.
- Positions 1+ are OBSOLETE alternatives the agent may still read. The script does not write to them, but it scans for them after each sync and reports any that still exist on disk so you can clean them up.
Multiple agents may declare the same primary path (e.g. Roo Code, Kilo Code, Codex, Copilot, and Gemini all share .agents/skills). The script deduplicates so each unique target is mirrored once.
Migration is just rearranging the array. When a vendor adopts the universal .agents/ convention, prepend the new path:
"skills": [".claude/skills"]
"skills": [".agents/skills", ".claude/skills"]
The next sync will mirror to .agents/skills and report .claude/skills as obsolete (delete when ready).
Universal .agents/ folder
Several modern agents read skills from a shared .agents/skills/ (project) and ~/.agents/skills/ (user) — Codex CLI, GitHub Copilot, Roo Code, Kilo Code, Gemini CLI, OpenCode, Antigravity. To opt an agent in, just put .agents/skills at position 0 of its skills array.
Cline and Claude Code do not currently support the .agents/ convention — they keep using their own paths. Instructions are not synced into .agents/ because the universal convention there is AGENTS.md (or GEMINI.md) at the repository root, already covered by the Codex/Gemini single-file targets. MCP servers are tracked per-agent in agents.json for reference only — MCP sync is not performed by this script.
IMPORTANT: When asked to modify skills, instructions, or custom agents, you MUST:
- Locate the source file under
.ai/ (not the agent-specific output)
- Make changes to the
.ai/ source
- Run the sync script to propagate changes to all agents
Custom agents format
Source files in .ai/agents/ use YAML frontmatter + markdown body. The frontmatter captures metadata for all platforms, and the sync script transforms to each platform's native format:
- GitHub Copilot — synced directly to
.github/agents/ (native Copilot agent format)
- Claude Code — synced to
.claude/commands/ (Claude uses the full file as a slash command)
- Roo Code — transformed into
.roomodes JSON (maps name → name, description → roleDefinition, body → customInstructions, groups → groups)
---
name: Repository Analyze and Sync
description: Regenerate the architecture map and sync changes to all agents.
tools: ["search", "edit", "runCommands"]
groups: ["read", "edit", "command"]
---
Prompt instructions here...
| Field | Copilot | Claude | Roo Code |
|---|
name | Agent display name | — | Mode display name |
description | Agent description | — | roleDefinition |
tools | Tool access list | — | — |
groups | — | — | Permission groups (read, edit, command, mcp) |
| Body | Agent instructions | Slash command prompt | customInstructions |
Path Mapping Reference
When you encounter a path in an agent-specific folder, map it to .ai/:
| Agent-Specific Path | Source Path (Edit Here) |
|---|
.roo/rules/*.md | .ai/*.instructions.md |
.roo/skills/<name>/SKILL.md | .ai/skills/<name>/SKILL.md |
.github/copilot-instructions.md | .ai/instructions.md (generated) |
.github/agents/<name>.md | .ai/agents/<name>.md |
AGENTS.md | .ai/instructions.md (generated) |
.claude/*.instructions.md | .ai/*.instructions.md |
.claude/skills/<name>/SKILL.md | .ai/skills/<name>/SKILL.md |
.claude/commands/<name>.md | .ai/agents/<name>.md |
.agents/skills/<name>/SKILL.md | .ai/skills/<name>/SKILL.md |
~/.agents/skills/<name>/SKILL.md | .ai/.global/skills/<name>/SKILL.md |
.kilo/rules/*.md | .ai/*.instructions.md |
.kilo/skills/<name>/SKILL.md | .ai/skills/<name>/SKILL.md |
.kilo/agents/<name>.md | .ai/agents/<name>.md |
GEMINI.md | .ai/instructions.md (generated, single-file like AGENTS.md) |
.gemini/skills/<name>/SKILL.md | .ai/skills/<name>/SKILL.md |
.gemini/agents/<name>.md | .ai/agents/<name>.md |
Example: If asked to update .roo/skills/ai-self-improvement/SKILL.md, you must edit .ai/skills/ai-self-improvement/SKILL.md instead.
Editable files (sources of truth)
.ai/instructions.md — the main system instructions file.ai/*instructions.md — additional instruction files (auto-included).ai/*instructions-detail.md — detailed instruction files (read only when needed).ai/skills/<name>/SKILL.md — skill definition files.ai/agents/<name>.md — project-level agent prompt templates.ai/.global/agents/<name>.md — global agent prompt templates (all repositories)
Workflow
- Treat
.ai/ as the single source of truth for agent instructions, skills, and custom agents.
- When creating or migrating a skill, create/update it under
.ai/skills/.
- When creating a custom agent, create it under
.ai/agents/ using YAML frontmatter + markdown.
- Make instruction changes in
.ai/instructions.md and related *.instructions.md files.
- Do not edit generated outputs directly (they are produced by the sync script):
.roo/rules/, .roo/skills/.github/copilot-instructions.md, .github/skills/, .github/agents/AGENTS.md, GEMINI.md.claude/*.instructions.md, .claude/skills/, .claude/commands/.kilo/rules/, .kilo/skills/, .kilo/agents/.gemini/skills/, .gemini/agents/.agents/skills/, ~/.agents/skills/ (universal convention)
- Test changes before syncing — verify scripts execute correctly and changes work as expected.
- After testing, run the sync script to apply to all agents.
Testing Before Sync
Before running the sync script, always verify your changes work correctly:
- For script changes: Execute the modified script and verify output is correct
- For instruction changes: Review the markdown renders properly and instructions are clear
- For skill changes: Test any bundled tools or scripts included in the skill
Activation process
After editing instruction files, skills, or custom agents, run from repository root. The script is cross-platform (Windows, macOS, Linux) and requires Python 3.8+.
python .ai/skills/ai-self-improvement/scripts/sync_agent_assets.py AUTO
python .ai/skills/ai-self-improvement/scripts/sync_agent_assets.py AUTO --global
On Windows, python may need to be py or python3 depending on how Python is installed.
Sync modes
| Mode | Description |
|---|
AUTO | Update only agents detected in this repository (default) |
ALL | Update all known agent outputs |
| Agent name | Update a specific agent (e.g. "Claude Code", roo-code) |
--global | Also sync .ai/.global/agents/ to user-level paths (off by default) |
--cleanup-obsolete | After sync, prompt to delete legacy folders flagged as obsolete in agents.json (positions 1+ of skills/globalSkills arrays). Safe — y/N confirmation required. |
--no-clear | Do not clear the console on start; also skips the 4-second exit pause (signals scripted/piped use). |
When invoked without arguments, the menu offers: AUTO, AUTO + Global, Cleanup (option 3), then numbered entries for each agent. ALL / ALL + Global are still supported as CLI parameters but no longer in the menu — they were rarely used.
Menu indicators
- Bold green name — agent is detected in this repository (its signature folder or instructions target exists on disk).
[supported] suffix — agent is fully .agents/-compatible, meaning every one of its outputs lands under .agents/ (or — for single-file outputs only — at the repository root). Such an agent needs no agent-specific folder. Currently only OpenAI Codex qualifies (AGENTS.md + .agents/skills/). The flag is computed from agents.json, so any other agent automatically lights up the moment its config is rewritten to drop agent-specific paths.
Detection and stale-file behavior
- Empty folders count as enabled. AUTO detection treats an agent as enabled when its target folder exists at the repository root, even if it is empty. Wiping the contents of
.roo/rules/, .clinerules/, or .claude/ does not disable the agent — the next sync repopulates it. For single-file agents (Codex, Copilot), the file or its companion folder counts.
- Stale instruction files are removed before copy. Before copying instructions, the script deletes any
*instructions.md files in the target folder that are not present in .ai/. Renaming or removing a source file removes the matching target file on the next sync, instead of leaving a stale copy behind.
Single source of truth
Never embed template content in instructions — reference template files instead.
- "Template maintained in
pr/checklist.template.md"
- Do not paste template content into instructions
Bundled files
- Agent config:
.ai/skills/ai-self-improvement/agents.json
- Sync script (Python, cross-platform):
.ai/skills/ai-self-improvement/scripts/sync_agent_assets.py
