Skip to content

SKILL.md

Latest commit

 

History

History
250 lines (201 loc) · 8.07 KB

SKILL.md

File metadata and controls

250 lines (201 loc) · 8.07 KB
Raw
name mrrs-standard
description Apply the Machine-Readable Repo Standard (MRRS) to any GitHub repository. Makes repos understandable by non-technical users, developers, and AI agents. Generates structured documentation with mermaid diagrams, three-tier READMEs, REPO_MANIFEST.yml metadata, and plain-english concept explainers.
compatible_clients
Claude Code
Claude Desktop
Gemini CLI
OpenCode
Blackbox AI
Mistral (via Cloudflare Workers AI)
Cursor
Windsurf
Cline
Aider
Continue.dev
Any MCP-compatible AI client

Machine-Readable Repo Standard (MRRS) — Universal AI Skill

This skill works with any AI coding assistant that reads markdown instruction files. No vendor lock-in.

Client Compatibility

This skill follows standard markdown instruction format. To use it:

Client How to Load
Claude Code Add to ~/.claude/skills/ or reference in CLAUDE.md
Claude Desktop Add to Project Knowledge
Gemini CLI Reference in GEMINI.md or project instructions
OpenCode Add to project context or .opencode/instructions.md
Blackbox AI Add to workspace instructions
Mistral / Cloudflare Include in system prompt or project context
Cursor Add to .cursorrules or project docs
Windsurf Add to .windsurfrules or workspace context
Cline Add to .clinerules or custom instructions
Aider Reference via --read flag or .aider.conf.yml
Continue.dev Add to .continuerc.json context providers
Any MCP client Serve as MCP resource or include in project root

When to Use This Skill

Trigger this skill when the user wants to:

  • Make a repo understandable by non-technical people
  • Add structured documentation to an existing project
  • Create a new repo with proper documentation from the start
  • Generate a REPO_MANIFEST.yml for machine readability
  • Create visual architecture docs with mermaid diagrams
  • Build a "DeepWiki-like" experience without external tools
  • Apply documentation standards across multiple repos
  • Make a repo AI-agent-friendly

What MRRS Produces

Every MRRS repo gets these files:

File Purpose Audience
README.md Three-tier progressive disclosure Everyone
ARCHITECTURE.md System design with mermaid diagrams Developers + AI
QUICKSTART.md Dual-path: non-technical + developer Users
.github/REPO_MANIFEST.yml Structured YAML metadata AI agents + tools
docs/CONCEPTS.md Plain-english explainer with analogies Non-technical
docs/TECHNICAL.md Developer deep-dive Developers
docs/TROUBLESHOOTING.md Decision-tree format with mermaid Everyone
docs/CHANGELOG.md Human-language changelog Everyone

Workflow

Step 1: Understand the Project

Before generating docs, gather this information:

  • What does the project do? (plain english)
  • What problem does it solve?
  • Who is it for?
  • What are the main components/files?
  • What commands or actions can users take?
  • What are common issues?

If the user has an existing repo, read the source files to extract this automatically.

Step 2: Generate REPO_MANIFEST.yml

This is the key file — structured metadata any AI agent can parse instantly. Create at .github/REPO_MANIFEST.yml:

schema: mrrs/v0.1
name: project-name
description: One sentence a non-technical person would understand
category: tool | library | template | service | documentation
license: MIT

audience:
  primary: developers | non-technical | mixed
  skill_level: beginner | intermediate | advanced

overview:
  what: Plain english, 1-2 sentences
  why: What problem it solves
  who: Who it's for

architecture:
  type: script | cli | web-app | api | action | library | monorepo
  languages: []
  dependencies: []
  platform: []
  components:
    - name: Component Name
      file: path/to/file
      purpose: What it does
      entry_point: true
  data_flow: |
    User does X → System does Y → Result is Z

commands:
  - name: command-name
    description: What it does
    usage: how-to-run
    destructive: false
    backup: false

quickstart:
  install_time: estimate
  prerequisites: []
  steps:
    - Step in plain english

