V0.3.2/markdown illustrator

[gimlichael]

This pull request introduces the new markdown-illustrator skill to the repository, providing a focused workflow for generating a Visual Brief and a diffusion-ready prompt from a markdown document. The README and documentation are updated to describe the new skill, its workflow, defaults, and usage scenarios, including detailed guidance for both users and agents.

Key changes:

New Skill Addition

• Added skills/markdown-illustrator/SKILL.md documenting the markdown-illustrator skill, including its purpose, output contract, workflow, visual strategy inference, and prompt compilation rules.

Documentation & Usage Updates

• Updated README.md to:
  • Add a hero image for visual context.
  • Include markdown-illustrator in the skills install command and the skills summary table. [1] [2] [3]
  • Add a comprehensive section explaining the motivation, workflow, inferred defaults, trigger examples, and common visual directions for markdown-illustrator.

[qodo-code-review]

Review Summary by Qodo

Add markdown-illustrator skill with visual brief and prompt compilation

✨ Enhancement 📝 Documentation

Walkthroughs

Description

• Introduces markdown-illustrator skill for visualization-first document processing
• Generates Visual Brief and compiled diffusion-ready prompts from markdown files
• Adds comprehensive documentation with workflow, defaults, and usage guidance
• Includes hero image branding and skill installation instructions

Diagram

flowchart LR
  A["Markdown Document"] -->|Read & Distill| B["Visual Brief"]
  B -->|Infer Strategy| C["Visual Strategy"]
  C -->|Compile| D["Final Prompt"]
  D -->|Return| E["Chat Response"]
  F["README Updates"] -->|Document| G["Skill Registry"]
  H["Hero Image"] -->|Brand| G

Loading

File Changes

1. README.md 📝 Documentation +94/-0

Document markdown-illustrator skill with comprehensive guidance

• Added hero image reference at the top for visual branding
• Included markdown-illustrator in the skills installation command list
• Added markdown-illustrator entry to the Available Skills table with description
• Added comprehensive "Why markdown-illustrator?" section explaining motivation, visual-first
 defaults, and inferred strategy
• Documented inferred defaults for intent, treatment, abstraction, labels, and aspect ratio
• Provided good trigger examples and common visual directions (whiteboard, blackboard, isometric,
 blueprint, editorial, cinematic, minimal poster)

README.md

---

2. skills/markdown-illustrator/SKILL.md 📝 Documentation +143/-0

Define markdown-illustrator skill specification and workflow

• Defined skill purpose: read markdown and return Visual Brief plus compiled prompt in chat
• Specified critical workflow constraints: narrow focus, no follow-up questions, no file creation,
 inferred strategy
• Documented output contract with Visual Brief structure and Final Prompt format
• Detailed markdown reading strategy focused on distilling meaning for visualization
• Provided Visual Brief writing guidelines for each field (subject, audience, narrative,
 opportunity, mood, must-show, avoid)
• Defined visual strategy inference dimensions: intent, treatment, abstraction, label density,
 aspect ratio
• Documented prompt compilation rules emphasizing composition, transformation, complexity control,
 anti-repetition, and text-safe prompting

skills/markdown-illustrator/SKILL.md

---

3. skills/markdown-illustrator/evals/evals.json 🧪 Tests +68/-0

Add evaluation scenarios for markdown-illustrator skill

• Created three evaluation scenarios testing core skill behaviors
• Eval 1: Microservices architecture document to hero-image prompt without menus
• Eval 2: Product launch document with explicit cinematic and Flux constraints
• Eval 3: Transformers explanation for onboarding with inferred digest/diagram strategy
• Defined 20+ expectations per eval covering chat response, Visual Brief structure, prompt quality,
 complexity control, anti-repetition, and no-branching behavior

skills/markdown-illustrator/evals/evals.json

---

View more (3)

4. skills/markdown-illustrator/evals/files/microservices-architecture.md 🧪 Tests +48/-0

Add microservices architecture evaluation document

• Created sample markdown document covering microservices architecture topics
• Includes sections on monolith-to-microservices spectrum, service mesh, observability, GPU
 inference, data pipelines, and cost optimization
