Get the FREE Ultimate OpenClaw Setup Guide →

mend-docs

npx machina-cli add skill yu-iskw/meta-agent-skills/mend-docs --openclaw
Files (1)
SKILL.md
2.7 KB

Mend Docs

This skill enables the automatic synchronization of documentation files with the available agents and skills in the repository.

Purpose

To ensure that README.md, CONTRIBUTING.md, and other public documentation files accurately list the capabilities of the agent without manual updates.

Instructions

  1. Discovery: Scan the following directories and categorize them:
    • Reusable Skills: Look for all SKILL.md files in skills/ (recursive).
    • Project Skills: Look for all SKILL.md files in .claude/skills/ (recursive).
    • Agents: Look for agent definitions or metadata in agents/ and .claude/agents/.
  2. 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.
  3. Target Identification: Identify documentation files and their respective markers:
    • README.md: Use <!-- REUSABLE_SKILLS_START --> and <!-- REUSABLE_SKILLS_END -->.
    • CONTRIBUTING.md: Use <!-- PROJECT_SKILLS_START --> and <!-- PROJECT_SKILLS_END -->.
  4. Formatting: Generate a table for each category.
    • Recommended format: A table with columns for Name, Description, and Link.
  5. Synchronization: Replace the content between the specific markers in the target documentation files.
    • Reusable skills go into README.md.
    • Project skills go into CONTRIBUTING.md.
    • CRITICAL: README.md MUST be written in English. Translate any non-English metadata (name, description) to English during the extraction/formatting phase for README.md.
  6. Verification: Ensure that the formatting is correct and all discovered skills are included in the correct file.

Markers

Reusable Skills (README.md)

<!-- REUSABLE_SKILLS_START -->
<!-- REUSABLE_SKILLS_END -->

Project Skills (CONTRIBUTING.md)

<!-- PROJECT_SKILLS_START -->
<!-- PROJECT_SKILLS_END -->

Example Table Format

<!-- markdown-link-check-disable -->
NameDescriptionLink
lint-fixIteratively run linters, apply auto-fixes, and resolve remaining issues..claude/skills/lint-fix/SKILL.md
<!-- markdown-link-check-enable -->

Source

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

Overview

Mend-docs automatically keeps public documentation up to date with the repository’s agents and skills. It scans SKILL.md files across reusable and project skills, plus agent metadata, and rewrites README.md and CONTRIBUTING.md to reflect current capabilities.

How This Skill Works

The tool discovers skills and agents by traversing specified directories, extracts name, description, and path from YAML frontmatter or folder names, then identifies target docs using predefined markers. It formats the results into tables (Name, Description, Link) and replaces the content between markers in README.md and CONTRIBUTING.md, translating non-English metadata for README.md when necessary.

When to Use It

  • When new skills or agents are added or updated and public docs need to reflect current capabilities
  • When preparing a PR or release that includes capability changes and needs automated documentation tables
  • When reusable and project skill catalogs drift out of date in README.md or CONTRIBUTING.md
  • When markers in README.md or CONTRIBUTING.md are missing or require re-synchronization
  • When ensuring the README remains English-only by translating non-English metadata during extraction/formatting

Quick Start

  1. Step 1: Run mend-docs to scan skills/ and agents/ for SKILL.md and metadata
  2. Step 2: Generate updated tables and replace the content between the markers in README.md and CONTRIBUTING.md
  3. Step 3: Review changes and commit to the repository (PR recommended)

Best Practices

  • Ensure every discovered skill/agent has a valid name, description, and relative path for accurate table entries
  • Keep README.md and CONTRIBUTING.md markers stable and correctly placed to avoid broken sections
  • Translate non-English metadata to English for README.md during extraction/formatting
  • Verify generated tables for correct links and up-to-date coverage of reusable and project skills
  • Run mend-docs as part of a PR/CI workflow to prevent drift between code and docs

Example Use Cases

  • Sync new reusable skills into README.md after adding SKILL.md files across skills/
  • Update project skills in CONTRIBUTING.md following a batch of skill updates in .claude/skills/
  • Translate non-English skill metadata to English for README.md to keep the document English-only
  • Add a new agent and let mend-docs refresh all related docs with updated capability listings
  • Regenerate tables to fix broken links and ensure all skills and agents are accurately listed

Frequently Asked Questions

Add this skill to your agents
Sponsor this space

Reach thousands of developers ↗