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