MDAssistant

A Copilot skill + agents + prompts package that helps you organize text into the correct GitHub Copilot customization files.

Problem

Copilot supports multiple MD file types (.instructions.md, .prompt.md, .agent.md, SKILL.md, copilot-instructions.md) — each with different purposes, frontmatter requirements, and locations. Choosing the wrong type wastes context window, causes silent failures, or makes your customizations invisible to the agent.

MDAssistant classifies your text, creates files with proper structure, and audits existing setups for issues.

Features

Command	What it does
/md-assistant	Full skill — classify, interview, bulk organize, or audit
/classify-text	Quick: paste text → get file type + proposed content
/organize-text	Quick: paste brain dump → get multiple properly-typed files
/audit-md-files	Quick: scan .github/ for issues and anti-patterns
@md-assistant	Interactive agent with guided workflows

All commands plan first — they show proposed changes and wait for your approval before creating files.

Installation

Copy the following into your target project:

.github/
├── skills/md-assistant/          # Core skill + references
│   ├── SKILL.md
│   └── references/
│       ├── decision-tree.md
│       ├── file-types.md
│       ├── anti-patterns.md
│       └── templates.md
├── agents/
│   ├── md-assistant.agent.md     # Interactive agent
│   └── md-auditor.agent.md       # Audit sub-agent
└── prompts/
    ├── classify-text.prompt.md   # Quick classification
    ├── audit-md-files.prompt.md  # Quick audit
    └── organize-text.prompt.md   # Quick bulk organize

Quick install (from repo root)

# From your target project directory:
cp -r <path-to-MDAssistant>/.github/skills/md-assistant .github/skills/
cp <path-to-MDAssistant>/.github/agents/md-assistant.agent.md .github/agents/
cp <path-to-MDAssistant>/.github/agents/md-auditor.agent.md .github/agents/
cp <path-to-MDAssistant>/.github/prompts/*.prompt.md .github/prompts/

Usage

Classify text

Type /classify-text in Copilot chat and paste your text:

"When working on Python files, always use type hints and follow PEP 8 naming conventions"

MDAssistant will identify this as File Instructions (applyTo: "**/*.py") and show a proposed .instructions.md file.

Organize a brain dump

Type /organize-text and paste a large block:

"Our project uses React + TypeScript. Always use functional components. When writing tests, use vitest with testing-library. Generate API clients from our OpenAPI spec. Act as a security reviewer when checking auth code."

MDAssistant splits this into:

• Workspace instructions: React + TypeScript, functional components
• File instructions: Testing conventions (applyTo: "**/*.test.ts")
• Prompt: Generate API clients from OpenAPI spec
• Agent: Security reviewer with read-only tools

Audit existing files

Type /audit-md-files to scan your project's .github/ directory. MDAssistant reports errors (missing frontmatter), warnings (vague descriptions), and suggestions (better organization).

Interactive mode

Select @md-assistant as your agent for a guided conversation. It will interview you about scope, triggers, and requirements, then recommend the right file types.

Requirements

• VS Code with GitHub Copilot extension
• Copilot Chat enabled

File Types Covered

Type	File	Purpose
Workspace Instructions	copilot-instructions.md / AGENTS.md	Project-wide standards
File Instructions	*.instructions.md	File-specific or task-specific rules
Prompts	*.prompt.md	Single reusable tasks
Custom Agents	*.agent.md	Specialized personas with tool restrictions
Skills	SKILL.md	Multi-step workflows with bundled assets

License

MIT