What does the skills-readme-alignment-maintainer do?

It audits README standards across *-skills repos using a two-pass workflow (audit first, then optional bounded fixes) to enforce consistent documentation, schema, and discoverability.

Can it automatically apply changes?

Only bounded fixes can be applied via --apply-fixes; it never commits changes automatically and only edits README files.

What outputs are produced?

A Markdown summary and a JSON report containing run_context, repos_scanned, profile_assignments, schema_violations, command_integrity_issues, fixes_applied, post_fix_status, and errors.

skills-readme-alignment-maintainer

Scanned

npx machina-cli add skill gaelic-ghost/productivity-skills/skills-readme-alignment-maintainer --openclaw

Files (1)

SKILL.md

3.4 KB

Skills README Alignment Maintainer

Run deterministic README standards maintenance for *-skills repositories in a workspace.

Inputs

Pass runtime inputs from the calling prompt:

--workspace <path>
--repo-glob <pattern> (default: *-skills)
--exclude <path> (repeatable)
optional --apply-fixes
optional --md-out, --json-out

Workflow

Run pass 1 audit with scripts/readme_alignment_maintainer.py.
Review profile assignments and issue categories.
If bounded remediation is desired, run pass 2 with --apply-fixes.
Re-check touched repos (handled by script).
Report Markdown and JSON outputs.

Commands

Audit only:

uv run python scripts/readme_alignment_maintainer.py \
  --workspace ~/Workspace \
  --repo-glob '*-skills' \
  --print-md \
  --print-json

Audit and bounded fixes:

uv run python scripts/readme_alignment_maintainer.py \
  --workspace ~/Workspace \
  --repo-glob '*-skills' \
  --apply-fixes \
  --md-out /tmp/readme-alignment-report.md \
  --json-out /tmp/readme-alignment-report.json

Fail when unresolved issues remain:

uv run python scripts/readme_alignment_maintainer.py \
  --workspace ~/Workspace \
  --repo-glob '*-skills' \
  --apply-fixes \
  --fail-on-issues

Safety Rules

Never commit changes automatically.
Edit README files only.
Never edit source code, manifests, lockfiles, CI files, or AGENTS.md.
Apply only bounded heading/schema/discoverability insertions and bootstrap README creation.
Keep diffs minimal and preserve existing style where possible.

Profile Model

Use references/profile-model.md:

public curated repos: enforce full schema including ## Customization Workflow Matrix, ## Install individually by Skill or Skill Pack, ## Update Skills, wrapped discoverability sections (## More resources for similar Skills with required nested ### subsections), and ## Keywords
private/internal repos: keep concise, omit growth-only sections
bootstrap repos: allow initial README creation with minimal complete structure

Output Contract

The script emits:

Markdown summary of run context, profile assignments, issues, fixes, remaining issues, and errors.
JSON report containing:
- run_context
- repos_scanned
- profile_assignments
- schema_violations
- command_integrity_issues
- fixes_applied
- post_fix_status
- errors

Use JSON for automation integration and Markdown for operator review.

Automation Templates

Use $skills-readme-alignment-maintainer in automation prompts.

For ready-to-fill Codex App and Codex CLI templates, use:

references/automation-prompts.md

References

Profile mapping: references/profile-model.md
Required sections by profile: references/section-schema.md
Voice and style rules: references/style-rules.md
Discoverability requirements: references/discoverability-rules.md
Verification checklist: references/verification-checklist.md
Seed standards artifacts: references/seed-artifacts.md
Automation prompt templates: references/automation-prompts.md

Source

git clone https://github.com/gaelic-ghost/productivity-skills/blob/main/skills-readme-alignment-maintainer/SKILL.mdView on GitHub

Overview

This skill runs deterministic README standards maintenance across *-skills repositories within a workspace. It uses a two-pass workflow: an initial audit and an optional bounded fixes pass to enforce profile-aware schemas, command integrity checks, and discoverability baselines for Codex App or CLI automation.

How This Skill Works

It invokes the readme_alignment_maintainer script to audit READMEs across matched repositories. After the audit, you can run a bounded fixes pass with --apply-fixes to patch only bounded sections, then re-check touched repos and generate Markdown and JSON outputs.

When to Use It

Auditing multiple *-skills repos to enforce a common README schema
Preparing Codex App or CLI automation runs to validate documentation consistency
Applying bounded fixes to align headings, sections, and discoverability without touching code
Reviewing profile assignments and issue categories to prioritize remediation
Generating Markdown and JSON run reports for operator review or automation pipelines

Quick Start

Step 1: Prepare your workspace and target repos (e.g., --workspace <path> --repo-glob '*-skills')
Step 2: Run the audit pass to produce Markdown/JSON output (e.g., --print-md --print-json)
Step 3: If needed, run the fixes pass with --apply-fixes and generate final reports

Best Practices

Do not auto-commit changes; only edit README files
Apply only bounded heading/schema/discoverability insertions
Always run the audit pass before attempting fixes
Verify post-fix status by re-checking touched repos
Preserve existing style and avoid editing non-readme files or source code

Example Use Cases

Audit public *-skills repos to ensure critical sections like Keywords and Discoverability exist
Audit internal/private repos and keep them concise by omitting growth-only sections
Bootstrap repos by creating minimal complete README structures
Run pass 1 audit, then pass 2 with --apply-fixes for standardized updates
Generate and inspect Markdown/JSON reports for stakeholders

Frequently Asked Questions

Add this skill to your agents