config:
  files: []
  environment_variables: []

related:
  - url: https://example.com
    label: Resource Name

status:
  maturity: alpha | beta | stable | deprecated
  last_updated: YYYY-MM-DD
  maintained: true

Step 3: Generate Three-Tier README

Structure every README with these tiers:

Tier 1 — Everyone (top of file)

  • Project name + one-line description
  • "What This Does" section in plain english
  • One mermaid diagram showing the high-level flow
  • No code, no jargon

Tier 2 — Users (middle)

  • Dual-path section with collapsible details:
    • 🟢 "I'm not technical" — clicks, settings, downloads
    • 🔵 "I'm a developer" — terminal commands
  • Both paths lead to the same outcome

Tier 3 — Developers + AI (bottom)

  • Architecture diagrams (mermaid)
  • Project structure tree
  • Command reference table
  • Data flow sequence diagram
  • Config details

Step 4: Generate CONCEPTS.md

Rules for this file:

  • No code blocks in the first half
  • Define every technical term on first use
  • Use analogies ("Think of it like...")
  • Include a glossary table at the bottom
  • Answer: What is it? Why does it exist? How does it help me?

Step 5: Generate Remaining Docs

ARCHITECTURE.md — Required diagrams (minimum):

  1. System overview (graph TD)
  2. Component map table
  3. Decision logic (flowchart)
  4. Data flow (sequenceDiagram)
  5. File structure tree

QUICKSTART.md — Two sections:

  • 🟢 Non-technical: numbered steps, plain english, no terminal
  • 🔵 Developer: install + verify + run commands
  • "What Just Happened" section explaining the commands

TROUBLESHOOTING.md — Format:

  • Start with a mermaid decision tree flowchart
  • Each issue gets: Symptoms → Cause → Fix
  • End with "Still Stuck?" linking to GitHub Issues

TECHNICAL.md — Sections:

  • Component reference with file paths
  • Config files table
  • Environment variables table
  • Error handling table
  • Security considerations

CHANGELOG.md — Format:

  • Each entry answers: What changed? Why? How does it affect me?
  • Sections: What's New, What's Fixed, What Changed, Breaking Changes

Applying to Existing Repos

When a user asks to apply MRRS to an existing repo:

  1. Read the existing source files and README
  2. Extract: purpose, components, commands, config, dependencies
  3. Generate REPO_MANIFEST.yml from extracted info
  4. Generate three-tier README (preserve existing content in Tier 3)
  5. Generate CONCEPTS.md with analogies for the project's domain
  6. Generate remaining docs
  7. Show the user the file tree and ask for review before committing

Mermaid Diagram Standards

Every MRRS repo includes at minimum:

  • Architecture overview: graph TD with styled nodes
  • Data flow: sequenceDiagram showing user → system → result
  • Decision tree: flowchart TD for troubleshooting

Style conventions:

  • Green (#4ecdc4) for positive/success states
  • Blue (#45b7d1) for system components
  • Orange (#ff9f43) for warnings/actions
  • Red (#ff6b6b) for problems/errors
  • White text on colored backgrounds

Quality Checklist

Before finalizing, verify:

  • REPO_MANIFEST.yml has all required sections filled
  • README has all three tiers
  • At least 3 mermaid diagrams across all docs
  • CONCEPTS.md has no code in first half + has glossary
  • TROUBLESHOOTING.md starts with decision tree
  • QUICKSTART.md has both 🟢 and 🔵 paths
  • No undefined jargon in Tier 1 or CONCEPTS.md
  • All {placeholders} are replaced with real content

Cross-Client Notes

  • File paths: Use $HOME or ~/ notation, not hardcoded paths
  • Shell commands: Stick to POSIX-compatible bash — avoid zsh-only syntax
  • Mermaid: All major Git platforms render mermaid natively (GitHub, GitLab, Bitbucket)
  • YAML: REPO_MANIFEST.yml follows standard YAML 1.2 spec — parseable by any language
  • No vendor dependencies: The standard uses only markdown, YAML, and mermaid — no proprietary formats