• Provides realistic technical content for skill evaluation and testing

skills/markdown-illustrator/evals/files/microservices-architecture.md

---

5. skills/markdown-illustrator/evals/files/product-launch.md 🧪 Tests +43/-0

Add product launch evaluation document

• Created sample markdown document for product launch playbook
• Covers vision, target personas, go-to-market phases, scope boundaries, and risk mitigation
• Provides business-focused content for skill evaluation with explicit constraints

skills/markdown-illustrator/evals/files/product-launch.md

---

6. skills/markdown-illustrator/evals/files/transformers-explained.md 🧪 Tests +32/-0

Add transformers architecture evaluation document

• Created sample markdown document explaining transformer architectures
• Covers attention mechanisms, scaling laws, and inference optimization
• Provides technical educational content for skill evaluation and onboarding context testing

skills/markdown-illustrator/evals/files/transformers-explained.md

---

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 📐 Spec deviations (0)

1. Missing trigger phrases in description ☑ 📘 Rule violation ⚙ Maintainability

Description

The YAML frontmatter description for markdown-illustrator describes what it does and when to use
it, but it does not include at least two concrete trigger-phrase examples. This violates the
requirement that the description field itself include trigger phrases users might say.

Code

skills/markdown-illustrator/SKILL.md[R2-4]

+name: markdown-illustrator
+description: >
+  Turn a markdown document into a visualization-first chat response consisting of one Visual Brief and one high-quality diffuser prompt generated with best-effort reasoning. Use when the user references a .md file and wants a hero image, cover image, visual digest, keynote opener, illustration, or diffuser prompt. Default to zero follow-up questions, no file creation, and no style/theme/model menus; infer a compact visual strategy from the request and document, and only honor extra specificity when the user explicitly asks for a named model, aesthetic, or visual treatment such as whiteboard or blackboard.

Evidence

PR Compliance ID 111421 requires the description field to include what the skill does, when to use
it, and at least 2 concrete trigger phrases. The added frontmatter description at
skills/markdown-illustrator/SKILL.md[3-4] contains purpose and usage context but no example user
utterances/trigger phrases.

Rule 111421: Document skill descriptions with purpose, usage context, and trigger phrases
skills/markdown-illustrator/SKILL.md[1-5]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The `skills/markdown-illustrator/SKILL.md` YAML frontmatter `description` is missing at least two concrete trigger-phrase examples (user utterances), which are required to be present in the `description` field itself.
## Issue Context
Compliance requires the `description` field to include: (1) what it does, (2) when to use it, and (3) at least 2 example trigger phrases users might say.
## Fix Focus Areas
- skills/markdown-illustrator/SKILL.md[1-5]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Workflow lacks concrete commands ☑ 📘 Rule violation ⚙ Maintainability

Description

The Workflow section contains imperative steps but does not provide any concrete command/script
invocation or a reference to a documented procedure. This makes the instructions prose-only and may
violate the requirement for command-driven guidance.

Code

skills/markdown-illustrator/SKILL.md[R44-51]

+## Workflow
+
+1. Read the markdown file for meaning, not for headings.
+2. Distill the whole document into a Visual Brief optimized for visualization.
+3. Infer a compact visual strategy from the request and document without asking follow-up questions.
+4. Generate one best-effort final prompt from that summary and strategy.
+5. Return the result directly in chat.
+6. If the user explicitly asked for constraints such as `Flux`, `photorealistic`, `editorial illustration`, `16:9`, `avoid people`, `whiteboard`, or `blackboard`, honor them inside the final prompt without turning the interaction into a selection flow.

Evidence

PR Compliance ID 111422 requires imperative instructions to include specific commands/scripts (or an
explicit reference to a documented procedure). The added ## Workflow steps are purely descriptive
and include no command invocations or procedure references.

