How levineam/qmd-skill works
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