What does mend-agent-rules do?

It automates discovery, extraction, and synchronization of skills and agents into CLAUDE.md and AGENTS.md by updating the specified markers.

How does it identify content to include?

It scans .claude/skills for SKILL.md files and .claude/agents for agent definitions, pulling name, description, and relative path from YAML frontmatter or folder names.

What if the target docs miss markers or framework docs?

The tool relies on the defined markers. If markers are missing, it will not insert content; if FRAMEWORK_DOCS is missing in one file, it synchronizes by duplicating it from the other file.

mend-agent-rules

npx machina-cli add skill yu-iskw/meta-agent-skills/mend-agent-rules --openclaw

Files (1)

SKILL.md

3.0 KB

Mend Agent Rules

This skill automates the synchronization of CLAUDE.md and AGENTS.md using AI / LLM to ensure they always reflect the current state of the repository's agents and skills.

Purpose

To provide AI agents with up-to-date instructions and context about available specialized capabilities without manual maintenance.

Instructions

Discovery: Scan the following directories and categorize them:
- Project Skills: All SKILL.md files in .claude/skills/ (recursive).
- Agents: Agent definitions or metadata in .claude/agents/.
Extraction: For each skill/agent found, extract:
- name: From YAML frontmatter or directory name.
- description: From YAML frontmatter or first paragraph.
- path: Relative path from the workspace root.
Target Identification: Identify documentation files and their respective markers:
- CLAUDE.md and AGENTS.md:
  -  and 
  -  and 
  -  and 
Formatting:
- Skills List: Generate a table of all discovered project skills.
- Agents List: Generate a table of discovered agents.
Synchronization: Replace the content between the specific markers in BOTH target files.
- Update BOTH CLAUDE.md and AGENTS.md with the project skills table, agents table, and framework documentation.
- CRITICAL: The framework documentation (explaining what Agent Skills are, directory structure, and guidelines) MUST be present in both files between the FRAMEWORK_DOCS markers. If it is missing from one but present in the other, synchronize it.
Verification: Confirm that both files are identical except for their top-level headers (# CLAUDE.md vs # AGENTS.md) and that all markers are preserved.

Markers

CLAUDE.md

<!-- AVAILABLE_SKILLS_START -->
<!-- AVAILABLE_SKILLS_END -->

<!-- AVAILABLE_AGENTS_START -->
<!-- AVAILABLE_AGENTS_END -->

<!-- FRAMEWORK_DOCS_START -->
<!-- FRAMEWORK_DOCS_END -->

AGENTS.md

<!-- AVAILABLE_SKILLS_START -->
<!-- AVAILABLE_SKILLS_END -->

<!-- AVAILABLE_AGENTS_START -->
<!-- AVAILABLE_AGENTS_END -->

<!-- FRAMEWORK_DOCS_START -->
<!-- FRAMEWORK_DOCS_END -->

Example Table Format

Name	Description	Link
lint-fix	Iteratively run linters, apply auto-fixes, and resolve remaining issues.	.claude/skills/lint-fix/SKILL.md

Source

git clone https://github.com/yu-iskw/meta-agent-skills/blob/main/.claude/skills/mend-agent-rules/SKILL.mdView on GitHub

Overview

Mend-agent-rules keeps CLAUDE.md and AGENTS.md up to date by scanning .claude/skills and .claude/agents, extracting name, description, and path, and rebuilding the sections between markers. It ensures both docs always reflect the repository's current skills and agents, with a shared framework docs block.

How This Skill Works

It uses an AI/LLM to discover skills and agents, extracts metadata from YAML frontmatter or folder names, formats the data into markdown tables, and replaces the content between AVAILABLE_SKILLS_START/END and AVAILABLE_AGENTS_START/END in both docs. It also cross-checks to ensure FRAMEWORK_DOCS appears identically in both files.

When to Use It

When new SKILL.md files are added or existing ones are updated in .claude/skills/, to refresh CLAUDE.md and AGENTS.md
When new agents are defined or agent metadata changes in .claude/agents/, to keep AGENTS.md current
When documentation drifts due to manual edits and you want a predictable, synchronized state
When preparing PRs or releases, to ensure both docs reflect the latest capabilities
During onboarding of new contributors, to bootstrap consistent documentation

Quick Start

Step 1: Run mend-agent-rules in the repo root to scan skills and agents
Step 2: Review the generated tables between the AVAILABLE_* markers in CLAUDE.md and AGENTS.md
Step 3: Commit and push the changes to your branch/PR

Best Practices

Ensure the DISCOVERY paths (.claude/skills and .claude/agents) are accessible to the tool
Keep YAML frontmatter consistent for reliable name/description extraction
Maintain the three marker blocks in CLAUDE.md and AGENTS.md and avoid manual edits inside them
Run a quick verification to confirm both files are identical except for their top headers
Back up the docs before running synchronization in CI or production environments

Example Use Cases

Add a new Skill SKILL.md under .claude/skills and run mend-agent-rules to update both docs
Update an Agent's metadata in .claude/agents and re-sync
Repair missing FRAMEWORK_DOCS blocks by copying content from one file to the other
PR-triggered sync to ensure CLAUDE.md and AGENTS.md reflect the latest state before review
Audit and fix broken links in the generated skills table after a sync

Frequently Asked Questions

Add this skill to your agents