skills.rest
gaelic-ghost
gaelic-ghostCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

maintain-project-agents

Audit and normalize AGENTS.md files against a YAML schema.

6|Updated Apr 9, 2026
Search Tags:#automation#audit#agents.md#guardrails#normalize#schema-validation#repo-maintenance
One-click install
npx skills add https://github.com/gaelic-ghost/socket --skill maintain-project-agents
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: maintain-project-agents
Source: https://github.com/gaelic-ghost/socket/tree/main/plugins/productivity-skills/skills/maintain-project-agents
Command: npx skills add https://github.com/gaelic-ghost/socket --skill maintain-project-agents

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires pyyaml, and includes scripts (resource) and references (resource) and assets (resource) components.

What problem does it solve?

Repositories often lack a consistent, machine-checkable AGENTS.md structure which leads to unclear maintainer guidance, placeholder content, malformed command examples, and weak safety boundaries; this Skill provides a deterministic way to find and surface those issues and to apply bounded, template-backed fixes when requested.

Core Features & Use Cases

  • Deterministic Schema Validation: Validates top-level sections and required subsections against a YAML-backed canonical schema and flags missing or non-canonical headings.
  • Bounded Apply Mode: Creates a missing AGENTS.md from a bundled template or normalizes the document while keeping edits strictly limited to the target file.
  • Workflow and Safety Checks: Detects placeholder text, thin routing guidance, malformed or empty command blocks, and thin safety guidance and emits structured issues.
  • Audit Reporting: Produces both JSON and human-readable Markdown reports with a clear output contract for automation and manual review.
  • Use Case: Run during repository maintenance, CI checks, or a maintainer review to enforce durable, scan-friendly AGENTS.md guidance across projects.

Quick Start

Run the tool with the repository root and set run-mode to check-only to audit or to apply to normalize the AGENTS.md file.

Frequently Asked Questions about maintain-project-agents

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I audit an AGENTS.md file for missing sections and malformed commands?▼

To audit an AGENTS.md file, run the tool in check-only mode against your repository root to validate top-level sections, required subsections, and command blocks, producing JSON and Markdown reports of any structural issues.

How do I normalize an existing AGENTS.md structure across multiple repositories?▼

You can normalize an existing AGENTS.md structure by running the tool in apply mode, which enforces a canonical schema backed by a YAML configuration and template while strictly restricting edits to the target file.

What is schema validation for AGENTS.md files and how does it detect placeholders?▼

Schema validation for AGENTS.md files checks document headings against a canonical YAML-backed structure, detecting placeholder text, thin routing guidance, and empty command blocks to ensure clear maintainer guidance.

Can I use a YAML template to create a missing AGENTS.md file automatically?▼

Yes, you can use a YAML template to create a missing AGENTS.md file automatically by executing apply mode, which generates the document from a bundled template while preserving configured preambles.

Does the AGENTS.md normalization process commit changes or push to the repository?▼

No, the AGENTS.md normalization process does not commit or push changes; it restricts all edits strictly to the target file and leaves version control actions to the user.

What are the limitations of using YAML schema validation for repo maintenance?▼

A limitation of using YAML schema validation for repo maintenance is that it requires a predefined canonical schema and template, and it restricts all automated fixes solely to the AGENTS.md file without modifying other repository content.

Related Skills

Explore More Software Engineering Skills→
julianromlijulianromli
141

agents-md-generator

Generate root and per-package AGENTS.md templates for repository submodules.

Community
Advanced
leaderiopleaderiop
7

Packages Graph

Parse package manifests, construct graphs, and generate compliance reports.

Community
Intermediate
FernanSuozaFernanSuoza

gov-instruction-surface-synchronization

Synchronize sentinel-marked instruction blocks from a canonical source into editor-specific files.

Community
Advanced
gaelic-ghostgaelic-ghost
6

maintain-project-roadmap

Validate and enforce checklist-style ROADMAP.md files against a canonical schema.

Community
Intermediate