Rule 111422: Make SKILL.md instructions concrete and command-driven
skills/markdown-illustrator/SKILL.md[44-51]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The `## Workflow` section uses imperative prose steps without including concrete commands/scripts (or referencing a documented procedure), which may violate the command-driven instruction requirement.
## Issue Context
If this skill is invoked via a CLI or standardized agent command pattern, document at least one concrete invocation example (with clear placeholders) or reference an internal procedure by ID/URL.
## Fix Focus Areas
- skills/markdown-illustrator/SKILL.md[44-51]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Undocumented evals.json files field ☑ 🐞 Bug ⛯ Reliability

Description

skills/markdown-illustrator/evals/evals.json introduces a files property, but the repo’s
documented eval schema and validator only require id, prompt, and expected_output, so files
is not validated or standardized. This can make the evals non-portable across eval runners (some
will ignore it; strict ones may reject it), and it’s unclear how the markdown inputs are expected to
be provided during evaluation.

Code

skills/markdown-illustrator/evals/evals.json[8]

+      "files": ["evals/files/microservices-architecture.md"],

Evidence

The repo’s validator parses each skill’s evals/evals.json and only enforces presence of id,
prompt, and expected_output—it does not mention or validate any files property. The
contributing guide also documents an eval entry shape that omits files, indicating it’s not part
of the established contract. Additionally, a repo-wide search shows "files": [...] only appears in
this new skill’s evals, so there is no established precedent within this repo for runners/tools to
honor it consistently.

scripts/validate-skill-templates.ps1[256-287]
CONTRIBUTING.md[69-81]
skills/markdown-illustrator/evals/evals.json[5-12]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`skills/markdown-illustrator/evals/evals.json` uses a non-standard `files` field to reference markdown inputs, but this field is not part of the repo’s documented eval schema and is not validated by `scripts/validate-skill-templates.ps1`. This makes eval execution behavior ambiguous across runners.
## Issue Context
- The repo documents eval entries with `id`, `prompt`, and `expected_output`.
- The validator enforces only those required fields and does not validate/copy/interpret `files`.
- Only the new skill uses `files`, so portability is unclear.
## Fix options (pick one)
1) **Remove `files` from evals.json** and adjust prompts to be runnable without implicit file attachment (e.g., include the markdown content inline in the prompt or instruct the runner/user to paste content).
2) **Formally adopt `files`** by:
- updating documentation (CONTRIBUTING.md / AGENTS.md) to include the `files` field,
- updating `scripts/validate-skill-templates.ps1` to validate that listed paths exist under the skill directory,
- (if applicable in this repo) updating any eval runner tooling to copy/attach those files into the eval workspace.
## Fix Focus Areas
- skills/markdown-illustrator/evals/evals.json[1-68]
- scripts/validate-skill-templates.ps1[256-289]
- CONTRIBUTING.md[67-82]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

ⓘ The new review experience is currently in Beta. Learn more

[Copilot]

Pull request overview

This PR adds a new markdown-illustrator skill that turns a markdown document into a single visualization-oriented “Visual Brief” plus one diffusion-ready final prompt, and updates repo docs to surface and explain the new workflow.

Changes:

• Added skills/markdown-illustrator/SKILL.md defining the workflow, output contract, and prompt-compilation rules.
• Added skills/markdown-illustrator/evals/* with sample markdown inputs and evals.json to validate expected behavior.
• Updated README.md to document and promote the new skill, including a new repository hero image.

Reviewed changes

Copilot reviewed 7 out of 9 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
skills/markdown-illustrator/SKILL.md	Defines the new skill’s contract, workflow, and prompting rules.
skills/markdown-illustrator/evals/evals.json	Adds eval prompts/expectations for validating the skill.
skills/markdown-illustrator/evals/files/microservices-architecture.md	Eval input document for architecture/diagram-leaning scenarios.
skills/markdown-illustrator/evals/files/product-launch.md	Eval input document for cinematic/launch scenarios.
skills/markdown-illustrator/evals/files/transformers-explained.md	Eval input document for onboarding/ML explanatory scenarios.
README.md	Documents and advertises markdown-illustrator; adds hero image reference.
assets/hero.jpg	Adds a new hero image asset used by the README.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.