AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

markdown-mermaid-writing

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.

Original source
K-Dense-AI
License
MIT
Pinned revision
5f2bc0341354fd5590aef76a533ada1e1e5b4e62

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read k-dense-ai--markdown-mermaid-writing at revision 5f2bc0341354fd5590aef76a533ada1e1e5b4e62, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 38

templates/project_documentation.md

Project Documentation Template

Back to Markdown Style Guide — 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 — 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

Prerequisites

| Requirement | Version | Check command | | ------------------ | ----------- | --------------------- | | [Runtime/Language] | ≥ [version] | [command] --version | | [Database/Service] | ≥ [version] | [command] --version | | [Tool] | ≥ [version] | [command] --version |

Install and run

# 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:

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

💡 First-time setup issues? See Troubleshooting for common problems.


🏗️ Architecture

System overview

[2–3 sentences explaining the high-level architecture — what the major components are and how they interact.]

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.]

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

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.]

⚙️ 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:

{
  "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 |

POST /api/[resource]

[Request body, parameters, response format]

PUT /api/[resource]/:id

[Request body, parameters, response format]

DELETE /api/[resource]/:id

[Parameters, response format]


🚀 Deployment

Production deployment

# 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) |

[Describe the deployment pipeline — build steps, test stages, deployment targets, rollback procedures.]


🔧 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

# 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 — [What version and which sections are most relevant]
  • API specification — [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]