mirror of
https://github.com/K-Dense-AI/claude-scientific-skills.git
synced 2026-03-27 07:09:27 +08:00
chore: remove docs/project files from PR per review feedback
Per borealBytes review comment, removing the docs/project directory from this PR since only the skill content should be included. The docs/project content remains in my local fork for reference. Refs: PR #50
This commit is contained in:
Clayton Young
@@ -1,161 +0,0 @@
|
||||
# Issue-00000050: Add Markdown and Mermaid Writing Skill
|
||||
|
||||
| Field | Value |
|
||||
| ---------------------- | ------------------------------------------------------------------------------------------------- |
|
||||
| **Issue** | `#50` |
|
||||
| **Type** | ✨ Feature |
|
||||
| **Severity** | 🟡 Medium |
|
||||
| **Priority** | P1 |
|
||||
| **Reporter** | Clayton Young (borealBytes / Superior Byte Works, LLC) |
|
||||
| **Assignee** | Unassigned |
|
||||
| **Date reported** | 2026-02-19 |
|
||||
| **Status** | Open |
|
||||
| **Users affected** | All scientific skill users producing documentation, reports, or diagrams |
|
||||
| **Revenue impact** | Indirect — improves skill quality, adoption, and downstream reproducibility |
|
||||
| **Resolved in** | [PR-00000050](../pr/pr-00000050-markdown-mermaid-skill.md) |
|
||||
| **Time to resolution** | TBD |
|
||||
|
||||
---
|
||||
|
||||
## 📋 Summary
|
||||
|
||||
Create a new skill — `markdown-mermaid-writing` — that establishes **markdown with embedded Mermaid diagrams as the DEFAULT and canonical format** for scientific documentation output. The core principle: text-based diagrams are the source of truth. Python-generated or AI-generated images are downstream conversions, never the starting point.
|
||||
|
||||
### Customer impact
|
||||
|
||||
| Dimension | Assessment |
|
||||
| --------------------- | ------------------------------------------------------------------------- |
|
||||
| **Who's affected** | Researchers, scientists, data engineers using skills for documentation |
|
||||
| **How many** | All users producing reports, papers, analysis docs, or any diagrams |
|
||||
| **Business impact** | Reduces downstream rendering failures; improves reproducibility and AI-readability of outputs |
|
||||
| **Workaround exists** | Yes — users can continue using existing image generation methods |
|
||||
|
||||
---
|
||||
|
||||
## 💡 Motivation and origin
|
||||
|
||||
### The conversation that sparked this
|
||||
|
||||
This feature request emerged from a discussion in the K-Dense Discord on 2026-02-19 about balancing AGENTS.md vs skills and the importance of documentation standards for sharing and combining scientific skills[^1].
|
||||
|
||||
> "One note I might offer you all in the claude-scientific-skills that would make it even better is better directions for writing markdown. Specifically using mermaid diagrams extensively and using tables and those instead of python created diagrams when it makes sense. From my experience, the more you get your reports and files in .md in just regular text, which mermaid is as well as being a simple 'script language'. This just helps with any downstream rendering and especially AI generated images (using mermaid instead of just long form text to describe relationships < tokens). Additionally mermaid can render along with markdown for easy use almost anywhere by humans or AI."
|
||||
>
|
||||
> — Clayton Young (@borealBytes), K-Dense Discord, 2026-02-19
|
||||
|
||||
The K-Dense team responded positively and confirmed this direction aligns with their upcoming reorganization plans[^2].
|
||||
|
||||
### Why markdown + Mermaid as source
|
||||
|
||||
| Aspect | Mermaid in Markdown | Python / AI Images |
|
||||
| ----------------------------- | ------------------- | ------------------- |
|
||||
| **Version control** | ✅ Full git diff | ❌ Binary blob |
|
||||
| **Token efficiency** | ✅ Less than prose descriptions | ❌ Base64 or external refs |
|
||||
| **Human editable** | ✅ Any text editor | ❌ Requires regeneration |
|
||||
| **AI parseable** | ✅ Structured text, no vision model | ❌ Requires vision model |
|
||||
| **Platform support** | ✅ GitHub, GitLab, Notion, VS Code | ⚠️ Requires image hosting |
|
||||
| **Downstream flexibility** | ✅ Convert to images anytime | ❌ One-way |
|
||||
| **Accessibility** | ✅ accTitle / accDescr on every diagram | ❌ Alt-text often missing |
|
||||
|
||||
### Three-phase workflow
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
accTitle: Documentation Production Workflow
|
||||
accDescr: Mermaid in markdown is the required source phase. Python and AI-generated images are optional downstream phases for polished output only.
|
||||
|
||||
source["📄 Phase 1 — Mermaid in Markdown<br/>(ALWAYS — source of truth)"]
|
||||
python["🐍 Phase 2 — Python Generated<br/>(optional — when charts needed)"]
|
||||
ai["🎨 Phase 3 — AI Generated<br/>(optional — polished visuals)"]
|
||||
final["📊 Final Output"]
|
||||
|
||||
source --> python
|
||||
source --> ai
|
||||
python --> final
|
||||
ai --> final
|
||||
source --> final
|
||||
|
||||
classDef source fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
|
||||
classDef optional fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
|
||||
classDef output fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
|
||||
|
||||
class source source
|
||||
class python,ai optional
|
||||
class final output
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Acceptance criteria
|
||||
|
||||
### Must have
|
||||
|
||||
- [ ] New skill directory: `scientific-skills/markdown-mermaid-writing/`
|
||||
- [ ] `SKILL.md` with YAML frontmatter, philosophy section, workflow guide
|
||||
- [ ] Markdown style guide (`references/markdown_style_guide.md`) — full guide, ~730 lines
|
||||
- [ ] Mermaid style guide (`references/mermaid_style_guide.md`) — full guide, ~454 lines
|
||||
- [ ] All 24 diagram type guides (`references/diagrams/*.md`)
|
||||
- [ ] All 9 document templates (`templates/*.md`)
|
||||
- [ ] Example research report in `assets/examples/`
|
||||
- [ ] Issue and PR documents following the AGENTS.md "Everything is Code" convention
|
||||
|
||||
### Must not have
|
||||
|
||||
- [ ] Modification of any existing skills
|
||||
- [ ] Breaking changes to repo structure
|
||||
- [ ] Removal of Python/AI image generation options — those remain valid as downstream phases
|
||||
|
||||
### Integration points
|
||||
|
||||
- `scientific-schematics` — use after mermaid source to generate AI-polished images
|
||||
- `scientific-writing` — use this skill for all document structure and diagrams within manuscripts
|
||||
- `literature-review` — use this skill for formatting findings and relationship diagrams
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Technical details
|
||||
|
||||
### Content sources
|
||||
|
||||
All style guides and templates ported from the `SuperiorByteWorks-LLC/agent-project` repository under Apache-2.0 license with attribution retained[^3].
|
||||
|
||||
| Source path | Destination |
|
||||
| ------------------------------------------- | ---------------------------------------------------- |
|
||||
| `agentic/markdown_style_guide.md` | `references/markdown_style_guide.md` |
|
||||
| `agentic/mermaid_style_guide.md` | `references/mermaid_style_guide.md` |
|
||||
| `agentic/mermaid_diagrams/*.md` (24 files) | `references/diagrams/*.md` |
|
||||
| `agentic/markdown_templates/*.md` (9 files) | `templates/*.md` |
|
||||
|
||||
### Skill directory structure
|
||||
|
||||
```text
|
||||
scientific-skills/markdown-mermaid-writing/
|
||||
├── SKILL.md
|
||||
├── references/
|
||||
│ ├── markdown_style_guide.md
|
||||
│ ├── mermaid_style_guide.md
|
||||
│ └── diagrams/ ← 24 diagram type guides
|
||||
│ ├── flowchart.md
|
||||
│ ├── sequence.md
|
||||
│ └── [22 more]
|
||||
├── templates/ ← 9 document templates
|
||||
│ ├── pull_request.md
|
||||
│ ├── issue.md
|
||||
│ └── [7 more]
|
||||
└── assets/
|
||||
└── examples/
|
||||
└── example-research-report.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 References
|
||||
|
||||
[^1]: K-Dense Discord thread, 2026-02-19. Discussion between Clayton Young (@borealBytes), Orion Li (K-Dense), and Timothy about AGENTS.md standards and scientific documentation.
|
||||
|
||||
[^2]: Orion Li (K-Dense), responding: "Thanks for letting us know! We'll make sure to include this into our sauce when we implement our upcoming reorganization of the skills." — K-Dense Discord, 2026-02-19.
|
||||
|
||||
[^3]: Boreal Bytes / Superior Byte Works, LLC. `opencode` repository. https://github.com/SuperiorByteWorks-LLC/agent-project. Apache-2.0 License.
|
||||
|
||||
---
|
||||
|
||||
_Last updated: 2026-02-19_
|
||||
@@ -1,115 +0,0 @@
|
||||
# Kanban: feat-00000050 — Markdown and Mermaid Writing Skill
|
||||
|
||||
_Feature board tracking PR #50 — `feat/markdown-mermaid-writing-skill` → `main`_
|
||||
|
||||
---
|
||||
|
||||
## 📋 Board overview
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
kanban:
|
||||
ticketBaseUrl: "https://github.com/K-Dense-AI/claude-scientific-skills/issues/"
|
||||
---
|
||||
kanban
|
||||
accTitle: PR 50 Markdown Mermaid Writing Skill Board
|
||||
accDescr: Kanban board tracking all tasks for the markdown-mermaid-writing skill PR from backlog through done.
|
||||
|
||||
column0[Done]
|
||||
task0@{ ticket: "50", title: "Create issue-00000050 feature request doc" }
|
||||
task1@{ ticket: "50", title: "Create PR-00000050 record doc" }
|
||||
task2@{ ticket: "50", title: "Create skill directory structure" }
|
||||
task3@{ ticket: "50", title: "Port markdown style guide (733 lines)" }
|
||||
task4@{ ticket: "50", title: "Port mermaid style guide (458 lines)" }
|
||||
task5@{ ticket: "50", title: "Port all 24 diagram type guides" }
|
||||
task6@{ ticket: "50", title: "Port all 9 document templates" }
|
||||
task7@{ ticket: "50", title: "Create SKILL.md with source format philosophy" }
|
||||
task8@{ ticket: "50", title: "Add example research report" }
|
||||
task9@{ ticket: "50", title: "Fix attribution to SuperiorByteWorks-LLC/agent-project" }
|
||||
task10@{ ticket: "50", title: "Fix Mermaid \\n → <br/> in all node labels" }
|
||||
task11@{ ticket: "50", title: "Renumber docs to #50 (upstream next number)" }
|
||||
task12@{ ticket: "50", title: "Create kanban board" }
|
||||
|
||||
column1[In Review]
|
||||
task13@{ ticket: "50", title: "Push branch and open PR to K-Dense-AI/claude-scientific-skills" }
|
||||
|
||||
column2[Backlog]
|
||||
task14@{ ticket: "50", title: "Human review and approval" }
|
||||
task15@{ ticket: "50", title: "Merge to main" }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Scope
|
||||
|
||||
| Field | Value |
|
||||
| -------------- | -------------------------------------------------------------------- |
|
||||
| **PR** | [#50](../pr/pr-00000050-markdown-mermaid-skill.md) |
|
||||
| **Issue** | [#50](../issues/issue-00000050-markdown-mermaid-skill.md) |
|
||||
| **Branch** | `feat/markdown-mermaid-writing-skill` |
|
||||
| **Target repo** | `K-Dense-AI/claude-scientific-skills` |
|
||||
| **Fork** | `borealBytes/claude-scientific-skills` |
|
||||
| **Started** | 2026-02-19 |
|
||||
| **Status** | 🟡 In Review — PR #50 open, awaiting K-Dense team review |
|
||||
|
||||
---
|
||||
|
||||
## ✅ Completed tasks
|
||||
|
||||
| Task | Evidence |
|
||||
| -------------------------------------------------- | -------------------------------------------------- |
|
||||
| Issue-00000050 feature request doc | `docs/project/issues/issue-00000050-markdown-mermaid-skill.md` |
|
||||
| PR-00000050 record doc | `docs/project/pr/pr-00000050-markdown-mermaid-skill.md` |
|
||||
| Skill directory structure | `scientific-skills/markdown-mermaid-writing/` |
|
||||
| Markdown style guide (733 lines) | `references/markdown_style_guide.md` |
|
||||
| Mermaid style guide (458 lines) | `references/mermaid_style_guide.md` |
|
||||
| 24 diagram type guides | `references/diagrams/*.md` |
|
||||
| 9 document templates | `templates/*.md` |
|
||||
| SKILL.md with source format philosophy | `scientific-skills/markdown-mermaid-writing/SKILL.md` |
|
||||
| Example CRISPR research report | `assets/examples/example-research-report.md` |
|
||||
| Attribution corrected to SuperiorByteWorks-LLC | All 42 refs updated |
|
||||
| Mermaid `\n` → `<br/>` in node labels | 12 occurrences fixed across 4 files |
|
||||
| Docs renumbered to #50 | Matches upstream next available number |
|
||||
|
||||
---
|
||||
|
||||
## 🔄 In progress
|
||||
|
||||
_Nothing currently in progress._
|
||||
|
||||
---
|
||||
|
||||
## 📋 Backlog
|
||||
|
||||
| Task | Blocked by | Notes |
|
||||
| ----------------------- | ---------- | --------------------------------------------- |
|
||||
| Human review / approval | PR push | K-Dense team reviews and merges |
|
||||
| Merge to main | Approval | Standard merge process |
|
||||
|
||||
---
|
||||
|
||||
## 📊 Progress
|
||||
|
||||
```mermaid
|
||||
pie
|
||||
accTitle: PR 50 Task Completion
|
||||
accDescr: Pie chart showing 13 tasks done out of 15 total tasks for PR 50
|
||||
|
||||
"Done" : 13
|
||||
"In Review" : 1
|
||||
"Backlog" : 2
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔗 References
|
||||
|
||||
- [PR-00000050](../pr/pr-00000050-markdown-mermaid-skill.md)
|
||||
- [Issue-00000050](../issues/issue-00000050-markdown-mermaid-skill.md)
|
||||
- [Upstream PR](https://github.com/K-Dense-AI/claude-scientific-skills/pull/50) (once pushed)
|
||||
- [Skill source](https://github.com/SuperiorByteWorks-LLC/agent-project)
|
||||
|
||||
---
|
||||
|
||||
_Last updated: 2026-02-19_
|
||||
@@ -1,188 +0,0 @@
|
||||
# PR-00000050: feat(scientific-communication): add markdown-mermaid-writing skill
|
||||
|
||||
| Field | Value |
|
||||
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **PR** | `#50` (https://github.com/K-Dense-AI/claude-scientific-skills/pull/50) |
|
||||
| **Author** | Clayton Young (borealBytes / Superior Byte Works, LLC) — [LinkedIn](https://www.linkedin.com/in/claytoneyoung/) · [Clayton@SuperiorByteWorks.com](mailto:Clayton@SuperiorByteWorks.com) |
|
||||
| **Date** | 2026-02-19 |
|
||||
| **Status** | Open — Draft |
|
||||
| **Branch** | `feat/markdown-mermaid-writing-skill` → `main` |
|
||||
| **Related issues** | [#50](../issues/issue-00000050-markdown-mermaid-skill.md) |
|
||||
| **Kanban board** | [feat-00000050](../kanban/feat-00000050-markdown-mermaid-skill.md) |
|
||||
| **Deploy strategy** | Standard — documentation-only addition, no code execution changes |
|
||||
|
||||
---
|
||||
|
||||
## 📋 Summary
|
||||
|
||||
### What changed and why
|
||||
|
||||
This PR adds a new skill — `markdown-mermaid-writing` — that establishes markdown with embedded Mermaid diagrams as the **default and canonical documentation format** for all scientific skills. The skill ports comprehensive style guides, 24 diagram type references, and 9 document templates from the `SuperiorByteWorks-LLC/agent-project` project, and codifies the "source format" philosophy proposed in the K-Dense Discord on 2026-02-19.
|
||||
|
||||
The motivation: scientific outputs currently default to Python-generated or AI-generated images for diagrams. This PR inverts that priority — text-based Mermaid diagrams are the source of truth, downstream image generation is secondary. This gives users version-controlled, token-efficient, universally renderable documentation by default.
|
||||
|
||||
### Impact classification
|
||||
|
||||
| Dimension | Level | Notes |
|
||||
| ----------------- | ------------------------------------------------------- | ------------------------------------- |
|
||||
| **Risk** | 🟢 Low | New skill only — no existing files modified |
|
||||
| **Scope** | Narrow | One new skill directory |
|
||||
| **Reversibility** | Easily reversible | Delete the directory to revert |
|
||||
| **Security** | None | Documentation only |
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Changes
|
||||
|
||||
### Change inventory
|
||||
|
||||
| File / Area | Change type | Description |
|
||||
| --------------------------------------------------- | ----------- | ---------------------------------------------------------------------- |
|
||||
| `docs/project/issues/issue-00000050-markdown-mermaid-skill.md` | Added | Feature request issue record |
|
||||
| `docs/project/pr/pr-00000050-markdown-mermaid-skill.md` | Added | This PR record |
|
||||
| `scientific-skills/markdown-mermaid-writing/SKILL.md` | Added | Main skill documentation with YAML frontmatter and philosophy |
|
||||
| `scientific-skills/markdown-mermaid-writing/references/markdown_style_guide.md` | Added | Full markdown style guide (~730 lines) ported from opencode |
|
||||
| `scientific-skills/markdown-mermaid-writing/references/mermaid_style_guide.md` | Added | Full mermaid style guide (~454 lines) ported from opencode |
|
||||
| `scientific-skills/markdown-mermaid-writing/references/diagrams/architecture.md` | Added | Diagram type guide |
|
||||
| `scientific-skills/markdown-mermaid-writing/references/diagrams/block.md` | Added | Diagram type guide |
|
||||
| `scientific-skills/markdown-mermaid-writing/references/diagrams/c4.md` | Added | Diagram type guide |
|
||||
| `scientific-skills/markdown-mermaid-writing/references/diagrams/class.md` | Added | Diagram type guide |
|
||||
| `scientific-skills/markdown-mermaid-writing/references/diagrams/complex_examples.md` | Added | Multi-diagram composition patterns |
|
||||
| `scientific-skills/markdown-mermaid-writing/references/diagrams/er.md` | Added | Diagram type guide |
|
||||
| `scientific-skills/markdown-mermaid-writing/references/diagrams/flowchart.md` | Added | Diagram type guide |
|
||||
| `scientific-skills/markdown-mermaid-writing/references/diagrams/gantt.md` | Added | Diagram type guide |
|
||||
| `scientific-skills/markdown-mermaid-writing/references/diagrams/git_graph.md` | Added | Diagram type guide |
|
||||
| `scientific-skills/markdown-mermaid-writing/references/diagrams/kanban.md` | Added | Diagram type guide |
|
||||
| `scientific-skills/markdown-mermaid-writing/references/diagrams/mindmap.md` | Added | Diagram type guide |
|
||||
| `scientific-skills/markdown-mermaid-writing/references/diagrams/packet.md` | Added | Diagram type guide |
|
||||
| `scientific-skills/markdown-mermaid-writing/references/diagrams/pie.md` | Added | Diagram type guide |
|
||||
| `scientific-skills/markdown-mermaid-writing/references/diagrams/quadrant.md` | Added | Diagram type guide |
|
||||
| `scientific-skills/markdown-mermaid-writing/references/diagrams/radar.md` | Added | Diagram type guide |
|
||||
| `scientific-skills/markdown-mermaid-writing/references/diagrams/requirement.md` | Added | Diagram type guide |
|
||||
| `scientific-skills/markdown-mermaid-writing/references/diagrams/sankey.md` | Added | Diagram type guide |
|
||||
| `scientific-skills/markdown-mermaid-writing/references/diagrams/sequence.md` | Added | Diagram type guide |
|
||||
| `scientific-skills/markdown-mermaid-writing/references/diagrams/state.md` | Added | Diagram type guide |
|
||||
| `scientific-skills/markdown-mermaid-writing/references/diagrams/timeline.md` | Added | Diagram type guide |
|
||||
| `scientific-skills/markdown-mermaid-writing/references/diagrams/treemap.md` | Added | Diagram type guide |
|
||||
| `scientific-skills/markdown-mermaid-writing/references/diagrams/user_journey.md` | Added | Diagram type guide |
|
||||
| `scientific-skills/markdown-mermaid-writing/references/diagrams/xy_chart.md` | Added | Diagram type guide |
|
||||
| `scientific-skills/markdown-mermaid-writing/references/diagrams/zenuml.md` | Added | Diagram type guide |
|
||||
| `scientific-skills/markdown-mermaid-writing/templates/decision_record.md` | Added | Document template |
|
||||
| `scientific-skills/markdown-mermaid-writing/templates/how_to_guide.md` | Added | Document template |
|
||||
| `scientific-skills/markdown-mermaid-writing/templates/issue.md` | Added | Document template |
|
||||
| `scientific-skills/markdown-mermaid-writing/templates/kanban.md` | Added | Document template |
|
||||
| `scientific-skills/markdown-mermaid-writing/templates/presentation.md` | Added | Document template |
|
||||
| `scientific-skills/markdown-mermaid-writing/templates/project_documentation.md` | Added | Document template |
|
||||
| `scientific-skills/markdown-mermaid-writing/templates/pull_request.md` | Added | Document template |
|
||||
| `scientific-skills/markdown-mermaid-writing/templates/research_paper.md` | Added | Document template |
|
||||
| `scientific-skills/markdown-mermaid-writing/templates/status_report.md` | Added | Document template |
|
||||
| `scientific-skills/markdown-mermaid-writing/assets/examples/example-research-report.md` | Added | Example demonstrating all diagram types and style rules |
|
||||
|
||||
### Architecture impact
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
accTitle: New Skill Position in Ecosystem
|
||||
accDescr: Shows markdown-mermaid-writing as the foundation layer that other skills build upon for documentation output
|
||||
|
||||
new["📄 markdown-mermaid-writing<br/>(this PR — new skill)"]
|
||||
writing["✍️ scientific-writing"]
|
||||
lit["📚 literature-review"]
|
||||
schematics["🎨 scientific-schematics"]
|
||||
reports["📋 clinical-reports"]
|
||||
|
||||
new -->|"provides style + templates"| writing
|
||||
new -->|"provides diagram standards"| lit
|
||||
new -->|"source format before AI polish"| schematics
|
||||
new -->|"provides document structure"| reports
|
||||
|
||||
classDef newskill fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
|
||||
classDef existing fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#1f2937
|
||||
|
||||
class new newskill
|
||||
class writing,lit,schematics,reports existing
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
### How to verify
|
||||
|
||||
```bash
|
||||
# Check directory structure
|
||||
tree scientific-skills/markdown-mermaid-writing/
|
||||
|
||||
# Check diagram type guide count (expect 24)
|
||||
ls scientific-skills/markdown-mermaid-writing/references/diagrams/ | wc -l
|
||||
|
||||
# Check template count (expect 9)
|
||||
ls scientific-skills/markdown-mermaid-writing/templates/ | wc -l
|
||||
|
||||
# Check style guide sizes
|
||||
wc -l scientific-skills/markdown-mermaid-writing/references/markdown_style_guide.md
|
||||
wc -l scientific-skills/markdown-mermaid-writing/references/mermaid_style_guide.md
|
||||
|
||||
# Verify SKILL.md has YAML frontmatter
|
||||
head -10 scientific-skills/markdown-mermaid-writing/SKILL.md
|
||||
```
|
||||
|
||||
### Test coverage
|
||||
|
||||
| Test type | Status | Notes |
|
||||
| ----------------- | ----------- | ---------------------------------- |
|
||||
| Unit tests | ⬜ N/A | Documentation skill — no code |
|
||||
| Manual testing | ✅ Verified | Directory structure and file content reviewed |
|
||||
| Format validation | ✅ Verified | Markdown style guide rules applied to all docs |
|
||||
|
||||
### Edge cases considered
|
||||
|
||||
- Attribution headers added to all ported files — license compliance
|
||||
- All Mermaid diagrams in new documents use `classDef`, not `%%{init}` — dark/light mode compatible
|
||||
- `accTitle` + `accDescr` on every diagram in new documents — accessibility
|
||||
|
||||
---
|
||||
|
||||
## 🔒 Security
|
||||
|
||||
### Security checklist
|
||||
|
||||
- [x] No secrets, credentials, API keys, or PII in the diff
|
||||
- [x] Authentication/authorization changes reviewed — N/A
|
||||
- [x] Input validation reviewed — N/A (documentation only)
|
||||
- [x] License and attribution retained — Apache-2.0, source credited
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Deployment
|
||||
|
||||
No deployment steps needed — documentation-only skill addition.
|
||||
|
||||
### Rollback
|
||||
|
||||
```bash
|
||||
git revert HEAD~[n] # or simply delete the skill directory
|
||||
rm -rf scientific-skills/markdown-mermaid-writing/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 Design decisions
|
||||
|
||||
- **"Source format" over generated images** — Mermaid diagrams are text, diffable, versionable, and renderable by any markdown viewer without a build step. AI/Python images are downstream artifacts. This PR establishes that hierarchy explicitly.
|
||||
- **Full port of opencode style guides** — Rather than a summary, the complete guides are included so agents using this skill have the full context without additional lookups. The token cost of loading this skill is offset by eliminating per-document style lookups.
|
||||
- **Apache-2.0 attribution preserved** — All ported content retains the original license header. MIT (claude-scientific-skills) is compatible with Apache-2.0 for downstream use.
|
||||
|
||||
No ADR created — this is a documentation addition with no architectural tradeoff.
|
||||
|
||||
---
|
||||
|
||||
## 🔗 References
|
||||
|
||||
- [Issue #50](../issues/issue-00000050-markdown-mermaid-skill.md) — Feature request
|
||||
- [opencode repository](https://github.com/SuperiorByteWorks-LLC/agent-project) — Source of ported style guides (Apache-2.0)
|
||||
- [K-Dense Discord thread](https://discord.com/channels/k-dense) — Originating conversation, 2026-02-19
|
||||
|
||||
---
|
||||
|
||||
_Last updated: 2026-02-19_
|
||||
Reference in New Issue
Block a user