# levineam/qmd-skill architecture

> Architecture diagram of the GitHub repository levineam/qmd-skill, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/levineam/qmd-skill
- Repository: https://github.com/levineam/qmd-skill

## Overview

##### Project type + purpose (what you’re diagramming)
This repo is **not an application** in the traditional sense; it’s a **skill definition package** for **Codex/Clawd** that teaches the environment how to use **qmd (Quick Markdown Search)**.

Evidence:
- File tree contains only:
- `README.md` (usage/docs)
- `SKILL.md` (the actual skill definition)
- README explicitly: “Codex/Clawd skill definition for qmd … Import … reading `SKILL.md`”
- qmd itself is an **external tool** hosted elsewhere: https://github.com/tobi/qmd

So the “system” here is an **integration**:
- Codex/Clawd runtime (host)
- This repo’s skill definition (configuration/metadata)
- The external qmd executable
- The user’s local Markdown content being searched

- Codex/Clawd environment loads skill definition from this Git repo
- Skill is defined in `SKILL.md`
- Skill targets qmd, which is external

- The exact **command(s)** executed (e.g., `qmd ...`)
- Required **inputs** (query string, path, glob, flags, etc.)
- Expected **outputs** (stdout format, JSON vs text, exit codes)
- Any **assumptions** (qmd must be installed, OS compatibility)
- Any **file system access** patterns (search in workspace, user home, repo)
- Any **network access** (unlikely, but confirm)

##### User
- Provides prompt/query to Codex/Clawd (and/or chooses the skill)

##### Codex/Clawd Runtime
- Skill loader / registry (imports this repo)
- Orchestrator (selects skill, passes parameters)
- Execution sandbox / tool runner (executes local commands)

##### Skill Definition: `SKILL.md` (this repo)
- Treated as a configuration artifact that defines:
- tool name: qmd
- invocation template
- input schema (if present)
- output parsing hints (if present)

##### qmd CLI (external binary)
- Installed on the host machine or environment image
- Executes searches

##### Filesystem / Workspace
- Markdown documents searched by qmd
- Potentially “repo under analysis”, local notes, etc.

##### GitHub Repo Source
- Where Codex/Clawd fetches this skill definition from (this repository)
- Separately, qmd’s own upstream repo (tobi/qmd)

##### User → Codex/Clawd Runtime
- “Search request / query / instruction”

##### Codex/Clawd Runtime → Skill Definition (`SKILL.md`)
- “Load/parse skill metadata”
- “Resolve invocation template / parameters”

##### Codex/Clawd Runtime → qmd CLI
- “Execute command: qmd …”
- (Optionally annotate: subprocess execution)

##### qmd CLI ↔ Filesystem
- “Read markdown files”
- “Return matched lines/paths/snippets”

##### qmd CLI → Codex/Clawd Runtime
- “stdout/stderr + exit code”

##### Codex/Clawd Runtime → User
- “Formatted search results / citations / paths”

If `SKILL.md` defines any structured output expectations (e.g., JSON), reflect that between qmd and Codex/Clawd with explicit labels (“JSON results”, “plain text results”).

##### Architectural patterns / principles present (and how to reflect them)
This project is a clean example of:
- **Declarative integration**: behavior defined by `SKILL.md`, not code.
- **Adapter pattern**: the skill adapts Codex/Clawd’s tool interface to an external CLI.
- **Separation of concerns**:
- Skill definition = contract
- Execution/runtime = orchestration
- qmd = core search functionality

This explicitly by putting `SKILL.md` in its own “Skill Package” boundary and showing that it does not execute; it only informs the runtime how to execute qmd.

##### Clear labels for each component
Use explicit names:
- “Codex/Clawd Runtime”
- “Skill Definition (`SKILL.md`)”
- “qmd CLI (installed binary)”
- “Local Markdown Corpus (workspace filesystem)”
- “Skill Source Repo (GitHub)”

- “git clone / fetch skill”
- “parse SKILL.md”
- “spawn process: qmd [args]”
- “read *.md files”
- “return matches (stdout)”
- “format results”

##### “As many components as possible” (practical decomposition here)
- Skill Source (Git repo)
- Skill Artifact (`SKILL.md`)
- Skill Loader
- Parameter Binder (maps user intent → qmd args)
- Tool Runner (executes qmd)
- Output Parser/Formatter
- qmd binary
- Filesystem corpus

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% System Context (C4 L1)
    %% =========================
    U["User"]:::actor

    subgraph "Codex/Clawd Host Environment"
        CR["Codex/Clawd Runtime"]:::runtime

        subgraph "Skill Package (this repo)"
            SDOC["Skill Definition (SKILL.md)"]:::artifact
            RDOC["Docs / Install Guide (README.md)"]:::docs
        end

        SL["Skill Loader / Registry"]:::component
        PB["Parameter Binder (intent -> qmd args)"]:::component
        TR["Tool Runner (subprocess executor)"]:::component
        RF["Result Parser / Formatter"]:::component
    end

    subgraph "External Dependencies"
        QMD["qmd CLI (external binary)"]:::external
        FS[("Local Markdown Corpus (Filesystem / Workspace)")]:::datastore
    end

    subgraph "Sources (Distribution)"
        GHS["Skill Source Repo (GitHub)"]:::source
        GHU["qmd Upstream Repo (tobi/qmd)"]:::source
    end

    %% Context flows
    U -->|"search_request(query,scope,options)"| CR
    CR -->|"formatted_results(paths,snippets)"| U

    %% Skill sourcing / loading
    GHS -->|"fetch_or_import_skill_repo"| SL
    SL -->|"read_and_parse"| SDOC
    SL -->|"reference_for_usage"| RDOC
    SL -->|"register_tool_definition"| CR

    %% Orchestration inside runtime
    CR -->|"select_skill(qmd)"| SL
    CR -->|"bind_inputs"| PB
    PB -->|"build_command: qmd [args]"| TR

    %% Subprocess boundary
    TR -->|"spawn_process(qmd ...)"| QMD
    QMD -->|"read_markdown_files(*.md)"| FS
    FS -->|"file_contents/paths"| QMD
    QMD -->|"stdout/stderr + exit_code"| TR

    %% Output handling
    TR -->|"raw_output"| RF
    RF -->|"structured_results(text_or_json)"| CR

    %% External tool provenance (informational dependency)
    GHU -.->|"provides_qmd_project"| QMD

    %% =========================
    %% Click Events (mapped files)
    %% =========================
    click SDOC "https://github.com/levineam/qmd-skill/blob/main/SKILL.md"
    click RDOC "https://github.com/levineam/qmd-skill/blob/main/README.md"

    %% =========================
    %% Styling (color is critical)
    %% =========================
    classDef actor fill:#FFE08A,stroke:#8A6D00,color:#1b1b1b,stroke-width:1px
    classDef runtime fill:#B9D7FF,stroke:#1C4E80,color:#0b1a2b,stroke-width:1.5px
    classDef component fill:#D7E9FF,stroke:#2B6CB0,color:#0b1a2b,stroke-width:1px
    classDef artifact fill:#BFEFC3,stroke:#1F7A3A,color:#0b2a12,stroke-width:1.5px
    classDef docs fill:#D8F5D9,stroke:#2E8B57,color:#0b2a12,stroke-width:1px
    classDef external fill:#E6E6E6,stroke:#666666,color:#1b1b1b,stroke-width:1.2px
    classDef datastore fill:#F2F2F2,stroke:#666666,color:#1b1b1b,stroke-width:1.5px
    classDef source fill:#E9D5FF,stroke:#6B46C1,color:#1f123a,stroke-width:1.2px
```
