skills/claude-scientific-skills
1
0
Fork 0
mirror of https://github.com/K-Dense-AI/claude-scientific-skills.git synced 2026-03-27 07:09:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(references): port style guides, 24 diagram guides, and 9 templates from opencode

Browse Source 
All content ported from borealBytes/opencode under Apache-2.0 license with
attribution headers prepended to each file.

- references/markdown_style_guide.md (~733 lines): full markdown formatting,
  citation, collapsible sections, emoji, Mermaid integration, and template
  selection guide
- references/mermaid_style_guide.md (~458 lines): full Mermaid standards —
  emoji set, classDef color palette, accessibility (accTitle/accDescr),
  theme neutrality (no %%{init}), and diagram type selection table
- references/diagrams/ (24 files): per-type exemplars, tips, and templates
  for all Mermaid diagram types
- templates/ (9 files): PR, issue, kanban, ADR, presentation, how-to,
  status report, research paper, project docs

Source: https://github.com/borealBytes/opencode
This commit is contained in:
borealBytes
2026-02-19 18:25:20 -05:00
parent b376b40f59
commit 02e19e3df9
35 changed files with 6687 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

275
scientific-skills/markdown-mermaid-writing/templates/how_to_guide.md Normal file
View File

@@ -0,0 +1,275 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# How-To / Tutorial Guide Template
> **Back to [Markdown Style Guide](../markdown_style_guide.md)** — Read the style guide first for formatting, citation, and emoji rules.
**Use this template for:** Step-by-step tutorials, how-to guides, onboarding walkthroughs, runbooks, setup instructions, or any document whose primary job is teaching someone to do something. Designed so the reader succeeds on the first attempt.
**Key features:** Prerequisites with verification commands, numbered steps with expected output at each stage, "verify it works" checkpoints, troubleshooting section for common failures, and "what's next" pathways.
**Philosophy:** A how-to guide fails if the reader gets stuck. Every step should be verifiable — the reader should be able to confirm they did it right before moving to the next one. Anticipate the exact moment they'll wonder "did that work?" and put a checkpoint there. Include the error messages they'll actually see, not just the happy path.
---
## How to Use
1. Copy this file to your project
2. Replace all `[bracketed placeholders]` with your content
3. **Test the guide yourself from scratch** — follow every step on a clean machine. If you skip this, the guide has bugs.
4. Add [Mermaid diagrams](../mermaid_style_guide.md) for process overviews, decision points, or architecture context
5. Include actual output (trimmed) at every verification step — don't just say "you should see output"
---
## The Template
Everything below the line is the template. Copy from here:
---
# [How to: Specific Task Description]
_[Estimated time: N minutes] · [Difficulty: Beginner / Intermediate / Advanced] · [Last verified: Date]_
---
## 📋 Overview
### What you'll accomplish
[One paragraph: what the reader will have built, configured, or achieved by the end of this guide. Be concrete.]
### What you'll learn
- [Skill or concept 1]
- [Skill or concept 2]
- [Skill or concept 3]
### Process overview
```mermaid
flowchart LR
accTitle: Tutorial Process Overview
accDescr: High-level steps from prerequisites through setup, configuration, and verification
prereqs([📋 Prerequisites]) --> setup[🔧 Setup]
setup --> configure[⚙️ Configure]
configure --> build[📦 Build]
build --> verify[✅ Verify]
classDef done fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
class verify done
```
---
## 📋 Prerequisites
Before starting, ensure you have:
| Requirement | Version | Verify with | Install link |
| ---------------- | ----------- | --------------------- | ------------------------------------ |
| [Tool/Runtime] | ≥ [version] | `[command] --version` | [Install guide](https://example.com) |
| [Dependency] | ≥ [version] | `[command] --version` | [Install guide](https://example.com) |
| [Account/Access] | — | [How to verify] | [Sign up](https://example.com) |
**Verify all prerequisites:**
```bash
# Run each command — all should succeed before proceeding
[command1] --version # Expected: [version] or higher
[command2] --version # Expected: [version] or higher
```
> ⚠️ **Don't skip this.** Step 3 will fail if [specific prerequisite] isn't installed correctly.
---
## 🔧 Steps
### Step 1: [Action verb — Set up / Create / Configure / Install]
[Brief context: why this step is necessary — one sentence.]
```bash
[command to run]
```
**Expected output:**
```
[What the terminal should show — include actual output, trimmed if long]
```
> 💡 **Tip:** [Helpful context about this step — common variation, what to do if on a different OS, etc.]
---
### Step 2: [Action verb]
[Brief context.]
```bash
[command to run]
```
**Expected output:**
```
[What you should see]
```
**If you see an error here**, check:
- [Most common cause and fix]
- [Second most common cause and fix]
---
### Step 3: [Action verb]
[Brief context.]
[If this step involves editing a file, show the exact content:]
```yaml
# config/[filename]
[key]: [value]
[key]: [value]
# [Comment explaining what this section does]
[key]:
[nested_key]: [value]
[nested_key]: [value]
```
> 📌 **Important:** [Critical detail about this configuration — what breaks if you get it wrong]
---
### Step 4: [Action verb]
[Brief context.]
```bash
[command to run]
```
**Expected output:**
```
[What you should see]
```
---
### Step 5: [Action verb — this should be the final action]
[Brief context.]
```bash
[final command]
```
---
## ✅ Verify it works
Run through these checks to confirm everything is working:
| Check | Command | Expected result |
| --------- | ----------- | ------------------------- |
| [Check 1] | `[command]` | [What success looks like] |
| [Check 2] | `[command]` | [What success looks like] |
| [Check 3] | `[command]` | [What success looks like] |
**All checks pass?** You're done. Jump to [What's next](#-whats-next).
**Something failed?** See [Troubleshooting](#-troubleshooting) below.
---
## 🔧 Troubleshooting
### "[Exact error message the reader will see]"
**Cause:** [What triggers this error — be specific]
**Fix:**
```bash
[exact commands to resolve]
```
**Verify the fix:**
```bash
[command to confirm the error is resolved]
```
---
### "[Another common error message]"
**Cause:** [What triggers this]
**Fix:**
1. [Step 1]
2. [Step 2]
3. Re-run the step that failed
---
### "[Third common issue — might not be an error message but a symptom]"
**Cause:** [What causes this behavior]
**Fix:**
[Solution with commands]
---
### Still stuck?
- **Search existing issues:** [docs/project/issues/](../../docs/project/issues/)
- **Ask for help:** [docs/project/kanban/](../../docs/project/kanban/)
- **File a bug:** [issue template](../../docs/project/issues/issue-00000001-agentic-documentation-system.md)
---
## 🚀 What's next
Now that you've completed this guide:
- **[Next tutorial]** — [What it covers and why you'd want to do it next](../workflow_guide.md)
- **[Reference docs]** — [Where to learn the full feature set](../markdown_style_guide.md)
- **[Advanced topic]** — [Deeper dive for when you're ready](../operational_readiness.md)
<details>
<summary><strong>📋 Quick reference card</strong></summary>
Key commands and values from this guide for future reference:
| Action | Command |
| -------------- | ----------- |
| [Start] | `[command]` |
| [Stop] | `[command]` |
| [Check status] | `[command]` |
| [View logs] | `[command]` |
| [Reset] | `[command]` |
</details>
---
## 🔗 References
- [Official documentation](https://example.com) — [Which section is most relevant]
- [Source repository](https://github.com/borealBytes) — [For bug reports and contributions]
---
_Last verified: [Date] on [OS/Platform version] · Maintained by [Team/Author]_