Skip to content

K-Dense-AI/scientific-agent-skills / skills/markdown-mermaid-writing

markdown-mermaid-writing

Unverified

Writes scientific Markdown documentation and Mermaid diagrams for workflows, relationships, timelines, and schemas. Provides syntax references, document templates, accessibility guidance, and version-aware rendering checks. Use when a user requests Markdown, Mermaid, or a text-based structural diagram; quantitative scientific figures require suitable plotting tools.

FileKindSize
SKILL.mdskill md16.3 KB
assets/examples/example-research-report.mdmarkdown3.4 KB
references/current-rendering.mdmarkdown7.6 KB
references/diagrams/architecture.mdmarkdown5.0 KB
references/diagrams/block.mdmarkdown5.0 KB
references/diagrams/c4.mdmarkdown6.7 KB
references/diagrams/class.mdmarkdown8.6 KB
references/diagrams/complex_examples.mdmarkdown16.8 KB
references/diagrams/er.mdmarkdown8.0 KB
references/diagrams/flowchart.mdmarkdown7.0 KB
references/diagrams/gantt.mdmarkdown6.0 KB
references/diagrams/git_graph.mdmarkdown2.2 KB
references/diagrams/kanban.mdmarkdown4.0 KB
references/diagrams/mindmap.mdmarkdown2.5 KB
references/diagrams/packet.mdmarkdown2.4 KB
references/diagrams/pie.mdmarkdown1.9 KB
references/diagrams/quadrant.mdmarkdown2.6 KB
references/diagrams/radar.mdmarkdown2.8 KB
references/diagrams/requirement.mdmarkdown3.0 KB
references/diagrams/sankey.mdmarkdown2.6 KB
references/diagrams/sequence.mdmarkdown5.9 KB
references/diagrams/state.mdmarkdown5.7 KB
references/diagrams/timeline.mdmarkdown4.5 KB
references/diagrams/treemap.mdmarkdown2.6 KB
references/diagrams/user_journey.mdmarkdown5.2 KB
references/diagrams/xy_chart.mdmarkdown2.6 KB
references/diagrams/zenuml.mdmarkdown2.5 KB
references/markdown_style_guide.mdmarkdown32.4 KB
references/mermaid_style_guide.mdmarkdown26.6 KB
templates/decision_record.mdmarkdown7.2 KB
templates/how_to_guide.mdmarkdown7.1 KB
templates/issue.mdmarkdown11.6 KB
templates/kanban.mdmarkdown10.6 KB
templates/presentation.mdmarkdown8.1 KB
templates/project_documentation.mdmarkdown11.5 KB
templates/pull_request.mdmarkdown11.8 KB
templates/research_paper.mdmarkdown10.1 KB
templates/status_report.mdmarkdown7.2 KB

templates/project_documentation.md

View on GitHub
<!-- Source: https://github.com/SuperiorByteWorks-LLC/agent-project | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->

# Project Documentation Template

> **Back to [Markdown Style Guide](../references/markdown_style_guide.md)** โ€” Read the style guide first for formatting, citation, and emoji rules.

**Use this template for:** Software projects, open-source libraries, internal tools, APIs, platforms, or any product that needs documentation for users and contributors. Designed to take someone from "what is this?" to "I'm contributing" in a single read.

**Key features:** Quick start that gets people running in under 5 minutes, architecture overview with Mermaid diagrams, API reference structure, troubleshooting section that addresses real problems, and contribution guidelines.

**Philosophy:** The best project docs eliminate the need to read the source code to understand the system. A new team member should be productive in hours, not weeks. Every "how does this work?" question should have an answer in this document or be one click away.

---

## How to Use

1. Copy this file as your project's main `README.md` or `docs/index.md`
2. Replace all `[bracketed placeholders]` with your content
3. Delete sections that don't apply (a CLI tool might skip API reference; a library might skip deployment)
4. Add [Mermaid diagrams](../references/mermaid_style_guide.md) โ€” especially for architecture, data flow, and request lifecycle
5. Keep the Quick Start brutally simple โ€” if setup takes more than 5 commands, simplify it

---

## The Template

Everything below the line is the template. Copy from here; commands, API routes,
versions, thresholds, and numerical values are illustrative placeholders. Verify them
against the actual project before publishing. Follow its existing tracker and PR conventions.

---

# [Project Name]

[One sentence: what this does and why someone would use it.]

[One sentence: the key differentiator or value proposition.]

[Add real CI and license badges only after verifying their destinations and status.]

---

## ๐Ÿ“‹ Table of contents

