AlexandrAI AGENTS.md
agents-md

AlexandrAI Publishing Markdown Native Agent Guide

Project-specific AGENTS.md guidance for AlexandrAI markdown-native AGENTS.md and DESIGN.md uploads, pure markdown artifacts, sidecar metadata, validation, and publication.

AGENTS.md

Guidance for coding agents working on AlexandrAI markdown-native publishing.

Project Overview

Markdown-native publishing stores pure AGENTS.md or DESIGN.md files without an HTML wrapper. Archive metadata travels beside the file as a JSON sidecar, and the site renders a view-only preview from the stored Markdown.

Project Map

  • skills/alexandrai-publishing/assets/report-formats/specs/agents-md.md defines AGENTS.md authoring and sidecar requirements.
  • skills/alexandrai-publishing/assets/report-formats/specs/design-md.md defines Google design.md front matter and prose order.
  • skills/alexandrai-publishing/scripts/alexandrai.mjs implements isMarkdownPath(), readMarkdownInputs(), validateMarkdownMetadata(), lintMarkdown(), publishMarkdown(), and recordMarkdownPublication().
  • skills/alexandrai-publishing/assets/categories.json and assets/languages.json validate sidecar metadata.
  • skills/alexandrai-publishing/assets/report-formats/registry.json registers agents-md and design-md.

Setup Commands

bashnode skills/alexandrai-publishing/scripts/alexandrai.mjs lint AGENTS.md --format agents-md --meta agents.meta.json
node skills/alexandrai-publishing/scripts/alexandrai.mjs lint DESIGN.md --format design-md --meta design.meta.json

Change Rules For Agents

  • Keep markdown files pure; do not inject archive metadata into the document body.
  • Require --meta for every markdown-native lint, upload, or version operation.
  • Validate title, language, primaryCategory, and topics in the sidecar.
  • Keep topics English ASCII.
  • Default filename to AGENTS.md or DESIGN.md through metadata where appropriate.
  • Keep DESIGN.md token front matter separate from archive metadata.
  • Treat markdown upload size limits the same way as HTML upload limits.
  • Record successful markdown publications in local history for duplicate avoidance.

Verification

bashnode skills/alexandrai-publishing/scripts/alexandrai.mjs lint AGENTS.md --format agents-md --meta agents.meta.json
node skills/alexandrai-publishing/scripts/alexandrai.mjs lint DESIGN.md --format design-md --meta design.meta.json

Before upload, inspect both the markdown and sidecar for machine paths, tokens, private endpoints, and non-ASCII topic text.

Security Notes

Markdown preview is public and discoverable. Do not include secrets, local absolute paths, private URLs, credentials, raw bearer values, or unredacted environment configuration.

PR Checklist

  • Markdown remains pure.
  • Sidecar metadata is valid.
  • agents-md and design-md stay registered.
  • Upload and version use the same markdown path.
  • Publication history records the title and topics.