Skip to content

feat: add c4-diagram skill #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dimdasci merged 3 commits into from
Jun 19, 2026
Merged

feat: add c4-diagram skill #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ac8279f
feat: add c4-diagram skill
dimdasci Jun 19, 2026
0ddc6b6
docs: reframe README as multi-skill solution architecture repo
dimdasci Jun 19, 2026
b472cce
fix: correct skills install syntax in README
dimdasci Jun 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,3 +12,4 @@ skills/convert/scripts/tests/explore_*.py
tmp/
skills/convert/scripts/__pycache__/
__pycache__/
skills/c4-diagram/scripts/node_modules/
224 changes: 90 additions & 134 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,191 +1,147 @@
# Distill knowledge from meetings, interviews, and screen-shares
# Solution Architecture Skills

An [Agent Skill](https://agentskills.io/) that turns recorded meetings into speaker-labelled markdown transcripts, optionally with screenshots and topic-by-topic documents.
A collection of [Agent Skills](https://agentskills.io/) that automate solution architecture tasks — from capturing knowledge in meetings to producing architecture diagrams.

Built for knowledge handovers, interviews, screen-share walkthroughs, and voice notes — anything where the value is in what was said, not in the audio.
Built for architects and engineering teams who want agents to apply domain methodology correctly, not just generate plausible output.

The point of the skill is to draw a clean line between **deterministic work** — audio normalisation, video → audio, chunking, VTT parsing, API calls, frame extraction — handled by the included scripts, and **language work** — picking the transcription path, naming speakers, judging what to repair or mark unclear, choosing which moments deserve a screenshot, and shaping the final document — done by the agent itself. Scripts move bytes; the agent decides meaning and structure.
## Skills

## Install

```bash
npx skills add dimdasci/distill-knowledge
```

This drops the skill into your agent's skills directory.

Manual install: clone this repo, copy `skills/distill-knowledge/` into your agent's skills folder.

The skill follows the [Agent Skills open standard](https://agentskills.io/) — originally developed by Anthropic, now an open spec adopted by Claude Code, Gemini CLI, Cursor, OpenCode, Goose, GitHub Copilot, OpenAI Codex, and many other agents. Any compliant agent will pick it up.

## Prerequisites

| Tool | Why |
|---|---|
| [`uv`](https://docs.astral.sh/uv/) | Runs the Python scripts (PEP 723, no venv to manage) |
| `ffmpeg`, `ffprobe` | Audio normalisation, video → audio extraction, screenshot frames |
| `OPENAI_API_KEY` | Transcription via `gpt-4o-transcribe` |
| Python ≥ 3.10 | `uv` installs the right interpreter automatically |

The skill checks all of these on first run.

### How to install the tools
| Skill | What it does | Status |
|---|---|---|
| [`distill-knowledge`](skills/distill-knowledge/) | Turns recorded meetings, interviews, and screen-shares into speaker-labeled transcripts and structured topic documents | Stable (v1.0) |
| [`c4-diagram`](skills/c4-diagram/) | Produces C4 architecture diagrams in Mermaid notation (flowchart + subgraphs, validated syntax) | Initial (v0.1) |

#### Install uv
## Install

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh # macOS, Linux
brew install uv # macOS, Homebrew
pipx install uv # any platform with pipx
```

Windows or alternatives: see <https://docs.astral.sh/uv/getting-started/installation/>.

#### Install ffmpeg
# Install all skills from this repo
npx skills add dimdasci/distill-knowledge --skill '*'

```bash
brew install ffmpeg # macOS
sudo apt install ffmpeg # Debian, Ubuntu
sudo dnf install ffmpeg # Fedora
choco install ffmpeg # Windows (Chocolatey)
# Install a specific skill
npx skills add dimdasci/distill-knowledge --skill distill-knowledge
npx skills add dimdasci/distill-knowledge --skill c4-diagram
```

`ffprobe` ships inside the same package.
Manual install: clone this repo, copy the desired `skills/<name>/` directory into your agent's skills folder.

#### Set the OpenAI API key
Skills follow the [Agent Skills open standard](https://agentskills.io/) — originally developed by Anthropic, now adopted by Claude Code, Gemini CLI, Cursor, OpenCode, Goose, GitHub Copilot, OpenAI Codex, and many other agents. Any compliant agent will pick them up.

The skill picks the key up automatically from either source — no extra wiring:
## Prerequisites

- **Shell environment** — `export OPENAI_API_KEY=sk-...` in your shell rc, or set it inline before invoking the agent.
- **Project `.env`** — create a `.env` file in the directory you run the agent from (or any parent), with `OPENAI_API_KEY=sk-...` on its own line. The skill walks up the directory tree to find it.
Each skill declares its own requirements. At a glance:

If both are set, the shell variable wins. Never commit `.env` — keep it gitignored.
| Skill | Needs |
|---|---|
| `distill-knowledge` | `uv`, `ffmpeg`, `ffprobe`, Python ≥3.10, `OPENAI_API_KEY` |
| `c4-diagram` | Node.js ≥18 (for Mermaid syntax validation) |

## How to use
See individual skill `SKILL.md` files for full setup details.

1. Drop the recording in `inbox/`. Audio or video. If you have a `.vtt` next to it, leave it there — the skill uses it as a speaker-aligned skeleton.
2. Ask the agent in plain English what you want.
3. Answer three intake questions: language, number of speakers, topic + any proper names or specialised terms.
4. The agent emits everything under `outbox/{slug}/`. It never writes outside that folder.
---

The skill always asks before transcribing. If you do not answer the intake questions, it will not call the API.
## Skill: distill-knowledge

## Examples
Converts audio/video recordings into knowledge artifacts. Draws a clean line between **deterministic work** (audio normalization, chunking, API calls, frame extraction) handled by scripts, and **language work** (transcription path selection, speaker naming, fidelity judgment, document shaping) done by the agent.

### Voice note → transcript only
### Quick example

> Process the voice memo I just dropped in inbox.

You get one file:

```
outbox/quick-thoughts-q3-20260420/
└── transcript.md
```

`transcript.md` has timestamped speaker turns. If there is one speaker, it is paragraphed by topic. The transcript is faithful to what was said — recoverable garble is repaired, silences are not filled.
### Capabilities

### Process handover → topic docs with screenshots
- VTT-aligned retranscription (speaker labels from VTT + clean text from API)
- Direct single-speaker transcription
- Multi-speaker diarization (8-min chunks, quality warning)
- Screenshot extraction from screen-share recordings
- Structured topic documents with inline screenshots

Anonymised prompt:
### How to use

> I have a recording of a process handover from Person A to Person B, in Spanish. The recording with screen-share and the VTT are in `inbox/`, prefixed `GMTYYYYMMDD-Recording`. I need documents that describe the processes as Person A presented them, but in English, split by topic with an index file. All tool explanations must be supported by clear screenshots with sequential numbering and explanatory titles. The VTT transcription is likely low quality and needs re-transcription.
1. Drop the recording in `inbox/`
2. Ask the agent what you want
3. Answer three intake questions: language, number of speakers, topic + proper names
4. Output appears under `outbox/{slug}/`

You get:

```
outbox/process-handover-20260420/
├── summary.md # index — one row per topic, links into topics/
├── transcript.md # full transcript, faithful to the source language
├── topics/
│ ├── 01-big-picture.md
│ ├── 02-receiving-tickets.md
│ ├── 03-priority-rules.md
│ ├── 04-triage-workflow.md
│ └── ...
└── screenshots/
├── 01.jpg
├── 02.jpg
└── ...
```
---

The shape above is what the agent chose for *this* prompt — it is not a template the skill enforces. The skill does not prescribe section names, file counts, or filenames. A different prompt yields a different structure: a single flat document, an FAQ, a checklist, a slide-by-slide narration, a Q&A pairing, or whatever else fits the goal. Discuss the target shape with the agent before or during processing — that is the part you have leverage over.
## Skill: c4-diagram

For the prompt above the agent landed on a `summary.md` index (who is who, the big picture, a table of topics), per-topic files in a *What it is → What you do → What you see → Things to watch out for → Source* rhythm, and screenshots numbered continuously across all topics.
Produces C4 software architecture diagrams rendered as Mermaid code. Applies Simon Brown's C4 methodology correctly — abstraction-first thinking, proper scoping, notation rules — and uses stable Mermaid syntax (flowchart + subgraphs, not the experimental C4* diagram types that break across versions).

## What a topic document looks like
### Quick example

The block below is a synthetic excerpt with placeholder screenshots. In real outputs the screenshots are frames extracted from the recording at the right timestamps. The layout below reflects one prompt's intent — yours can ask for something completely different.
> Create a system context diagram for our payment service.

```mermaid
---
title: Payment Service — System Context
---
flowchart TB
Merchant(["<b>Merchant</b><br/><i>[Person]</i><br/>Submits payment requests"])
PaySvc["<b>Payment Service</b><br/><i>[Software System]</i><br/>Processes card payments"]
Gateway["<b>Card Network Gateway</b><br/><i>[Software System, External]</i><br/>Routes to card networks"]:::external

Merchant -- "submits payments via" --> PaySvc
PaySvc -- "authorizes charges through" --> Gateway
...
```

### Capabilities

- All C4 diagram types: system context, container, component, deployment, dynamic, landscape
- Validated Mermaid syntax (mermaid.parse with loose security)
- Anti-pattern detection (banned C4* keywords, hub-and-spoke bus, mixed levels)
- Self-check against C4 notation rules
- Complete working templates for all diagram types

### How to use

> ### Step 5 — Triaging an incoming ticket
>
> #### What it is
>
> The triage queue is where every new customer message lands before it reaches an agent. The triager assigns priority, owner, and tags before the ticket leaves the queue.
>
> #### What you do
>
> 1. Open the help-desk → switch to the `Queue` view → filter by `status = New`.
> 2. Open the oldest unassigned ticket.
> 3. Read the customer message. Skim the customer's history in the right panel.
> 4. Set Priority (`Low / Normal / High / Urgent`) and at least one Tag — without a tag the SLA timer is hidden.
> 5. If the issue matches a known engineering bug, fill `Linked issue` so the ticket auto-routes to the right team.
> 6. Click `Assign` and pick the agent. Save.
>
> #### What you see
>
> ![Screenshot 12](docs/assets/example-screenshot-01.png)
> **Screenshot 12 — Ticket detail view, TKT-4821.** Header *"TKT-4821 — Cannot export report to CSV"*; status pills below: `Open · High · Billing team`. Form fields top to bottom: Subject (`Cannot export report to CSV`), Customer (`Lina Park — Borealis Studio`), Priority (`High`), Status (`Open`), Assignee (empty), Linked issue (empty), Tags (empty). Left sidebar: `Inbox | Queue | Customers | Reports | Settings`.
>
> ![Screenshot 13](docs/assets/example-screenshot-02.png)
> **Screenshot 13 — Triage queue view.** Header *"Triage queue — 24 unassigned"*, filter line *"status = New · sort by oldest"*. Table columns: ID, Subject, Customer, Priority, Status. Rows visible: TKT-4821 (Cannot export report to CSV, Borealis Studio, High, New), TKT-4822 (2FA email not arriving, Ceres Logistics, Urgent, New), TKT-4823 (Wrong totals on dashboard, Delta Atelier, Normal, New), TKT-4824 (Bulk import stuck at 30%, Echo Robotics, High, New), TKT-4825 (How do I invite a colleague?, Forge & Sons, Low, New), TKT-4826 (API key rotated unexpectedly, Helix Foods, Urgent, New).
>
> #### Things to watch out for
>
> - Tickets with no Tags are hidden from the SLA timer. Always set at least one tag before saving.
> - The "Internal note" toggle in the reply box defaults to OFF — double-check before pasting customer-facing text.
>
> #### Source
>
> Transcript: parts 34, 35, 36 (timestamps 46:30–52:30).
1. Tell the agent what system you want to diagram and who will read it
2. The agent identifies C4 abstractions, selects diagram type, confirms with you
3. Diagram produced, validated, and delivered as a Mermaid code block

---

## Repo layout
## Repo Layout

| Path | What it is |
|---|---|
| `skills/distill-knowledge/` | The skill itself — what `npx skills add` installs |
| `inbox/` | Drop recordings here |
| `outbox/` | Generated transcripts and topic docs |
| `tmp/` | Preprocessing intermediates (chunks, manifests). Safe to delete. |
| `eval/` | Trigger-evaluation harness — checks that the skill activates on the right prompts |
| `docs/assets/` | Placeholder images used in this README |
| `skills/distill-knowledge/` | Distill Knowledge skill — transcription and topic docs |
| `skills/c4-diagram/` | C4 Diagram skill — architecture diagrams in Mermaid |
| `inbox/` | Drop recordings here (distill-knowledge) |
| `outbox/` | Generated artifacts |
| `tmp/` | Processing intermediates (safe to delete) |
| `eval/` | Trigger-evaluation harness |
| `docs/assets/` | Images used in documentation |

The published GitHub repo is named `distill-knowledge` to match the skill (skills.sh convention). The local working dir may differ.
## Design Principles

## Two transcription paths
All skills in this repo share a philosophy:

| Input | Path | Notes |
|---|---|---|
| Recording with a good VTT | Render the VTT directly | Cheapest, most accurate. No API call. |
| Recording with a garbled VTT | VTT-aligned re-transcription | VTT gives speaker labels and turn timestamps; `gpt-4o-transcribe` gives clean text; the agent aligns. |
| Recording, no VTT, one speaker | Direct transcription | `gpt-4o-transcribe` on the prepared audio. |
| Recording, no VTT, many speakers | Diarise fallback | `gpt-4o-transcribe-diarize` in 8-minute chunks. Quality is unstable — the skill warns you. |

The skill picks the path at Gate 1 of the workflow and asks you to confirm before spending API budget.
1. **Methodology over syntax** — skills encode *how to think about the task* (C4 abstractions, transcription fidelity rules), not just tool syntax.
2. **Scripts for I/O, agents for judgment** — deterministic work (file processing, validation, API calls) lives in scripts; decisions about meaning and structure are the agent's job.
3. **Progressive disclosure** — SKILL.md stays compact; heavy references load on demand to respect context budgets.
4. **Validation loops** — every skill validates its output before delivering (syntax check, self-check checklists).
5. **Anti-pattern catalogs** — encode known mistakes so agents avoid them without trial and error.

## Development checks
## Development

```bash
make quality # format check + lint + syntax + tests
make quality # format check + lint + syntax + tests (distill-knowledge)
make format # apply formatter
make install-hooks # enable commit-time checks
```

CI runs the same quality checks in `.github/workflows/python-quality.yml`.
For c4-diagram validation:
```bash
cd skills/c4-diagram/scripts && npm install
node validate_mermaid.mjs --strict ../../assets/templates/context.mmd
```

## License

Expand Down
Loading
Loading