- [Quick start](#-quick-start)
- [Architecture](#-architecture)
- [Configuration](#-configuration)
- [API reference](#-api-reference)
- [Deployment](#-deployment)
- [Troubleshooting](#-troubleshooting)
- [Contributing](#-contributing)
- [References](#-references)

---

## ๐Ÿš€ Quick start

### Prerequisites

| Requirement        | Version     | Check command         |
| ------------------ | ----------- | --------------------- |
| [Runtime/Language] | โ‰ฅ [version] | `[command] --version` |
| [Database/Service] | โ‰ฅ [version] | `[command] --version` |
| [Tool]             | โ‰ฅ [version] | `[command] --version` |

### Install and run

```bash
# Clone the repository
git clone https://github.com/[org]/[repo].git
cd [repo]

# Install dependencies
[package-manager] install

# Configure environment
cp .env.example .env
# Edit .env with your values

# Start the application
[package-manager] run dev
```

**Verify it works:**

```bash
curl http://localhost:[port]/health
# Expected: {"status": "ok", "version": "[version]"}
```

> ๐Ÿ’ก **First-time setup issues?** See [Troubleshooting](#-troubleshooting) for common problems.

---

## ๐Ÿ—๏ธ Architecture

### System overview

[2โ€“3 sentences explaining the high-level architecture โ€” what the major components are and how they interact.]

```mermaid
flowchart TB
    accTitle: System Architecture Overview
    accDescr: High-level architecture showing client, API, services, and data layers with primary data flow paths

    client([๐Ÿ‘ค Client]) --> api[๐ŸŒ API Gateway]

    subgraph services ["โš™๏ธ Services"]
        svc_a[๐Ÿ“‹ Service A]
        svc_b[๐Ÿ“ฆ Service B]
        svc_c[๐Ÿ” Auth Service]
    end

    subgraph data ["๐Ÿ’พ Data"]
        db[(๐Ÿ’พ Primary DB)]
        cache[โšก Cache]
        queue[๐Ÿ“ฅ Message Queue]
    end

    api --> svc_c
    api --> svc_a
    api --> svc_b
    svc_a --> db
    svc_a --> cache
    svc_b --> queue
    svc_b --> db

    classDef svc fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
    classDef data fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d

    class svc_a,svc_b,svc_c svc
    class db,cache,queue data
```

### Key components

| Component     | Purpose        | Technology   |
| ------------- | -------------- | ------------ |
| [Component 1] | [What it does] | [Tech stack] |
| [Component 2] | [What it does] | [Tech stack] |
| [Component 3] | [What it does] | [Tech stack] |

### Data flow

[Describe the primary request lifecycle โ€” what happens when a user makes a typical request.]

```mermaid
sequenceDiagram
    accTitle: Primary Request Lifecycle
    accDescr: Sequence showing how a typical request flows through the API gateway, service layer, and data stores

    participant C as ๐Ÿ‘ค Client
    participant A as ๐ŸŒ API Gateway
    participant S as โš™๏ธ Service
    participant D as ๐Ÿ’พ Database

    C->>A: ๐Ÿ“ค Request
    A->>A: ๐Ÿ” Authenticate
    A->>S: โš™๏ธ Process
    S->>D: ๐Ÿ” Query
    D-->>S: ๐Ÿ“ฅ Results
    S-->>A: ๐Ÿ“ค Response
    A-->>C: โœ… 200 OK
```

<details>
<summary><strong>๐Ÿ“‹ Detailed Architecture Notes</strong></summary>

### Directory structure

```
[repo]/
โ”œโ”€โ”€ src/
โ”‚   โ”œโ”€โ”€ api/          # Route handlers and middleware
โ”‚   โ”œโ”€โ”€ services/     # Business logic
โ”‚   โ”œโ”€โ”€ models/       # Data models and schemas
โ”‚   โ”œโ”€โ”€ config/       # Configuration and environment
โ”‚   โ””โ”€โ”€ utils/        # Shared utilities
โ”œโ”€โ”€ tests/
โ”‚   โ”œโ”€โ”€ unit/
โ”‚   โ””โ”€โ”€ integration/
โ”œโ”€โ”€ docs/             # Additional documentation
โ””โ”€โ”€ scripts/          # Build, deploy, and maintenance scripts
```

### Design decisions

- **[Decision 1]:** [Why this approach was chosen over alternatives. Link to ADR if one exists.]
- **[Decision 2]:** [Why this approach was chosen.]

</details>

---

## โš™๏ธ Configuration

### Environment variables

| Variable       | Required | Default          | Description                                         |
| -------------- | -------- | ---------------- | --------------------------------------------------- |
| `DATABASE_URL` | Yes      | โ€”                | PostgreSQL connection string                        |
| `REDIS_URL`    | No       | `localhost:6379` | Redis cache connection                              |
| `LOG_LEVEL`    | No       | `info`           | Logging verbosity: `debug`, `info`, `warn`, `error` |
| `PORT`         | No       | `3000`           | HTTP server port                                    |
| `[VAR_NAME]`   | [Yes/No] | [default]        | [Description]                                       |

### Configuration files

| File                     | Purpose                                       |
| ------------------------ | --------------------------------------------- |
| `.env`                   | Local environment variables (never committed) |
| `config/default.json`    | Default settings for all environments         |
| `config/production.json` | Production overrides                          |

---

## ๐Ÿ“ก API Reference

### Authentication

Illustrative bearer-token example; replace with the actual service authentication contract:

```
Authorization: Bearer <token>
```

Placeholder only: replace `POST /auth/login`, expiry, scopes, and refresh behavior with verified service documentation. No live service is implied by these routes.

### Endpoints

#### `GET /api/[resource]`

**Description:** [What this endpoint returns]

**Parameters:**

| Parameter | Type    | Required | Description                         |
| --------- | ------- | -------- | ----------------------------------- |
| `limit`   | integer | No       | Max results (default: 20, max: 100) |
| `offset`  | integer | No       | Pagination offset                   |
| `[param]` | [type]  | [Yes/No] | [Description]                       |

**Response:**

```json
{
  "data": [
    {
      "id": "uuid",
      "name": "Example",
      "created_at": "2026-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "total": 42,
    "limit": 20,
    "offset": 0
  }
}
```

**Error responses:**

| Status | Meaning      | When                         |
| ------ | ------------ | ---------------------------- |
| `401`  | Unauthorized | Missing or invalid token     |
| `403`  | Forbidden    | Insufficient permissions     |
| `404`  | Not found    | Resource doesn't exist       |
| `429`  | Rate limited | Exceeded [N] requests/minute |

<details>
<summary><strong>๐Ÿ“ก Additional Endpoints</strong></summary>

#### `POST /api/[resource]`

[Request body, parameters, response format]

#### `PUT /api/[resource]/:id`

[Request body, parameters, response format]

#### `DELETE /api/[resource]/:id`

[Parameters, response format]

</details>

---

## ๐Ÿš€ Deployment

### Production deployment

```bash
# Build
[package-manager] run build

# Run database migrations
[package-manager] run migrate

# Start production server
[package-manager] run start
```

### Environment requirements

| Requirement | Production | Staging |
| ----------- | ---------- | ------- |
| CPU         | [spec]     | [spec]  |
| Memory      | [spec]     | [spec]  |
| Storage     | [spec]     | [spec]  |
| Database    | [spec]     | [spec]  |

### Health checks

| Endpoint            | Expected | Purpose                                  |
| ------------------- | -------- | ---------------------------------------- |
| `GET /health`       | `200 OK` | Basic liveness                           |
| `GET /health/ready` | `200 OK` | Full readiness (DB, cache, dependencies) |

<details>
<summary><strong>๐Ÿ”ง CI/CD Pipeline Details</strong></summary>

[Describe the deployment pipeline โ€” build steps, test stages, deployment targets, rollback procedures.]

</details>

---

## ๐Ÿ”ง Troubleshooting

### Common issues

#### "Connection refused" on startup

**Cause:** Database is not running or connection string is incorrect.

**Fix:**

1. Verify database is running: `[check-command]`
2. Check `DATABASE_URL` in `.env`
3. Test connection: `[test-command]`

#### "[Specific error message]"

**Cause:** [What triggers this error]

**Fix:**

1. [Step 1]
2. [Step 2]

#### Slow response times

**Cause:** [Common causes โ€” missing indexes, cache cold start, etc.]

**Fix:**

1. Check cache connectivity: `[command]`
2. Verify database indexes: `[command]`
3. Review recent changes to query patterns

### Getting help

- **Bug reports:** [Link to issue template or process]
- **Questions:** [Link to discussions, Slack channel, or forum]
- **Security issues:** [Email or private disclosure process]

---

## ๐Ÿค Contributing

### Development setup

```bash
# Fork and clone
git clone https://github.com/[your-fork]/[repo].git

# Install with dev dependencies
[package-manager] install --dev

# Run tests
[package-manager] test

# Run linter
[package-manager] run lint
```

### Workflow

1. Create a branch from `main`: `git checkout -b feature/your-feature`
2. Make changes following the code style (enforced by linter)
3. Write tests for new functionality
4. Run the full test suite: `[package-manager] test`
5. Open a pull request with a clear description

### Code standards

- [Language/framework style guide or linter config]
- [Test coverage expectations]
- [PR review process]
- [Documentation expectations for new features]

---

## ๐Ÿ”— References

- [Official framework docs](https://example.com) โ€” [What version and which sections are most relevant]
- [API specification](https://example.com) โ€” [OpenAPI/Swagger link if applicable]
- Architecture Decision Records (replace with the project link) โ€” [Why key decisions were made]

---

_Last updated: [Date] ยท Maintained by [Team/Owner]_
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall