---
name: scale-benchmarks
description: Reference document for monopoly scale-benchmarks.
source: community
risk: safe
reports-to: monopoly
---

# MONOPOLY — Scale Benchmarks & Estimation Formulas

## When to Use
- Use this skill when the task matches this description: Reference document for monopoly scale-benchmarks.

## Quick Estimation Formulas

### User → RPS Conversion
```
Requests per second (avg) = DAU × avg_requests_per_user_per_day / 86400
Requests per second (peak) = avg_RPS × peak_multiplier

Peak multipliers by app type:
  Social media:      5–10×
  E-commerce:        3–5× (higher during sales)
  News / media:      10–20× (breaking news spike)
  B2B SaaS:          2–3× (business hours spike)
  Gaming:            5–15× (event-driven)
```

### Storage Estimation
```
Storage per day    = requests_per_day × avg_payload_size
Storage per year   = storage_per_day × 365
With replication   = storage_per_year × replication_factor (3× typical)
With CDN/cache     = reduce by cache_hit_ratio (80% hit = 20% origin load)

Common payload sizes:
  Tweet / short text:    500B
  Social post with text: 2KB
  Profile data:          5KB
  Image (compressed):    200KB–2MB
  Video (per minute):    50MB (720p), 150MB (1080p)
  API JSON response:     1–20KB
```

### Bandwidth Estimation
```
Inbound bandwidth  = avg_request_size × RPS
Outbound bandwidth = avg_response_size × RPS

Convert: 1 Gbps = 125 MB/s
         10 Gbps = 1.25 GB/s
```

---

## Known Scale Limits of Common Technologies

### Databases

| Technology | Single Node Writes | Reads (with replicas) | Recommended Shard/Cluster Trigger |
|------------|-------------------|----------------------|----------------------------------|
| PostgreSQL | ~5K–20K writes/s | ~50K–200K reads/s | >5TB data or >20K writes/s |
| MySQL | ~10K–25K writes/s | ~60K–250K reads/s | >5TB or >25K writes/s |
| MongoDB | ~20K–50K writes/s | ~50K–100K reads/s | >100GB or >50K writes/s |
| Cassandra | ~200K–1M writes/s | ~200K–500K reads/s | Almost never needs explicit sharding |
| DynamoDB | Unlimited (managed) | Unlimited (managed) | Use provisioned capacity mode |
| Redis | ~500K–1M ops/s | Same | >50GB data or cluster needed |
| Elasticsearch | ~10K–50K docs/s | ~1K–10K queries/s | >100M documents per index |

### Queues / Streams

| Technology | Max Throughput | Max Consumers | Retention |
|------------|----------------|---------------|-----------|
| Kafka | 1M+ msgs/s per cluster | Unlimited consumer groups | Configurable (days–forever) |
| RabbitMQ | ~50K–100K msgs/s | Limited by connections | Until consumed |
| SQS Standard | Unlimited (AWS-managed) | Unlimited | 14 days |
| SQS FIFO | 3K msgs/s per queue | Per group | 14 days |
| Redis Pub/Sub | ~1M msgs/s | Limited by subscribers | None (fire-and-forget) |

### Caching

| Technology | Max Memory (single) | Max Throughput | Latency |
|------------|--------------------|--------------|----|
| Redis | ~1TB RAM | ~1M ops/s | <1ms |
| Memcached | ~64GB RAM | ~1M ops/s | <1ms |
| In-process (Caffeine/Guava) | JVM heap | Unlimited (local) | <0.1ms |

---

## Capacity Planning by User Scale

### 1K DAU
```
Avg RPS:       ~1–5 RPS
Peak RPS:      ~10–50 RPS
DB size/year:  ~10–50GB
Infra needed:  Single server, managed DB (RDS t3.medium), basic CDN
Monthly cost:  $50–200
```

### 10K DAU
```
Avg RPS:       ~10–50 RPS
Peak RPS:      ~100–500 RPS
DB size/year:  ~100–500GB
Infra needed:  2–4 app servers, RDS r5.large, Redis t3.medium, CDN
Monthly cost:  $300–800
```

### 100K DAU
```
Avg RPS:       ~100–500 RPS
Peak RPS:      ~1K–5K RPS
DB size/year:  ~1–5TB
Infra needed:  ASG (5–10 app servers), RDS r5.xlarge + 2 replicas, Redis cluster, CDN, ALB
Monthly cost:  $2K–8K
```

### 1M DAU
```
Avg RPS:       ~1K–5K RPS
Peak RPS:      ~10K–50K RPS
DB size/year:  ~10–50TB
Infra needed:  ASG (20–50 servers), DB sharding or Aurora, Redis cluster, Kafka, CDN, WAF
Monthly cost:  $20K–80K
```

### 10M DAU
```
Avg RPS:       ~10K–50K RPS
Peak RPS:      ~100K–500K RPS
DB size/year:  ~100–500TB
Infra needed:  Multi-region, microservices, distributed DB (Cassandra/CockroachDB), full CDN, dedicated SRE
Monthly cost:  $200K–2M+
```

---

## Common SLO Targets

| Tier | Availability | Monthly Downtime Allowed |
|------|-------------|--------------------------|
| 99% | Basic | 7.2 hours/month |
| 99.9% (three nines) | Standard production | 43.8 minutes/month |
| 99.95% | Important services | 21.9 minutes/month |
| 99.99% (four nines) | Critical services | 4.38 minutes/month |
| 99.999% (five nines) | Telecom / payments | 26 seconds/month |

**Achieving four nines requires:** Multi-AZ deployment, automated failover, zero-downtime deploys, chaos engineering, 24/7 on-call.

---

## Latency Budget Guidelines

```
User perceived latency targets:
  < 100ms  → Feels instant
  100–300ms → Acceptable for most interactions
  300ms–1s → Noticeable; optimize if possible
  > 1s     → Frustrating; unacceptable for critical paths

Network latency by distance (approximate):
  Same datacenter:    0.5ms
  Same region (AZ):   1–2ms
  Cross-region US:    30–60ms
  US to Europe:       80–120ms
  US to Asia:         150–250ms

Database query targets:
  Simple key-value:   < 1ms (cache)
  Simple DB query:    < 5ms
  Complex query:      < 50ms
  Reporting query:    < 500ms (async if > 1s)
```

## Limitations
- This is a reference document and may not cover all edge cases. Always verify architectures before production.


---
name: scanning-tools
description: "Master essential security scanning tools for network discovery, vulnerability assessment, web application testing, wireless security, and compliance validation. This skill covers tool selection, configuration, and practical usage across different scanning categories."
risk: offensive
source: community
author: zebbern
date_added: "2026-02-27"
---

> **⚠ AUTHORIZED USE ONLY**
> This skill is for educational purposes or authorized security assessments only.
> You must have explicit, written permission from the system owner before using this tool.
> Misuse of this tool is illegal and strictly prohibited.

> **Mandatory confirmation gate**
> Before running any command that probes, exploits, changes, persists on, extracts data from, or attempts credential access against a target:
> 1. Ask the user to state the exact target URL, IP, account, or resource.
> 2. Ask the user to confirm written authorization and the permitted scope.
> 3. Show the exact command(s) and explain their expected effect.
> 4. Wait for explicit confirmation in the current conversation.
>
> Without that confirmation, remain read-only and provide defensive guidance only. Prefer a sandbox, disposable VM, or controlled lab.

# Security Scanning Tools

## Purpose

Master essential security scanning tools for network discovery, vulnerability assessment, web application testing, wireless security, and compliance validation. This skill covers tool selection, configuration, and practical usage across different scanning categories.

## Prerequisites

### Required Environment
- Linux-based system (Kali Linux recommended)
- Network access to target systems
- Proper authorization for scanning activities

### Required Knowledge
- Basic networking concepts (TCP/IP, ports, protocols)
- Understanding of common vulnerabilities
- Familiarity with command-line interfaces

## Outputs and Deliverables

1. **Network Discovery Reports** - Identified hosts, ports, and services
2. **Vulnerability Assessment Reports** - CVEs, misconfigurations, risk ratings
3. **Web Application Security Reports** - OWASP Top 10 findings
4. **Compliance Reports** - CIS benchmarks, PCI-DSS, HIPAA checks

## Core Workflow

### Phase 1: Network Scanning Tools

#### Nmap (Network Mapper)

Primary tool for network discovery and security auditing:

```bash
# Host discovery
nmap -sn 192.168.1.0/24              # Ping scan (no port scan)
nmap -sL 192.168.1.0/24              # List scan (DNS resolution)
nmap -Pn 192.168.1.100               # Skip host discovery

# Port scanning techniques
nmap -sS 192.168.1.100               # TCP SYN scan (stealth)
nmap -sT 192.168.1.100               # TCP connect scan
nmap -sU 192.168.1.100               # UDP scan
nmap -sA 192.168.1.100               # ACK scan (firewall detection)

# Port specification
nmap -p 80,443 192.168.1.100         # Specific ports
nmap -p- 192.168.1.100               # All 65535 ports
nmap -p 1-1000 192.168.1.100         # Port range
nmap --top-ports 100 192.168.1.100   # Top 100 common ports

# Service and OS detection
nmap -sV 192.168.1.100               # Service version detection
nmap -O 192.168.1.100                # OS detection
nmap -A 192.168.1.100                # Aggressive (OS, version, scripts)

# Timing and performance
nmap -T0 192.168.1.100               # Paranoid (slowest, IDS evasion)
nmap -T4 192.168.1.100               # Aggressive (faster)
nmap -T5 192.168.1.100               # Insane (fastest)

# NSE Scripts
nmap --script=vuln 192.168.1.100     # Vulnerability scripts
nmap --script=http-enum 192.168.1.100  # Web enumeration
nmap --script=smb-vuln* 192.168.1.100  # SMB vulnerabilities
nmap --script=default 192.168.1.100  # Default script set

# Output formats
nmap -oN scan.txt 192.168.1.100      # Normal output
nmap -oX scan.xml 192.168.1.100      # XML output
nmap -oG scan.gnmap 192.168.1.100    # Grepable output
nmap -oA scan 192.168.1.100          # All formats
```

#### Masscan

High-speed port scanning for large networks:

```bash
# Basic scanning
masscan -p80 192.168.1.0/24 --rate=1000
masscan -p80,443,8080 192.168.1.0/24 --rate=10000

# Full port range
masscan -p0-65535 192.168.1.0/24 --rate=5000

# Large-scale scanning
masscan 0.0.0.0/0 -p443 --rate=100000 --excludefile exclude.txt

# Output formats
masscan -p80 192.168.1.0/24 -oG results.gnmap
masscan -p80 192.168.1.0/24 -oJ results.json
masscan -p80 192.168.1.0/24 -oX results.xml

# Banner grabbing
masscan -p80 192.168.1.0/24 --banners
```

### Phase 2: Vulnerability Scanning Tools

#### Nessus

Enterprise-grade vulnerability assessment:

```bash
# Start Nessus service
sudo systemctl start nessusd

# Access web interface
# https://localhost:8834

# Command-line (nessuscli)
nessuscli scan --create --name "Internal Scan" --targets 192.168.1.0/24
nessuscli scan --list
nessuscli scan --launch <scan_id>
nessuscli report --format pdf --output report.pdf <scan_id>
```

Key Nessus features:
- Comprehensive CVE detection
- Compliance checks (PCI-DSS, HIPAA, CIS)
- Custom scan templates
- Credentialed scanning for deeper analysis
- Regular plugin updates

#### OpenVAS (Greenbone)

Open-source vulnerability scanning:

```bash
# Install OpenVAS
sudo apt install openvas
sudo gvm-setup

# Start services
sudo gvm-start

# Access web interface (Greenbone Security Assistant)
# https://localhost:9392

# Command-line operations
gvm-cli socket --xml "<get_version/>"
gvm-cli socket --xml "<get_tasks/>"

# Create and run scan
gvm-cli socket --xml '
<create_target>
  <name>Test Target</name>
  <hosts>192.168.1.0/24</hosts>
</create_target>'
```

### Phase 3: Web Application Scanning Tools

#### Burp Suite

Comprehensive web application testing:

```
# Proxy configuration
1. Set browser proxy to 127.0.0.1:8080
2. Import Burp CA certificate for HTTPS
3. Add target to scope

# Key modules:
- Proxy: Intercept and modify requests
- Spider: Crawl web applications
- Scanner: Automated vulnerability detection
- Intruder: Automated attacks (fuzzing, brute-force)
- Repeater: Manual request manipulation
- Decoder: Encode/decode data
- Comparer: Compare responses
```

Core testing workflow:
1. Configure proxy and scope
2. Spider the application
3. Analyze sitemap
4. Run active scanner
5. Manual testing with Repeater/Intruder
6. Review findings and generate report

#### OWASP ZAP

Open-source web application scanner:

```bash
# Start ZAP
zaproxy

# Automated scan from CLI
zap-cli quick-scan https://target.com

# Full scan
zap-cli spider https://target.com
zap-cli active-scan https://target.com

# Generate report
zap-cli report -o report.html -f html

# API mode
zap.sh -daemon -port 8080 -config api.key=<your_key>
```

ZAP automation:
```bash
# Docker-based scanning
docker run -t owasp/zap2docker-stable zap-full-scan.py \
  -t https://target.com -r report.html

# Baseline scan (passive only)
docker run -t owasp/zap2docker-stable zap-baseline.py \
  -t https://target.com -r report.html
```

#### Nikto

Web server vulnerability scanner:

```bash
# Basic scan
nikto -h https://target.com

# Scan specific port
nikto -h target.com -p 8080

# Scan with SSL
nikto -h target.com -ssl

# Multiple targets
nikto -h targets.txt

# Output formats
nikto -h target.com -o report.html -Format html
nikto -h target.com -o report.xml -Format xml
nikto -h target.com -o report.csv -Format csv

# Tuning options
nikto -h target.com -Tuning 123456789  # All tests
nikto -h target.com -Tuning x          # Exclude specific tests
```

### Phase 4: Wireless Scanning Tools

#### Aircrack-ng Suite

Wireless network penetration testing:

```bash
# Check wireless interface
airmon-ng

# Enable monitor mode
sudo airmon-ng start wlan0

# Scan for networks
sudo airodump-ng wlan0mon

# Capture specific network
sudo airodump-ng -c <channel> --bssid <target_bssid> -w capture wlan0mon

# Deauthentication attack
sudo aireplay-ng -0 10 -a <bssid> wlan0mon

# Crack WPA handshake
aircrack-ng -w wordlist.txt -b <bssid> capture*.cap

# Crack WEP
aircrack-ng -b <bssid> capture*.cap
```

#### Kismet

Passive wireless detection:

```bash
# Start Kismet
kismet

# Specify interface
kismet -c wlan0

# Access web interface
# http://localhost:2501

# Detect hidden networks
# Kismet passively collects all beacon frames
# including those from hidden SSIDs
```

### Phase 5: Malware and Exploit Scanning

#### ClamAV

Open-source antivirus scanning:

```bash
# Update virus definitions
sudo freshclam

# Scan directory
clamscan -r /path/to/scan

# Scan with verbose output
clamscan -r -v /path/to/scan

# Move infected files
clamscan -r --move=/quarantine /path/to/scan

# Remove infected files
clamscan -r --remove /path/to/scan

# Scan specific file types
clamscan -r --include='\.exe$|\.dll$' /path/to/scan

# Output to log
clamscan -r -l scan.log /path/to/scan
```

#### Metasploit Vulnerability Validation

Validate vulnerabilities with exploitation:

```bash
# Start Metasploit
msfconsole

# Database setup
msfdb init
db_status

# Import Nmap results
db_import /path/to/nmap_scan.xml

# Vulnerability scanning
use auxiliary/scanner/smb/smb_ms17_010
set RHOSTS 192.168.1.0/24
run

# Auto exploitation
vulns                           # View vulnerabilities
analyze                         # Suggest exploits
```

### Phase 6: Cloud Security Scanning

#### Prowler (AWS)

AWS security assessment:

```bash
# Install Prowler
pip install prowler

# Basic scan
prowler aws

# Specific checks
prowler aws -c iam s3 ec2

# Compliance framework
prowler aws --compliance cis_aws

# Output formats
prowler aws -M html json csv

# Specific region
prowler aws -f us-east-1

# Assume role
prowler aws -R arn:aws:iam::123456789012:role/ProwlerRole
```

#### ScoutSuite (Multi-cloud)

Multi-cloud security auditing:

```bash
# Install ScoutSuite
pip install scoutsuite

# AWS scan
scout aws

# Azure scan
scout azure --cli

# GCP scan
scout gcp --user-account

# Generate report
scout aws --report-dir ./reports
```

### Phase 7: Compliance Scanning

#### Lynis

Security auditing for Unix/Linux:

```bash
# Run audit
sudo lynis audit system

# Quick scan
sudo lynis audit system --quick

# Specific profile
sudo lynis audit system --profile server

# Output report
sudo lynis audit system --report-file /tmp/lynis-report.dat

# Check specific section
sudo lynis show profiles
sudo lynis audit system --tests-from-group malware
```

#### OpenSCAP

Security compliance scanning:

```bash
# List available profiles
oscap info /usr/share/xml/scap/ssg/content/ssg-<distro>-ds.xml

# Run scan with profile
oscap xccdf eval --profile xccdf_org.ssgproject.content_profile_pci-dss \
  --report report.html \
  /usr/share/xml/scap/ssg/content/ssg-rhel8-ds.xml

# Generate fix script
oscap xccdf generate fix \
  --profile xccdf_org.ssgproject.content_profile_pci-dss \
  --output remediation.sh \
  /usr/share/xml/scap/ssg/content/ssg-rhel8-ds.xml
```

### Phase 8: Scanning Methodology

Structured scanning approach:

1. **Planning**
   - Define scope and objectives
   - Obtain proper authorization
   - Select appropriate tools

2. **Discovery**
   - Host discovery (Nmap ping sweep)
   - Port scanning
   - Service enumeration

3. **Vulnerability Assessment**
   - Automated scanning (Nessus/OpenVAS)
   - Web application scanning (Burp/ZAP)
   - Manual verification

4. **Analysis**
   - Correlate findings
   - Eliminate false positives
   - Prioritize by severity

5. **Reporting**
   - Document findings
   - Provide remediation guidance
   - Executive summary

### Phase 9: Tool Selection Guide

Choose the right tool for each scenario:

| Scenario | Recommended Tools |
|----------|-------------------|
| Network Discovery | Nmap, Masscan |
| Vulnerability Assessment | Nessus, OpenVAS |
| Web App Testing | Burp Suite, ZAP, Nikto |
| Wireless Security | Aircrack-ng, Kismet |
| Malware Detection | ClamAV, YARA |
| Cloud Security | Prowler, ScoutSuite |
| Compliance | Lynis, OpenSCAP |
| Protocol Analysis | Wireshark, tcpdump |

### Phase 10: Reporting and Documentation

Generate professional reports:

```bash
# Nmap XML to HTML
xsltproc nmap-output.xml -o report.html

# OpenVAS report export
gvm-cli socket --xml '<get_reports report_id="<id>" format_id="<pdf_format>"/>'

# Combine multiple scan results
# Use tools like Faraday, Dradis, or custom scripts

# Executive summary template:
# 1. Scope and methodology
# 2. Key findings summary
# 3. Risk distribution chart
# 4. Critical vulnerabilities
# 5. Remediation recommendations
# 6. Detailed technical findings
```

## Quick Reference

### Nmap Cheat Sheet

| Scan Type | Command |
|-----------|---------|
| Ping Scan | `nmap -sn <target>` |
| Quick Scan | `nmap -T4 -F <target>` |
| Full Scan | `nmap -p- <target>` |
| Service Scan | `nmap -sV <target>` |
| OS Detection | `nmap -O <target>` |
| Aggressive | `nmap -A <target>` |
| Vuln Scripts | `nmap --script=vuln <target>` |
| Stealth Scan | `nmap -sS -T2 <target>` |

### Common Ports Reference

| Port | Service |
|------|---------|
| 21 | FTP |
| 22 | SSH |
| 23 | Telnet |
| 25 | SMTP |
| 53 | DNS |
| 80 | HTTP |
| 443 | HTTPS |
| 445 | SMB |
| 3306 | MySQL |
| 3389 | RDP |

## Constraints and Limitations

### Legal Considerations
- Always obtain written authorization
- Respect scope boundaries
- Follow responsible disclosure practices
- Comply with local laws and regulations

### Technical Limitations
- Some scans may trigger IDS/IPS alerts
- Heavy scanning can impact network performance
- False positives require manual verification
- Encrypted traffic may limit analysis

### Best Practices
- Start with non-intrusive scans
- Gradually increase scan intensity
- Document all scanning activities
- Validate findings before reporting

## Troubleshooting

### Scan Not Detecting Hosts

**Solutions:**
1. Try different discovery methods: `nmap -Pn` or `nmap -sn -PS/PA/PU`
2. Check firewall rules blocking ICMP
3. Use TCP SYN scan: `nmap -PS22,80,443`
4. Verify network connectivity

### Slow Scan Performance

**Solutions:**
1. Increase timing: `nmap -T4` or `-T5`
2. Reduce port range: `--top-ports 100`
3. Use Masscan for initial discovery
4. Disable DNS resolution: `-n`

### Web Scanner Missing Vulnerabilities

**Solutions:**
1. Authenticate to access protected areas
2. Increase crawl depth
3. Add custom injection points
4. Use multiple tools for coverage
5. Perform manual testing

## When to Use
This skill is applicable to execute the workflow or actions described in the overview.


---
name: scanpy
description: "Scanpy is a scalable Python toolkit for analyzing single-cell RNA-seq data, built on AnnData. Apply this skill for complete single-cell workflows including quality control, normalization, dimensionality reduction, clustering, marker gene identification, visualization, and trajectory analysis."
license: SD-3-Clause license
metadata:
    skill-author: K-Dense Inc.
risk: critical
source: community
---

# Scanpy: Single-Cell Analysis

## Overview

Scanpy is a scalable Python toolkit for analyzing single-cell RNA-seq data, built on AnnData. Apply this skill for complete single-cell workflows including quality control, normalization, dimensionality reduction, clustering, marker gene identification, visualization, and trajectory analysis.

## When to Use This Skill

This skill should be used when:
- Analyzing single-cell RNA-seq data (.h5ad, 10X, CSV formats)
- Performing quality control on scRNA-seq datasets
- Creating UMAP, t-SNE, or PCA visualizations
- Identifying cell clusters and finding marker genes
- Annotating cell types based on gene expression
- Conducting trajectory inference or pseudotime analysis
- Generating publication-quality single-cell plots

## Quick Start

### Basic Import and Setup

```python
import scanpy as sc
import pandas as pd
import numpy as np

# Configure settings
sc.settings.verbosity = 3
sc.settings.set_figure_params(dpi=80, facecolor='white')
sc.settings.figdir = './figures/'
```

### Loading Data

```python
# From 10X Genomics
adata = sc.read_10x_mtx('path/to/data/')
adata = sc.read_10x_h5('path/to/data.h5')

# From h5ad (AnnData format)
adata = sc.read_h5ad('path/to/data.h5ad')

# From CSV
adata = sc.read_csv('path/to/data.csv')
```

### Understanding AnnData Structure

The AnnData object is the core data structure in scanpy:

```python
adata.X          # Expression matrix (cells × genes)
adata.obs        # Cell metadata (DataFrame)
adata.var        # Gene metadata (DataFrame)
adata.uns        # Unstructured annotations (dict)
adata.obsm       # Multi-dimensional cell data (PCA, UMAP)
adata.raw        # Raw data backup

# Access cell and gene names
adata.obs_names  # Cell barcodes
adata.var_names  # Gene names
```

## Standard Analysis Workflow

### 1. Quality Control

Identify and filter low-quality cells and genes:

```python
# Identify mitochondrial genes
adata.var['mt'] = adata.var_names.str.startswith('MT-')

# Calculate QC metrics
sc.pp.calculate_qc_metrics(adata, qc_vars=['mt'], inplace=True)

# Visualize QC metrics
sc.pl.violin(adata, ['n_genes_by_counts', 'total_counts', 'pct_counts_mt'],
             jitter=0.4, multi_panel=True)

# Filter cells and genes
sc.pp.filter_cells(adata, min_genes=200)
sc.pp.filter_genes(adata, min_cells=3)
adata = adata[adata.obs.pct_counts_mt < 5, :]  # Remove high MT% cells
```

**Use the QC script for automated analysis:**
```bash
python scripts/qc_analysis.py input_file.h5ad --output filtered.h5ad
```

### 2. Normalization and Preprocessing

```python
# Normalize to 10,000 counts per cell
sc.pp.normalize_total(adata, target_sum=1e4)

# Log-transform
sc.pp.log1p(adata)

# Save raw counts for later
adata.raw = adata

# Identify highly variable genes
sc.pp.highly_variable_genes(adata, n_top_genes=2000)
sc.pl.highly_variable_genes(adata)

# Subset to highly variable genes
adata = adata[:, adata.var.highly_variable]

# Regress out unwanted variation
sc.pp.regress_out(adata, ['total_counts', 'pct_counts_mt'])

# Scale data
sc.pp.scale(adata, max_value=10)
```

### 3. Dimensionality Reduction

```python
# PCA
sc.tl.pca(adata, svd_solver='arpack')
sc.pl.pca_variance_ratio(adata, log=True)  # Check elbow plot

# Compute neighborhood graph
sc.pp.neighbors(adata, n_neighbors=10, n_pcs=40)

# UMAP for visualization
sc.tl.umap(adata)
sc.pl.umap(adata, color='leiden')

# Alternative: t-SNE
sc.tl.tsne(adata)
```

### 4. Clustering

```python
# Leiden clustering (recommended)
sc.tl.leiden(adata, resolution=0.5)
sc.pl.umap(adata, color='leiden', legend_loc='on data')

# Try multiple resolutions to find optimal granularity
for res in [0.3, 0.5, 0.8, 1.0]:
    sc.tl.leiden(adata, resolution=res, key_added=f'leiden_{res}')
```

### 5. Marker Gene Identification

```python
# Find marker genes for each cluster
sc.tl.rank_genes_groups(adata, 'leiden', method='wilcoxon')

# Visualize results
sc.pl.rank_genes_groups(adata, n_genes=25, sharey=False)
sc.pl.rank_genes_groups_heatmap(adata, n_genes=10)
sc.pl.rank_genes_groups_dotplot(adata, n_genes=5)

# Get results as DataFrame
markers = sc.get.rank_genes_groups_df(adata, group='0')
```

### 6. Cell Type Annotation

```python
# Define marker genes for known cell types
marker_genes = ['CD3D', 'CD14', 'MS4A1', 'NKG7', 'FCGR3A']

# Visualize markers
sc.pl.umap(adata, color=marker_genes, use_raw=True)
sc.pl.dotplot(adata, var_names=marker_genes, groupby='leiden')

# Manual annotation
cluster_to_celltype = {
    '0': 'CD4 T cells',
    '1': 'CD14+ Monocytes',
    '2': 'B cells',
    '3': 'CD8 T cells',
}
adata.obs['cell_type'] = adata.obs['leiden'].map(cluster_to_celltype)

# Visualize annotated types
sc.pl.umap(adata, color='cell_type', legend_loc='on data')
```

### 7. Save Results

```python
# Save processed data
adata.write('results/processed_data.h5ad')

# Export metadata
adata.obs.to_csv('results/cell_metadata.csv')
adata.var.to_csv('results/gene_metadata.csv')
```

## Common Tasks

### Creating Publication-Quality Plots

```python
# Set high-quality defaults
sc.settings.set_figure_params(dpi=300, frameon=False, figsize=(5, 5))
sc.settings.file_format_figs = 'pdf'

# UMAP with custom styling
sc.pl.umap(adata, color='cell_type',
           palette='Set2',
           legend_loc='on data',
           legend_fontsize=12,
           legend_fontoutline=2,
           frameon=False,
           save='_publication.pdf')

# Heatmap of marker genes
sc.pl.heatmap(adata, var_names=genes, groupby='cell_type',
              swap_axes=True, show_gene_labels=True,
              save='_markers.pdf')

# Dot plot
sc.pl.dotplot(adata, var_names=genes, groupby='cell_type',
              save='_dotplot.pdf')
```

Refer to `references/plotting_guide.md` for comprehensive visualization examples.

### Trajectory Inference

```python
# PAGA (Partition-based graph abstraction)
sc.tl.paga(adata, groups='leiden')
sc.pl.paga(adata, color='leiden')

# Diffusion pseudotime
adata.uns['iroot'] = np.flatnonzero(adata.obs['leiden'] == '0')[0]
sc.tl.dpt(adata)
sc.pl.umap(adata, color='dpt_pseudotime')
```

### Differential Expression Between Conditions

```python
# Compare treated vs control within cell types
adata_subset = adata[adata.obs['cell_type'] == 'T cells']
sc.tl.rank_genes_groups(adata_subset, groupby='condition',
                         groups=['treated'], reference='control')
sc.pl.rank_genes_groups(adata_subset, groups=['treated'])
```

### Gene Set Scoring

```python
# Score cells for gene set expression
gene_set = ['CD3D', 'CD3E', 'CD3G']
sc.tl.score_genes(adata, gene_set, score_name='T_cell_score')
sc.pl.umap(adata, color='T_cell_score')
```

### Batch Correction

```python
# ComBat batch correction
sc.pp.combat(adata, key='batch')

# Alternative: use Harmony or scVI (separate packages)
```

## Key Parameters to Adjust

### Quality Control
- `min_genes`: Minimum genes per cell (typically 200-500)
- `min_cells`: Minimum cells per gene (typically 3-10)
- `pct_counts_mt`: Mitochondrial threshold (typically 5-20%)

### Normalization
- `target_sum`: Target counts per cell (default 1e4)

### Feature Selection
- `n_top_genes`: Number of HVGs (typically 2000-3000)
- `min_mean`, `max_mean`, `min_disp`: HVG selection parameters

### Dimensionality Reduction
- `n_pcs`: Number of principal components (check variance ratio plot)
- `n_neighbors`: Number of neighbors (typically 10-30)

### Clustering
- `resolution`: Clustering granularity (0.4-1.2, higher = more clusters)

## Common Pitfalls and Best Practices

1. **Always save raw counts**: `adata.raw = adata` before filtering genes
2. **Check QC plots carefully**: Adjust thresholds based on dataset quality
3. **Use Leiden over Louvain**: More efficient and better results
4. **Try multiple clustering resolutions**: Find optimal granularity
5. **Validate cell type annotations**: Use multiple marker genes
6. **Use `use_raw=True` for gene expression plots**: Shows original counts
7. **Check PCA variance ratio**: Determine optimal number of PCs
8. **Save intermediate results**: Long workflows can fail partway through

## Bundled Resources

### scripts/qc_analysis.py
Automated quality control script that calculates metrics, generates plots, and filters data:

```bash
python scripts/qc_analysis.py input.h5ad --output filtered.h5ad \
    --mt-threshold 5 --min-genes 200 --min-cells 3
```

### references/standard_workflow.md
Complete step-by-step workflow with detailed explanations and code examples for:
- Data loading and setup
- Quality control with visualization
- Normalization and scaling
- Feature selection
- Dimensionality reduction (PCA, UMAP, t-SNE)
- Clustering (Leiden, Louvain)
- Marker gene identification
- Cell type annotation
- Trajectory inference
- Differential expression

Read this reference when performing a complete analysis from scratch.

### references/api_reference.md
Quick reference guide for scanpy functions organized by module:
- Reading/writing data (`sc.read_*`, `adata.write_*`)
- Preprocessing (`sc.pp.*`)
- Tools (`sc.tl.*`)
- Plotting (`sc.pl.*`)
- AnnData structure and manipulation
- Settings and utilities

Use this for quick lookup of function signatures and common parameters.

### references/plotting_guide.md
Comprehensive visualization guide including:
- Quality control plots
- Dimensionality reduction visualizations
- Clustering visualizations
- Marker gene plots (heatmaps, dot plots, violin plots)
- Trajectory and pseudotime plots
- Publication-quality customization
- Multi-panel figures
- Color palettes and styling

Consult this when creating publication-ready figures.

### assets/analysis_template.py
Complete analysis template providing a full workflow from data loading through cell type annotation. Copy and customize this template for new analyses:

```bash
cp assets/analysis_template.py my_analysis.py
# Edit parameters and run
python my_analysis.py
```

The template includes all standard steps with configurable parameters and helpful comments.

## Additional Resources

- **Official scanpy documentation**: https://scanpy.readthedocs.io/
- **Scanpy tutorials**: https://scanpy-tutorials.readthedocs.io/
- **scverse ecosystem**: https://scverse.org/ (related tools: squidpy, scvi-tools, cellrank)
- **Best practices**: Luecken & Theis (2019) "Current best practices in single-cell RNA-seq"

## Tips for Effective Analysis

1. **Start with the template**: Use `assets/analysis_template.py` as a starting point
2. **Run QC script first**: Use `scripts/qc_analysis.py` for initial filtering
3. **Consult references as needed**: Load workflow and API references into context
4. **Iterate on clustering**: Try multiple resolutions and visualization methods
5. **Validate biologically**: Check marker genes match expected cell types
6. **Document parameters**: Record QC thresholds and analysis settings
7. **Save checkpoints**: Write intermediate results at key steps

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: scarcity-urgency-psychologist
description: "One sentence - what this skill does and when to invoke it"
risk: safe
source: community
date_added: "2026-04-04"
---
You are a **Behavioral Psychologist specializing in motivation, reactance, and temporal decision-making**. Your task is to engineer genuine scarcity and urgency mechanics that create real psychological motivation to act now.

## When to Use
- Use when you need urgency or scarcity messaging that feels credible instead of manipulative.
- Use when timing, stock, access, or deadlines should push action without damaging trust.

## CONTEXT GATHERING

Before designing scarcity, establish:

1. **The Target Human** - psychographic profile, cynicism level, and trust stage.
2. **The Objective** - what action must happen now.
3. **The Output** - scarcity and urgency strategy.
4. **Constraints** - actual inventory, deadline truth, and ethics.

If the scarcity is not real, stop and ask for a different strategy.

## PSYCHOLOGICAL FRAMEWORK: GENUINE SCARCITY CALIBRATION

### Mechanism
Scarcity works when the audience believes the opportunity is genuinely limited and personally relevant. If the audience senses manipulation, psychological reactance rises and the tactic can backfire. Use only real scarcity, honest deadlines, and proportionate urgency (Worchel scarcity heuristic; Brehm reactance theory; Omar et al., 2021; Gong et al., 2021; Wang et al., 2025; Suvarna & Malagi, 2025).

### Execution Steps

**Step 1 - Verify the scarcity is real**
Check whether the limit is inventory, capacity, time, access, or attention.
*Research basis: fake scarcity destroys trust when detected (Omar et al., 2021; Wang et al., 2025).*

**Step 2 - Decide whether urgency is needed**
Not every scarce offer needs a deadline.
*Research basis: urgency is effective only when delay has a real cost (temporal discounting research; Brehm).*

**Step 3 - Match the frame to cynicism**
Use softer language when the audience is skeptical and stronger language when the limit is obvious.
*Research basis: reactance increases as the audience perceives pressure or manipulation (Grandpre et al., 2003; Quick et al., 2018).*

**Step 4 - State the consequence clearly**
Explain what happens if the user waits.
*Research basis: visible opportunity cost increases action more than vague urgency (Houdek, 2016; Suvarna & Malagi, 2025).*

**Step 5 - Keep the tone calm**
Avoid panic language.
*Research basis: high-pressure scarcity can trigger avoidance and doubt (Brehm; Lavoie & Quick, 2013).*

## DECISION MATRIX

### Variable: scarcity type
- If inventory-limited -> state the actual remaining quantity.
- If capacity-limited -> explain slots, seats, or bandwidth honestly.
- If time-limited -> explain the real deadline and why it exists.
- If access-limited -> explain the genuine window or eligibility.

### Variable: audience cynicism
- If high -> use transparent, minimal urgency.
- If medium -> combine clarity with consequence.
- If low -> you can be slightly more vivid, but still honest.

### Variable: category norm
- If urgency is expected -> a deadline can be effective.
- If urgency is unusual -> be especially careful.
- If urgency is common and abused -> use scarcity sparingly.

## FAILURE MODES - DO NOT DO THESE

**Failure Mode 1**
- Agents typically: invent scarcity.
- Why it fails psychologically: once the trick is detected, credibility drops sharply.
- Instead: use real limits only.

**Failure Mode 2**
- Agents typically: overuse countdowns and alarms.
- Why it fails psychologically: urgency fatigue makes people tune out.
- Instead: use the minimum urgent cue needed.

**Failure Mode 3**
- Agents typically: pair scarcity with aggressive pressure.
- Why it fails psychologically: reactance turns motivation into resistance.
- Instead: keep the tone calm and choice-preserving.

## ETHICAL GUARDRAILS

This skill must:
- Use real scarcity.
- Avoid fake deadlines and fake stock counts.
- Preserve choice and clarity.

The line between persuasion and manipulation is making a real opportunity timely versus manufacturing panic to force a purchase. Never cross it.

## SKILL CHAINING

Before invoking this skill, the agent should have completed:
- [ ] `@loss-aversion-designer`
- [ ] `@trust-calibrator`

This skill's output feeds into:
- [ ] `@copywriting-psychologist`
- [ ] `@sequence-psychologist`
- [ ] `@price-psychology-strategist`

## OUTPUT QUALITY CHECK

Before finalizing output, the agent asks:
- [ ] Is the scarcity real?
- [ ] Is urgency actually needed?
- [ ] Did I match the tone to the audience's cynicism?
- [ ] Did I avoid panic language?
- [ ] Does this preserve trust and autonomy?

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: schema-markup
description: Design, validate, and optimize schema.org structured data for eligibility, correctness, and measurable SEO impact.
risk: critical
source: community
date_added: '2026-02-27'
---

# Schema Markup & Structured Data

You are an expert in **structured data and schema markup** with a focus on
**Google rich result eligibility, accuracy, and impact**.

Your responsibility is to:

- Determine **whether schema markup is appropriate**
- Identify **which schema types are valid and eligible**
- Prevent invalid, misleading, or spammy markup
- Design **maintainable, correct JSON-LD**
- Avoid over-markup that creates false expectations

You do **not** guarantee rich results.
You do **not** add schema that misrepresents content.

---

## Phase 0: Schema Eligibility & Impact Index (Required)

Before writing or modifying schema, calculate the **Schema Eligibility & Impact Index**.

### Purpose

The index answers:

> **Is schema markup justified here, and is it likely to produce measurable benefit?**

---

## 🔢 Schema Eligibility & Impact Index

### Total Score: **0–100**

This is a **diagnostic score**, not a promise of rich results.

---

### Scoring Categories & Weights

| Category                         | Weight  |
| -------------------------------- | ------- |
| Content–Schema Alignment         | 25      |
| Rich Result Eligibility (Google) | 25      |
| Data Completeness & Accuracy     | 20      |
| Technical Correctness            | 15      |
| Maintenance & Sustainability     | 10      |
| Spam / Policy Risk               | 5       |
| **Total**                        | **100** |

---

### Category Definitions

#### 1. Content–Schema Alignment (0–25)

- Schema reflects **visible, user-facing content**
- Marked entities actually exist on the page
- No hidden or implied content

**Automatic failure** if schema describes content not shown.

---

#### 2. Rich Result Eligibility (0–25)

- Schema type is **supported by Google**
- Page meets documented eligibility requirements
- No known disqualifying patterns (e.g. self-serving reviews)

---

#### 3. Data Completeness & Accuracy (0–20)

- All required properties present
- Values are correct, current, and formatted properly
- No placeholders or fabricated data

---

#### 4. Technical Correctness (0–15)

- Valid JSON-LD
- Correct nesting and types
- No syntax, enum, or formatting errors

---

#### 5. Maintenance & Sustainability (0–10)

- Data can be kept in sync with content
- Updates won’t break schema
- Suitable for templates if scaled

---

#### 6. Spam / Policy Risk (0–5)

- No deceptive intent
- No over-markup
- No attempt to game rich results

---

### Scoring Guidance per Category

For each of the six scoring categories, allot points within the category's weight band using these anchors:

- **0–15% of band:** Schema describes none of the visible content (e.g. you would mark `description` for a `Recipe` page that has no recipe markup yet).
- **16–40% of band:** Partial alignment — the schema describes some but not all of the visible content, OR maps to a less-common schema.org type.
- **41–80% of band:** Strong alignment — the schema describes the bulk of the visible content with a common schema.org type.
- **81–100% of band:** Exemplary — the schema covers all visible content, uses a Google-supported rich-result type, and includes all required properties.

Sum the per-category scores to compute the Eligibility Index used in §"Eligibility Bands" below.

### Eligibility Bands (Required)

| Score  | Verdict               | Interpretation                        |
| ------ | --------------------- | ------------------------------------- |
| 85–100 | **Strong Candidate**  | Schema is appropriate and low risk    |
| 70–84  | **Valid but Limited** | Use selectively, expect modest impact |
| 55–69  | **High Risk**         | Implement only with strict controls   |
| <55    | **Do Not Implement**  | Likely invalid or harmful             |

If verdict is **Do Not Implement**, stop and explain why.

---

## Phase 1: Page & Goal Assessment

(Proceed only if score ≥ 70)

### 1. Page Type

- What kind of page is this?
- Primary content entity
- Single-entity vs multi-entity page

### 2. Current State

- Existing schema present?
- Errors or warnings?
- Rich results currently shown?

### 3. Objective

- Which rich result (if any) is targeted?
- Expected benefit (CTR, clarity, trust)
- Is schema _necessary_ to achieve this?

---

## Core Principles (Non-Negotiable)

### 1. Accuracy Over Ambition

- Schema must match visible content exactly
- Do not “add content for schema”
- Remove schema if content is removed

---

### 2. Google First, Schema.org Second

- Follow **Google rich result documentation**
- Schema.org allows more than Google supports
- Unsupported types provide minimal SEO value

---

### 3. Minimal, Purposeful Markup

- Add only schema that serves a clear purpose
- Avoid redundant or decorative markup
- More schema ≠ better SEO

---

### 4. Continuous Validation

- Validate before deployment
- Monitor Search Console enhancements
- Fix errors promptly

---

## Supported & Common Schema Types

_(Only implement when eligibility criteria are met.)_

### Organization

Use for: brand entity (homepage or about page)

### WebSite (+ SearchAction)

Use for: enabling sitelinks search box

### Article / BlogPosting

Use for: editorial content with authorship

### Product

Use for: real purchasable products
**Must show price, availability, and offers visibly**

---

### SoftwareApplication

Use for: SaaS apps and tools

---

### FAQPage

Use only when:

- Questions and answers are visible
- Not used for promotional content
- Not user-generated without moderation

---

### HowTo

Use only for:

- Genuine step-by-step instructional content
- Not marketing funnels

---

### BreadcrumbList

Use whenever breadcrumbs exist visually

---

### LocalBusiness

Use for: real, physical business locations

---

### Review / AggregateRating

**Strict rules:**

- Reviews must be genuine
- No self-serving reviews
- Ratings must match visible content

---

### Event

Use for: real events with clear dates and availability

---

## Multiple Schema Types per Page

Use `@graph` when representing multiple entities.

Rules:

- One primary entity per page
- Others must relate logically
- Avoid conflicting entity definitions

---

## Validation & Testing

### Required Tools

- Google Rich Results Test
- Schema.org Validator
- Search Console Enhancements

### Common Failure Patterns

- Missing required properties
- Mismatched values
- Hidden or fabricated data
- Incorrect enum values
- Dates not in ISO 8601

---

## Implementation Guidance

### Static Sites

- Embed JSON-LD in templates
- Use includes for reuse

### Frameworks (React / Next.js)

- Server-side rendered JSON-LD
- Data serialized directly from source

### CMS / WordPress

- Prefer structured plugins
- Use custom fields for dynamic values
- Avoid hardcoded schema in themes

---

## Output Format (Required)

### Schema Strategy Summary

- Eligibility Index score + verdict
- Supported schema types
- Risks and constraints

### JSON-LD Implementation

```json
{
  "@context": "https://schema.org",
  "@type": "...",
  ...
}
```

### Placement Instructions

Where and how to add it

### Validation Checklist

- [ ] Valid JSON-LD
- [ ] Passes Rich Results Test
- [ ] Matches visible content
- [ ] Meets Google eligibility rules

---

## Questions to Ask (If Needed)

1. What content is visible on the page?
2. Which rich result are you targeting (if any)?
3. Is this content templated or editorial?
4. How is this data maintained?
5. Is schema already present?

---

## Related Skills

- **seo-audit** – Full SEO review including schema
- **programmatic-seo** – Templated schema at scale
- **analytics-tracking** – Measure rich result impact

## When to Use
This skill is applicable to execute the workflow or actions described in the overview.

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: schema-markup-generator
description: "Generate and implement JSON-LD structured data for web apps, blogs, FAQs, and SaaS sites. Supports WebSite, SoftwareApplication, BlogPosting, FAQPage, HowTo, and more."
category: seo
risk: safe
source: self
source_type: self
date_added: "2026-05-31"
author: Whoisabhishekadhikari
tags: [seo, schema, json-ld, structured-data, rich-results, nextjs, technical-seo]
tools: [claude, cursor, gemini, claude-code]
version: 1.0.0
---

# Schema Markup Generator Skill

Add JSON-LD structured data to pages to unlock rich results, improve CTR, and signal context to Google and AI systems.

---

## When to Use

- Use when adding or auditing JSON-LD schema for websites, SaaS apps, tools, articles, FAQs, breadcrumbs, or organization pages.
- Use when schema must be implemented in Next.js App Router or validated against Google Rich Results and Schema.org tooling.
- Use when a page has strong content but lacks structured data for search engines and rich-result eligibility.

---

## How to Add Schema in Next.js App Router

The cleanest approach is a reusable `JsonLd` component:

```jsx
// components/JsonLd.jsx
export function JsonLd({ data }) {
  const json = JSON.stringify(data).replace(/</g, '\\u003c');
  return (
    <script
      type="application/ld+json"
      dangerouslySetInnerHTML={{ __html: json }}
    />
  );
}
```

Use it in any page:
```jsx
import { JsonLd } from '@/components/JsonLd';

export default function MyPage() {
  return (
    <>
      <JsonLd data={mySchemaObject} />
      {/* rest of page */}
    </>
  );
}
```

---

## Schema Types by Page Type

### WebSite + Sitelinks Searchbox (homepage only)
```js
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "name": "100 SEO Tools",
  "url": "https://www.100seotools.com",
  "description": "Free online SEO tools for keyword research, technical audits, and more.",
  "potentialAction": {
    "@type": "SearchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "https://www.100seotools.com/search?q={search_term_string}"
    },
    "query-input": "required name=search_term_string"
  }
}
```

---

### SoftwareApplication (tool / SaaS app pages)
```js
{
  "@context": "https://schema.org",
  "@type": "SoftwareApplication",
  "name": "Keyword Density Checker",
  "applicationCategory": "WebApplication",
  "operatingSystem": "Web",
  "url": "https://www.100seotools.com/tools/keyword-density-checker",
  "description": "Free keyword density checker tool. Analyze keyword frequency and optimize your content for SEO.",
  "offers": {
    "@type": "Offer",
    "price": "0",
    "priceCurrency": "USD"
  },
  "featureList": [
    "Analyze keyword frequency",
    "Detect over-optimization",
    "Export results as CSV"
  ],
  "provider": {
    "@type": "Organization",
    "name": "100 SEO Tools",
    "url": "https://www.100seotools.com"
  }
}
```

---

### Article / BlogPosting (blog posts)
```js
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "How to Improve Your Core Web Vitals in 2025",
  "description": "A practical guide to improving LCP, FID, and CLS scores for better rankings.",
  "url": "https://www.100seotools.com/blog/improve-core-web-vitals",
  "datePublished": "2025-01-15",
  "dateModified": "2025-03-20",
  "author": {
    "@type": "Person",
    "name": "Jane Smith",
    "url": "https://www.100seotools.com/author/jane-smith"
  },
  "publisher": {
    "@type": "Organization",
    "name": "100 SEO Tools",
    "logo": {
      "@type": "ImageObject",
      "url": "https://www.100seotools.com/logo.png"
    }
  },
  "image": {
    "@type": "ImageObject",
    "url": "https://www.100seotools.com/images/blog/core-web-vitals.jpg",
    "width": 1200,
    "height": 630
  },
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://www.100seotools.com/blog/improve-core-web-vitals"
  }
}
```

---

### FAQPage (FAQ sections, tool help pages)
```js
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "What is keyword density?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Keyword density is the percentage of times a keyword appears in a piece of content relative to the total word count. A healthy keyword density is typically 1-3%."
      }
    },
    {
      "@type": "Question",
      "name": "Is this tool free to use?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Yes, our keyword density checker is completely free with no registration required."
      }
    }
  ]
}
```

---

### HowTo (step-by-step tool guides)
```js
{
  "@context": "https://schema.org",
  "@type": "HowTo",
  "name": "How to Check Keyword Density",
  "description": "Step-by-step guide to analyzing keyword density using our free tool.",
  "totalTime": "PT2M",
  "step": [
    {
      "@type": "HowToStep",
      "position": 1,
      "name": "Paste your content",
      "text": "Copy your article or webpage content and paste it into the text area.",
      "image": "https://www.100seotools.com/images/how-to/step1.jpg"
    },
    {
      "@type": "HowToStep",
      "position": 2,
      "name": "Enter your target keyword",
      "text": "Type the keyword you want to analyze in the keyword field."
    },
    {
      "@type": "HowToStep",
      "position": 3,
      "name": "Click Analyze",
      "text": "Press the Analyze button to get your keyword density report instantly."
    }
  ]
}
```

---

### BreadcrumbList (all non-homepage pages)
```js
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "Home",
      "item": "https://www.100seotools.com"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "SEO Tools",
      "item": "https://www.100seotools.com/tools"
    },
    {
      "@type": "ListItem",
      "position": 3,
      "name": "Keyword Density Checker",
      "item": "https://www.100seotools.com/tools/keyword-density-checker"
    }
  ]
}
```

---

### Organization (about, contact pages)
```js
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "100 SEO Tools",
  "url": "https://www.100seotools.com",
  "logo": "https://www.100seotools.com/logo.png",
  "sameAs": [
    "https://twitter.com/100seotools",
    "https://www.linkedin.com/company/100seotools"
  ],
  "contactPoint": {
    "@type": "ContactPoint",
    "contactType": "customer support",
    "email": "hello@100seotools.com"
  }
}
```

---

## Combining Multiple Schemas on One Page

A tool page can have BreadcrumbList + SoftwareApplication + FAQPage:

```jsx
export default function ToolPage() {
  return (
    <>
      <JsonLd data={breadcrumbSchema} />
      <JsonLd data={softwareApplicationSchema} />
      <JsonLd data={faqSchema} />
      {/* page content */}
    </>
  );
}
```

Each schema lives in its own `<script>` tag — do NOT merge them into one object.

---

## Validation

Always validate schema before deploying:

1. **Google Rich Results Test** — https://search.google.com/test/rich-results
2. **Schema.org Validator** — https://validator.schema.org/
3. **Google Search Console** → Enhancements → check for warnings after deployment

```bash
# Quick check: schema appears in HTML
curl -s https://www.yourdomain.com/tools/keyword-density | grep -A 5 "application/ld+json"
```

---

## Schema Markup Checklist

- [ ] Homepage has `WebSite` schema
- [ ] Tool/app pages have `SoftwareApplication` schema
- [ ] Blog posts have `BlogPosting` / `Article` schema
- [ ] FAQ sections have `FAQPage` schema
- [ ] Step-by-step guides have `HowTo` schema
- [ ] All non-homepage pages have `BreadcrumbList`
- [ ] About/contact page has `Organization` schema
- [ ] All URLs in schema are absolute HTTPS
- [ ] Schema validated with Google Rich Results Test
- [ ] No schema errors in Google Search Console

## Limitations

- Does not guarantee rich-result eligibility or display; Google and other consumers decide whether to use valid schema.
- Generated examples must be adapted to the site's real content, legal entity details, ratings, pricing, and availability.
- Always validate deployed HTML, not only source code, because frameworks and rendering modes can change the final markup.


---
name: sci-fi-interface
description: Web and App implementation guide for Sci-Fi Interface Design. Trigger when user wants HUDs, spacecraft dashboards, or tactical military readouts.
date_added: "2026-06-17"
risk: safe
source: self
source_type: self
---

# Sci-Fi Interface Design (HUD)

> "Heads-Up Display. Tactical, precise, and highly analytical."

## When to Use
Use this sub-style when the user's request matches the aesthetic described above. This is a child reference of the `design-it` skill and is not meant to be triggered directly.

## Core Principles
1. **Wireframe and Outlines**: Interfaces are built almost entirely out of thin strokes rather than solid filled boxes.
2. **Circular Arrays & Radars**: Heavy use of concentric circles, radar sweeps, and curved progress bars.
3. **Monochrome + Warning**: Often entirely monochromatic (just blue, or just green) with a secondary color (red) used exclusively for alerts.

## Visual DNA
- **Colors**: Midnight background. UI is pure Cyan, Emerald Green, or Amber (like classic monochrome monitors). **Minimalist Slate** works if made dark.
- **Typography**: Strict, technical monospace fonts (`Share Tech Mono`, `VT323`, `Space Mono`). All caps.
- **Styling**: Tiny UI chroming details (target brackets `[ ]`, framing lines, precise pixel coordinates).

## Web Implementation
- Heavy use of SVG for circular dials, and CSS borders for the layout.
- **CSS Example**:
```css
body {
  background-color: #000b18; /* Deep space navy */
  color: #4df; /* Holographic cyan */
  font-family: 'Share Tech Mono', monospace;
  text-transform: uppercase;
}

/* The HUD Frame */
.hud-container {
  border: 1px solid rgba(68, 221, 255, 0.3);
  position: relative;
  padding: 30px;
}

/* Corner brackets */
.hud-container::before {
  content: '';
  position: absolute;
  top: -2px; left: -2px;
  width: 20px; height: 20px;
  border-top: 2px solid #4df;
  border-left: 2px solid #4df;
}
.hud-container::after {
  content: '';
  position: absolute;
  bottom: -2px; right: -2px;
  width: 20px; height: 20px;
  border-bottom: 2px solid #4df;
  border-right: 2px solid #4df;
}

.hud-value {
  font-size: 3rem;
  text-shadow: 0 0 10px rgba(68, 221, 255, 0.8);
}

.hud-warning {
  color: #ff3333;
  text-shadow: 0 0 10px rgba(255, 51, 51, 0.8);
  animation: blink 1s step-end infinite;
}

@keyframes blink { 50% { opacity: 0; } }
```

## App Implementation

### SwiftUI
```swift
struct SciFiHUDView: View {
    @State private var bootUp = false

    var body: some View {
        ZStack {
            Color(hex: "000b18").ignoresSafeArea() // Deep space navy

            VStack {
                // Circular Radar/Dial
                ZStack {
                    Circle()
                        .stroke(Color(hex: "4df").opacity(0.3), lineWidth: 1)

                    Circle()
                        .trim(from: 0.0, to: bootUp ? 0.75 : 0.0)
                        .stroke(Color(hex: "4df"), style: StrokeStyle(lineWidth: 4, lineCap: .round))
                        .rotationEffect(.degrees(-90))

                    Text("SYS.OK")
                        .font(.custom("Space Mono", size: 24))
                        .foregroundColor(Color(hex: "4df"))
                        .shadow(color: Color(hex: "4df"), radius: 5)
                }
                .frame(width: 200, height: 200)
                .padding(.bottom, 40)

                // HUD Data Frame
                HStack {
                    Text("COORD: 45.22, 12.8")
                    Spacer()
                    Text("[ LOCK ]")
                }
                .font(.custom("Space Mono", size: 16))
                .foregroundColor(Color(hex: "4df"))
                .padding()
                .border(Color(hex: "4df").opacity(0.5), width: 1)
                .overlay(
                    // Corner bracket accents
                    Path { path in
                        path.move(to: CGPoint(x: 0, y: 15)); path.addLine(to: CGPoint(x: 0, y: 0)); path.addLine(to: CGPoint(x: 15, y: 0))
                        path.move(to: CGPoint(x: 300, y: 15)); path.addLine(to: CGPoint(x: 300, y: 0)); path.addLine(to: CGPoint(x: 285, y: 0))
                    }
                    .stroke(Color(hex: "4df"), lineWidth: 2)
                )
            }
            .padding()
        }
        .onAppear {
            withAnimation(.easeInOut(duration: 2.0)) { bootUp = true }
        }
    }
}
```
- SwiftUI is uniquely fantastic for Sci-Fi HUDs. `Circle().trim(from: to:)` lets you build complex sweeping circular progress rings.
- Use `Path` overlays to draw the exact 90-degree corner brackets (`[ ]`) that define the HUD look.

### Flutter
```dart
class SciFiHUDScreen extends StatefulWidget {
  @override
  State<SciFiHUDScreen> createState() => _SciFiHUDScreenState();
}

class _SciFiHUDScreenState extends State<SciFiHUDScreen> with SingleTickerProviderStateMixin {
  late AnimationController _ctrl;

  @override
  void initState() {
    super.initState();
    _ctrl = AnimationController(vsync: this, duration: const Duration(seconds: 2))..forward();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      backgroundColor: const Color(0xFF000B18),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            // Circular Radar
            SizedBox(
              width: 200, height: 200,
              child: Stack(
                fit: StackFit.expand,
                children: [
                  CircularProgressIndicator(value: 1.0, strokeWidth: 1, color: const Color(0xFF44DDFF).withOpacity(0.3)),
                  AnimatedBuilder(
                    animation: _ctrl,
                    builder: (context, _) => CircularProgressIndicator(
                      value: _ctrl.value * 0.75, // 75% full
                      strokeWidth: 4,
                      color: const Color(0xFF44DDFF),
                    ),
                  ),
                  const Center(
                    child: Text('SYS.OK', style: TextStyle(fontFamily: 'SpaceMono', color: Color(0xFF44DDFF), fontSize: 24, shadows: [Shadow(color: Color(0xFF44DDFF), blurRadius: 5)])),
                  )
                ],
              ),
            ),
            const SizedBox(height: 40),

            // HUD Data Frame (requires CustomPaint for true corner brackets)
            Container(
              width: 300,
              padding: const EdgeInsets.all(16),
              decoration: BoxDecoration(border: Border.all(color: const Color(0xFF44DDFF).withOpacity(0.5))),
              child: const Row(
                mainAxisAlignment: MainAxisAlignment.spaceBetween,
                children: [
                  Text('COORD: 45.22, 12.8', style: TextStyle(fontFamily: 'SpaceMono', color: Color(0xFF44DDFF))),
                  Text('[ LOCK ]', style: TextStyle(fontFamily: 'SpaceMono', color: Color(0xFF44DDFF))),
                ],
              ),
            )
          ],
        ),
      ),
    );
  }
}
```
- `CircularProgressIndicator` is an easy hack for circular HUD rings, but for true Sci-Fi interfaces in Flutter, you should build a `CustomPainter` to draw concentric stroked circles and arcs.
- Heavy use of monospace fonts and pure cyan (`#44DDFF`).

### React Native
```jsx
// Requires react-native-svg
import Svg, { Circle, Path } from 'react-native-svg';

const SciFiHUDScreen = () => {
  return (
    <View style={{ flex: 1, backgroundColor: '#000B18', justifyContent: 'center', alignItems: 'center' }}>

      {/* Circular Radar */}
      <View style={{ width: 200, height: 200, justifyContent: 'center', alignItems: 'center', marginBottom: 40 }}>
        <Svg height="200" width="200" style={{ position: 'absolute' }}>
          <Circle cx="100" cy="100" r="90" stroke="rgba(68, 221, 255, 0.3)" strokeWidth="1" fill="none" />
          <Circle cx="100" cy="100" r="90" stroke="#4df" strokeWidth="4" strokeDasharray="565" strokeDashoffset="140" fill="none" />
        </Svg>
        <Text style={{ fontFamily: 'monospace', color: '#4df', fontSize: 24, textShadowColor: '#4df', textShadowRadius: 5 }}>
          SYS.OK
        </Text>
      </View>

      {/* HUD Frame */}
      <View style={{
        width: 300, padding: 16, flexDirection: 'row', justifyContent: 'space-between',
        borderColor: 'rgba(68, 221, 255, 0.5)', borderWidth: 1
      }}>
        <Text style={{ fontFamily: 'monospace', color: '#4df' }}>COORD: 45.22, 12.8</Text>
        <Text style={{ fontFamily: 'monospace', color: '#4df' }}>[ LOCK ]</Text>

        {/* Pseudo Corner Brackets using absolute views */}
        <View style={{ position: 'absolute', top: -2, left: -2, width: 15, height: 15, borderTopWidth: 2, borderLeftWidth: 2, borderColor: '#4df' }} />
        <View style={{ position: 'absolute', bottom: -2, right: -2, width: 15, height: 15, borderBottomWidth: 2, borderRightWidth: 2, borderColor: '#4df' }} />
      </View>

    </View>
  );
};
```
- You absolutely must use `react-native-svg` to draw circular HUD dials. Use `strokeDasharray` and `strokeDashoffset` on the `<Circle>` to draw arcs.
- The corner brackets are built easily by absolutely positioning small `View`s with 2 active borders over the corners of a container.

### Jetpack Compose
```kotlin
@Composable
fun SciFiHUDScreen() {
    // Animation for boot up
    val transition = rememberInfiniteTransition()
    val sweep by transition.animateFloat(initialValue = 0f, targetValue = 270f, animationSpec = infiniteRepeatable(tween(2000), RepeatMode.Restart))

    Column(
        modifier = Modifier.fillMaxSize().background(Color(0xFF000B18)),
        horizontalAlignment = Alignment.CenterHorizontally,
        verticalArrangement = Arrangement.Center
    ) {
        // Circular Radar
        Box(contentAlignment = Alignment.Center, modifier = Modifier.size(200.dp)) {
            Canvas(modifier = Modifier.fillMaxSize()) {
                drawCircle(color = Color(0xFF44DDFF).copy(alpha = 0.3f), style = Stroke(width = 2f))
                drawArc(
                    color = Color(0xFF44DDFF),
                    startAngle = -90f,
                    sweepAngle = sweep,
                    useCenter = false,
                    style = Stroke(width = 8f, cap = StrokeCap.Round)
                )
            }
            Text("SYS.OK", color = Color(0xFF44DDFF), fontFamily = FontFamily.Monospace, fontSize = 24.sp)
        }

        Spacer(Modifier.height(40.dp))

        // HUD Frame
        Box(modifier = Modifier.width(300.dp)) {
            Row(
                modifier = Modifier.fillMaxWidth().border(1.dp, Color(0xFF44DDFF).copy(alpha = 0.5f)).padding(16.dp),
                horizontalArrangement = Arrangement.SpaceBetween
            ) {
                Text("COORD: 45.22, 12.8", color = Color(0xFF44DDFF), fontFamily = FontFamily.Monospace)
                Text("[ LOCK ]", color = Color(0xFF44DDFF), fontFamily = FontFamily.Monospace)
            }

            // Corner brackets via Canvas
            Canvas(modifier = Modifier.fillMaxSize()) {
                val path = Path().apply {
                    moveTo(0f, 40f); lineTo(0f, 0f); lineTo(40f, 0f) // Top Left
                    moveTo(size.width, size.height - 40f); lineTo(size.width, size.height); lineTo(size.width - 40f, size.height) // Bottom Right
                }
                drawPath(path, color = Color(0xFF44DDFF), style = Stroke(width = 4f))
            }
        }
    }
}
```
- Jetpack Compose's `Canvas` is incredibly powerful here. Use `drawArc` for the circular HUD rings.
- Draw the corner brackets on a `Canvas` overlaying the Box using `Path().apply { moveTo... lineTo... }`.

## Do's and Don'ts
- **DO**: Animate elements entering the screen as if they are 'booting up' or 'calibrating' (drawing lines from 0 to 100%).
- **DON'T**: Use drop shadows. Light in a HUD is emitted, not blocked. Use `text-shadow` for glows instead.

## Limitations
- This is a styling reference and does not replace environment-specific validation, accessibility testing, or expert review.
- Ensure appropriate contrast ratios and responsive behaviors are verified separately.


---
name: scientific-writing
description: "This is the core skill for the deep research and writing tool—combining AI-driven deep research with well-formatted written outputs. Every document produced is backed by comprehensive literature search and verified citations through the research-lookup skill."
license: MIT license
metadata:
    skill-author: K-Dense Inc.
risk: critical
source: community
---

# Scientific Writing

## Overview

**This is the core skill for the deep research and writing tool**—combining AI-driven deep research with well-formatted written outputs. Every document produced is backed by comprehensive literature search and verified citations through the research-lookup skill.

Scientific writing is a process for communicating research with precision and clarity. Write manuscripts using IMRAD structure, citations (APA/AMA/Vancouver), figures/tables, and reporting guidelines (CONSORT/STROBE/PRISMA). Apply this skill for research papers and journal submissions.

**Critical Principle: Always write in full paragraphs with flowing prose. Never submit bullet points in the final manuscript.** Use a two-stage process: first create section outlines with key points using research-lookup, then convert those outlines into complete paragraphs.

## When to Use This Skill

This skill should be used when:
- Writing or revising any section of a scientific manuscript (abstract, introduction, methods, results, discussion)
- Structuring a research paper using IMRAD or other standard formats
- Formatting citations and references in specific styles (APA, AMA, Vancouver, Chicago, IEEE)
- Creating, formatting, or improving figures, tables, and data visualizations
- Applying study-specific reporting guidelines (CONSORT for trials, STROBE for observational studies, PRISMA for reviews)
- Drafting abstracts that meet journal requirements (structured or unstructured)
- Preparing manuscripts for submission to specific journals
- Improving writing clarity, conciseness, and precision
- Ensuring proper use of field-specific terminology and nomenclature
- Addressing reviewer comments and revising manuscripts

## Visual Enhancement with Scientific Schematics

**⚠ MANDATORY: Every scientific paper MUST include a graphical abstract plus 1-2 additional AI-generated figures using the scientific-schematics skill.**

This is not optional. Scientific papers without visual elements are incomplete. Before finalizing any document:
1. **ALWAYS generate a graphical abstract** as the first visual element
2. Generate at minimum ONE additional schematic or diagram using scientific-schematics
3. Prefer 3-4 total figures for comprehensive papers (graphical abstract + methods flowchart + results visualization + conceptual diagram)

### Graphical Abstract (REQUIRED)

**Every scientific writeup MUST include a graphical abstract.** This is a visual summary of your paper that:
- Appears before or immediately after the text abstract
- Captures the entire paper's key message in one image
- Is suitable for journal table of contents display
- Uses landscape orientation (typically 1200x600px)

**Generate the graphical abstract FIRST:**
```bash
python scripts/generate_schematic.py "Graphical abstract for [paper title]: [brief description showing workflow from input → methods → key findings → conclusions]" -o figures/graphical_abstract.png
```

**Graphical Abstract Requirements:**
- **Content**: Visual summary showing workflow, key methods, main findings, and conclusions
- **Style**: Clean, professional, suitable for journal TOC
- **Elements**: Include 3-5 key steps/concepts with connecting arrows or flow
- **Text**: Minimal labels, large readable fonts
- Log: `[HH:MM:SS] GENERATED: Graphical abstract for paper summary`

### Additional Figures (GENERATE EXTENSIVELY)

**⚠ CRITICAL: Use BOTH scientific-schematics AND generate-image EXTENSIVELY throughout all documents.**

Every document should be richly illustrated. Generate figures liberally - when in doubt, add a visual.

**MINIMUM Figure Requirements:**

| Document Type | Minimum | Recommended |
|--------------|---------|-------------|
| Research Papers | 5 | 6-8 |
| Literature Reviews | 4 | 5-7 |
| Market Research | 20 | 25-30 |
| Presentations | 1/slide | 1-2/slide |
| Posters | 6 | 8-10 |
| Grants | 4 | 5-7 |
| Clinical Reports | 3 | 4-6 |

**Use scientific-schematics EXTENSIVELY for technical diagrams:**
```bash
python scripts/generate_schematic.py "your diagram description" -o figures/output.png
```

- Study design and methodology flowcharts (CONSORT, PRISMA, STROBE)
- Conceptual framework diagrams
- Experimental workflow illustrations
- Data analysis pipeline diagrams
- Biological pathway or mechanism diagrams
- System architecture visualizations
- Neural network architectures
- Decision trees, algorithm flowcharts
- Comparison matrices, timeline diagrams
- Any technical concept that benefits from schematic visualization

**Use generate-image EXTENSIVELY for visual content:**
```bash
python scripts/generate_image.py "your image description" -o figures/output.png
```

- Photorealistic illustrations of concepts
- Medical/anatomical illustrations
- Environmental/ecological scenes
- Equipment and lab setup visualizations
- Artistic visualizations, infographics
- Cover images, header graphics
- Product mockups, prototype visualizations
- Any visual that enhances understanding or engagement

The AI will automatically:
- Create publication-quality images with proper formatting
- Review and refine through multiple iterations
- Ensure accessibility (colorblind-friendly, high contrast)
- Save outputs in the figures/ directory

**When in Doubt, Generate a Figure:**
- Complex concept → generate a schematic
- Data discussion → generate a visualization
- Process description → generate a flowchart
- Comparison → generate a comparison diagram
- Reader benefit → generate a visual

For detailed guidance, refer to the scientific-schematics and generate-image skill documentation.

---

## Core Capabilities

### 1. Manuscript Structure and Organization

**IMRAD Format**: Guide papers through the standard Introduction, Methods, Results, And Discussion structure used across most scientific disciplines. This includes:
- **Introduction**: Establish research context, identify gaps, state objectives
- **Methods**: Detail study design, populations, procedures, and analysis approaches
- **Results**: Present findings objectively without interpretation
- **Discussion**: Interpret results, acknowledge limitations, propose future directions

For detailed guidance on IMRAD structure, refer to `references/imrad_structure.md`.

**Alternative Structures**: Support discipline-specific formats including:
- Review articles (narrative, systematic, scoping)
- Case reports and case series
- Meta-analyses and pooled analyses
- Theoretical/modeling papers
- Methods papers and protocols

### 2. Section-Specific Writing Guidance

**Abstract Composition**: Craft concise, standalone summaries (100-250 words) that capture the paper's purpose, methods, results, and conclusions. Support both structured abstracts (with labeled sections) and unstructured single-paragraph formats.

**Introduction Development**: Build compelling introductions that:
- Establish the research problem's importance
- Review relevant literature systematically
- Identify knowledge gaps or controversies
- State clear research questions or hypotheses
- Explain the study's novelty and significance

**Methods Documentation**: Ensure reproducibility through:
- Detailed participant/sample descriptions
- Clear procedural documentation
- Statistical methods with justification
- Equipment and materials specifications
- Ethical approval and consent statements

**Results Presentation**: Present findings with:
- Logical flow from primary to secondary outcomes
- Integration with figures and tables
- Statistical significance with effect sizes
- Objective reporting without interpretation

**Discussion Construction**: Synthesize findings by:
- Relating results to research questions
- Comparing with existing literature
- Acknowledging limitations honestly
- Proposing mechanistic explanations
- Suggesting practical implications and future research

### 3. Citation and Reference Management

Apply citation styles correctly across disciplines. For comprehensive style guides, refer to `references/citation_styles.md`.

**Major Citation Styles:**
- **AMA (American Medical Association)**: Numbered superscript citations, common in medicine
- **Vancouver**: Numbered citations in square brackets, biomedical standard
- **APA (American Psychological Association)**: Author-date in-text citations, common in social sciences
- **Chicago**: Notes-bibliography or author-date, humanities and sciences
- **IEEE**: Numbered square brackets, engineering and computer science

**Best Practices:**
- Cite primary sources when possible
- Include recent literature (last 5-10 years for active fields)
- Balance citation distribution across introduction and discussion
- Verify all citations against original sources
- Use reference management software (Zotero, Mendeley, EndNote)

### 4. Figures and Tables

Create effective data visualizations that enhance comprehension. For detailed best practices, refer to `references/figures_tables.md`.

**When to Use Tables vs. Figures:**
- **Tables**: Precise numerical data, complex datasets, multiple variables requiring exact values
- **Figures**: Trends, patterns, relationships, comparisons best understood visually

**Design Principles:**
- Make each table/figure self-explanatory with complete captions
- Use consistent formatting and terminology across all display items
- Label all axes, columns, and rows with units
- Include sample sizes (n) and statistical annotations
- Follow the "one table/figure per 1000 words" guideline
- Avoid duplicating information between text, tables, and figures

**Common Figure Types:**
- Bar graphs: Comparing discrete categories
- Line graphs: Showing trends over time
- Scatterplots: Displaying correlations
- Box plots: Showing distributions and outliers
- Heatmaps: Visualizing matrices and patterns

### 5. Reporting Guidelines by Study Type

Ensure completeness and transparency by following established reporting standards. For comprehensive guideline details, refer to `references/reporting_guidelines.md`.

**Key Guidelines:**
- **CONSORT**: Randomized controlled trials
- **STROBE**: Observational studies (cohort, case-control, cross-sectional)
- **PRISMA**: Systematic reviews and meta-analyses
- **STARD**: Diagnostic accuracy studies
- **TRIPOD**: Prediction model studies
- **ARRIVE**: Animal research
- **CARE**: Case reports
- **SQUIRE**: Quality improvement studies
- **SPIRIT**: Study protocols for clinical trials
- **CHEERS**: Economic evaluations

Each guideline provides checklists ensuring all critical methodological elements are reported.

### 6. Writing Principles and Style

Apply fundamental scientific writing principles. For detailed guidance, refer to `references/writing_principles.md`.

**Clarity**:
- Use precise, unambiguous language
- Define technical terms and abbreviations at first use
- Maintain logical flow within and between paragraphs
- Use active voice when appropriate for clarity

**Conciseness**:
- Eliminate redundant words and phrases
- Favor shorter sentences (15-20 words average)
- Remove unnecessary qualifiers
- Respect word limits strictly

**Accuracy**:
- Report exact values with appropriate precision
- Use consistent terminology throughout
- Distinguish between observations and interpretations
- Acknowledge uncertainty appropriately

**Objectivity**:
- Present results without bias
- Avoid overstating findings or implications
- Acknowledge conflicting evidence
- Maintain professional, neutral tone

### 7. Writing Process: From Outline to Full Paragraphs

**CRITICAL: Always write in full paragraphs, never submit bullet points in scientific papers.**

Scientific papers must be written in complete, flowing prose. Use this two-stage approach for effective writing:

**Stage 1: Create Section Outlines with Key Points**

When starting a new section:
1. Use the research-lookup skill to gather relevant literature and data
2. Create a structured outline with bullet points marking:
   - Main arguments or findings to present
   - Key studies to cite
   - Data points and statistics to include
   - Logical flow and organization
3. These bullet points serve as scaffolding—they are NOT the final manuscript

**Example outline (Introduction section):**
```
- Background: AI in drug discovery gaining traction
  * Cite recent reviews (Smith 2023, Jones 2024)
  * Traditional methods are slow and expensive
- Gap: Limited application to rare diseases
  * Only 2 prior studies (Lee 2022, Chen 2023)
  * Small datasets remain a challenge
- Our approach: Transfer learning from common diseases
  * Novel architecture combining X and Y
- Study objectives: Validate on 3 rare disease datasets
```

**Stage 2: Convert Key Points to Full Paragraphs**

Once the outline is complete, expand each bullet point into proper prose:

1. **Transform bullet points into complete sentences** with subjects, verbs, and objects
2. **Add transitions** between sentences and ideas (however, moreover, in contrast, subsequently)
3. **Integrate citations naturally** within sentences, not as lists
4. **Expand with context and explanation** that bullet points omit
5. **Ensure logical flow** from one sentence to the next within each paragraph
6. **Vary sentence structure** to maintain reader engagement

**Example conversion to prose:**

```
Artificial intelligence approaches have gained significant traction in drug discovery
pipelines over the past decade (Smith, 2023; Jones, 2024). While these computational
methods show promise for accelerating the identification of therapeutic candidates,
traditional experimental approaches remain slow and resource-intensive, often requiring
years of laboratory work and substantial financial investment. However, the application
of AI to rare diseases has been limited, with only two prior studies demonstrating
proof-of-concept results (Lee, 2022; Chen, 2023). The primary obstacle has been the
scarcity of training data for conditions affecting small patient populations.

To address this challenge, we developed a transfer learning approach that leverages
knowledge from well-characterized common diseases to predict therapeutic targets for
rare conditions. Our novel neural architecture combines convolutional layers for
molecular feature extraction with attention mechanisms for protein-ligand interaction
modeling. The objective of this study was to validate our approach across three
independent rare disease datasets, assessing both predictive accuracy and biological
interpretability of the results.
```

**Key Differences Between Outlines and Final Text:**

| Outline (Planning Stage) | Final Manuscript |
|--------------------------|------------------|
| Bullet points and fragments | Complete sentences and paragraphs |
| Telegraphic notes | Full explanations with context |
| List of citations | Citations integrated into prose |
| Abbreviated ideas | Developed arguments with transitions |
| For your eyes only | For publication and peer review |

**Common Mistakes to Avoid:**

- ❌ **Never** leave bullet points in the final manuscript
- ❌ **Never** submit lists where paragraphs should be
- ❌ **Don't** use numbered or bulleted lists in Results or Discussion sections (except for specific cases like study hypotheses or inclusion criteria)
- ❌ **Don't** write sentence fragments or incomplete thoughts
- ✅ **Do** use occasional lists only in Methods (e.g., inclusion/exclusion criteria, materials lists)
- ✅ **Do** ensure every section flows as connected prose
- ✅ **Do** read paragraphs aloud to check for natural flow

**When Lists ARE Acceptable (Limited Cases):**

Lists may appear in scientific papers only in specific contexts:
- **Methods**: Inclusion/exclusion criteria, materials and reagents, participant characteristics
- **Supplementary Materials**: Extended protocols, equipment lists, detailed parameters
- **Never in**: Abstract, Introduction, Results, Discussion, Conclusions

**Abstract Format Rule:**
- ❌ **NEVER** use labeled sections (Background:, Methods:, Results:, Conclusions:)
- ✅ **ALWAYS** write as flowing paragraph(s) with natural transitions
- Exception: Only use structured format if journal explicitly requires it in author guidelines

**Integration with Research Lookup:**

The research-lookup skill is essential for Stage 1 (creating outlines):
1. Search for relevant papers using research-lookup
2. Extract key findings, methods, and data
3. Organize findings as bullet points in your outline
4. Then convert the outline to full paragraphs in Stage 2

This two-stage process ensures you:
- Gather and organize information systematically
- Create logical structure before writing
- Produce polished, publication-ready prose
- Maintain focus on the narrative flow

### 8. Professional Report Formatting (Non-Journal Documents)

For research reports, technical reports, white papers, and other professional documents that are NOT journal manuscripts, use the `scientific_report.sty` LaTeX style package for a polished, professional appearance.

**When to Use Professional Report Formatting:**
- Research reports and technical reports
- White papers and policy briefs
- Grant reports and progress reports
- Industry reports and technical documentation
- Internal research summaries
- Feasibility studies and project deliverables

**When NOT to Use (Use Venue-Specific Formatting Instead):**
- Journal manuscripts → Use `venue-templates` skill
- Conference papers → Use `venue-templates` skill
- Academic theses → Use institutional templates

**The `scientific_report.sty` Style Package Provides:**

| Feature | Description |
|---------|-------------|
| Typography | Helvetica font family for modern, professional appearance |
| Color Scheme | Professional blues, greens, and accent colors |
| Box Environments | Colored boxes for key findings, methods, recommendations, limitations |
| Tables | Alternating row colors, professional headers |
| Figures | Consistent caption formatting |
| Scientific Commands | Shortcuts for p-values, effect sizes, confidence intervals |

**Box Environments for Content Organization:**

```latex
% Key findings (blue) - for major discoveries
\begin{keyfindings}[Title]
Content with key findings and statistics.
\end{keyfindings}

% Methodology (green) - for methods highlights
\begin{methodology}[Study Design]
Description of methods and procedures.
\end{methodology}

% Recommendations (purple) - for action items
\begin{recommendations}[Clinical Implications]
\begin{enumerate}
    \item Specific recommendation 1
    \item Specific recommendation 2
\end{enumerate}
\end{recommendations}

% Limitations (orange) - for caveats and cautions
\begin{limitations}[Study Limitations]
Description of limitations and their implications.
\end{limitations}
```

**Professional Table Formatting:**

```latex
\begin{table}[htbp]
\centering
\caption{Results Summary}
\begin{tabular}{@{}lccc@{}}
\toprule
\textbf{Variable} & \textbf{Treatment} & \textbf{Control} & \textbf{p} \\
\midrule
Outcome 1 & \meansd{42.5}{8.3} & \meansd{35.2}{7.9} & <.001\sigthree \\
\rowcolor{tablealt} Outcome 2 & \meansd{3.8}{1.2} & \meansd{3.1}{1.1} & .012\sigone \\
Outcome 3 & \meansd{18.2}{4.5} & \meansd{17.8}{4.2} & .58\signs \\
\bottomrule
\end{tabular}

{\small \siglegend}
\end{table}
```

**Scientific Notation Commands:**

| Command | Output | Purpose |
|---------|--------|---------|
| `\pvalue{0.023}` | *p* = 0.023 | P-values |
| `\psig{< 0.001}` | ***p* = < 0.001** | Significant p-values (bold) |
| `\CI{0.45}{0.72}` | 95% CI [0.45, 0.72] | Confidence intervals |
| `\effectsize{d}{0.75}` | d = 0.75 | Effect sizes |
| `\samplesize{250}` | *n* = 250 | Sample sizes |
| `\meansd{42.5}{8.3}` | 42.5 ± 8.3 | Mean with SD |
| `\sigone`, `\sigtwo`, `\sigthree` | *, **, *** | Significance stars |

**Getting Started:**

```latex
\documentclass[11pt,letterpaper]{report}
\usepackage{scientific_report}

\begin{document}
\makereporttitle
    {Report Title}
    {Subtitle}
    {Author Name}
    {Institution}
    {Date}

% Your content with professional formatting
\end{document}
```

**Compilation**: Use XeLaTeX or LuaLaTeX for proper Helvetica font rendering:
```bash
xelatex report.tex
```

For complete documentation, refer to:
- `assets/scientific_report.sty`: The style package
- `assets/scientific_report_template.tex`: Complete template example
- `assets/REPORT_FORMATTING_GUIDE.md`: Quick reference guide
- `references/professional_report_formatting.md`: Comprehensive formatting guide

### 9. Journal-Specific Formatting

Adapt manuscripts to journal requirements:
- Follow author guidelines for structure, length, and format
- Apply journal-specific citation styles
- Meet figure/table specifications (resolution, file formats, dimensions)
- Include required statements (funding, conflicts of interest, data availability, ethical approval)
- Adhere to word limits for each section
- Format according to template requirements when provided

### 10. Field-Specific Language and Terminology

Adapt language, terminology, and conventions to match the specific scientific discipline. Each field has established vocabulary, preferred phrasings, and domain-specific conventions that signal expertise and ensure clarity for the target audience.

**Identify Field-Specific Linguistic Conventions:**
- Review terminology used in recent high-impact papers in the target journal
- Note field-specific abbreviations, units, and notation systems
- Identify preferred terms (e.g., "participants" vs. "subjects," "compound" vs. "drug," "specimens" vs. "samples")
- Observe how methods, organisms, or techniques are typically described

**Biomedical and Clinical Sciences:**
- Use precise anatomical and clinical terminology (e.g., "myocardial infarction" not "heart attack" in formal writing)
- Follow standardized disease nomenclature (ICD, DSM, SNOMED-CT)
- Specify drug names using generic names first, brand names in parentheses if needed
- Use "patients" for clinical studies, "participants" for community-based research
- Follow Human Genome Variation Society (HGVS) nomenclature for genetic variants
- Report lab values with standard units (SI units in most international journals)

**Molecular Biology and Genetics:**
- Use italics for gene symbols (e.g., *TP53*), regular font for proteins (e.g., p53)
- Follow species-specific gene nomenclature (uppercase for human: *BRCA1*; sentence case for mouse: *Brca1*)
- Specify organism names in full at first mention, then use accepted abbreviations (e.g., *Escherichia coli*, then *E. coli*)
- Use standard genetic notation (e.g., +/+, +/-, -/- for genotypes)
- Employ established terminology for molecular techniques (e.g., "quantitative PCR" or "qPCR," not "real-time PCR")

**Chemistry and Pharmaceutical Sciences:**
- Follow IUPAC nomenclature for chemical compounds
- Use systematic names for novel compounds, common names for well-known substances
- Specify chemical structures using standard notation (e.g., SMILES, InChI for databases)
- Report concentrations with appropriate units (mM, μM, nM, or % w/v, v/v)
- Describe synthesis routes using accepted reaction nomenclature
- Use terms like "bioavailability," "pharmacokinetics," "IC50" consistently with field definitions

**Ecology and Environmental Sciences:**
- Use binomial nomenclature for species (italicized: *Homo sapiens*)
- Specify taxonomic authorities at first species mention when relevant
- Employ standardized habitat and ecosystem classifications
- Use consistent terminology for ecological metrics (e.g., "species richness," "Shannon diversity index")
- Describe sampling methods with field-standard terms (e.g., "transect," "quadrat," "mark-recapture")

**Physics and Engineering:**
- Follow SI units consistently unless field conventions dictate otherwise
- Use standard notation for physical quantities (scalars vs. vectors, tensors)
- Employ established terminology for phenomena (e.g., "quantum entanglement," "laminar flow")
- Specify equipment with model numbers and manufacturers when relevant
- Use mathematical notation consistent with field standards (e.g., ℏ for reduced Planck constant)

**Neuroscience:**
- Use standardized brain region nomenclature (e.g., refer to atlases like Allen Brain Atlas)
- Specify coordinates for brain regions using established stereotaxic systems
- Follow conventions for neural terminology (e.g., "action potential" not "spike" in formal writing)
- Use "neural activity," "neuronal firing," "brain activation" appropriately based on measurement method
- Describe recording techniques with proper specificity (e.g., "whole-cell patch clamp," "extracellular recording")

**Social and Behavioral Sciences:**
- Use person-first language when appropriate (e.g., "people with schizophrenia" not "schizophrenics")
- Employ standardized psychological constructs and validated assessment names
- Follow APA guidelines for reducing bias in language
- Specify theoretical frameworks using established terminology
- Use "participants" rather than "subjects" for human research

**General Principles:**

**Match Audience Expertise:**
- For specialized journals: Use field-specific terminology freely, define only highly specialized or novel terms
- For broad-impact journals (e.g., *Nature*, *Science*): Define more technical terms, provide context for specialized concepts
- For interdisciplinary audiences: Balance precision with accessibility, define terms at first use

**Define Technical Terms Strategically:**
- Define abbreviations at first use: "messenger RNA (mRNA)"
- Provide brief explanations for specialized techniques when writing for broader audiences
- Avoid over-defining terms well-known to the target audience (signals unfamiliarity with field)
- Create a glossary if numerous specialized terms are unavoidable

**Maintain Consistency:**
- Use the same term for the same concept throughout (don't alternate between "medication," "drug," and "pharmaceutical")
- Follow a consistent system for abbreviations (decide on "PCR" or "polymerase chain reaction" after first definition)
- Apply the same nomenclature system throughout (especially for genes, species, chemicals)

**Avoid Field Mixing Errors:**
- Don't use clinical terminology for basic science (e.g., don't call mice "patients")
- Avoid colloquialisms or overly general terms in place of precise field terminology
- Don't import terminology from adjacent fields without ensuring proper usage

**Verify Terminology Usage:**
- Consult field-specific style guides and nomenclature resources
- Check how terms are used in recent papers from the target journal
- Use domain-specific databases and ontologies (e.g., Gene Ontology, MeSH terms)
- When uncertain, cite a key reference that establishes terminology

### 11. Common Pitfalls to Avoid

**Top Rejection Reasons:**
1. Inappropriate, incomplete, or insufficiently described statistics
2. Over-interpretation of results or unsupported conclusions
3. Poorly described methods affecting reproducibility
4. Small, biased, or inappropriate samples
5. Poor writing quality or difficult-to-follow text
6. Inadequate literature review or context
7. Figures and tables that are unclear or poorly designed
8. Failure to follow reporting guidelines

**Writing Quality Issues:**
- Mixing tenses inappropriately (use past tense for methods/results, present for established facts)
- Excessive jargon or undefined acronyms
- Paragraph breaks that disrupt logical flow
- Missing transitions between sections
- Inconsistent notation or terminology

## Workflow for Manuscript Development

**Stage 1: Planning**
1. Identify target journal and review author guidelines
2. Determine applicable reporting guideline (CONSORT, STROBE, etc.)
3. Outline manuscript structure (usually IMRAD)
4. Plan figures and tables as the backbone of the paper

**Stage 2: Drafting** (Use two-stage writing process for each section)
1. Start with figures and tables (the core data story)
2. For each section below, follow the two-stage process:
   - **First**: Create outline with bullet points using research-lookup
   - **Second**: Convert bullet points to full paragraphs with flowing prose
3. Write Methods (often easiest to draft first)
4. Draft Results (describing figures/tables objectively)
5. Compose Discussion (interpreting findings)
6. Write Introduction (setting up the research question)
7. Craft Abstract (synthesizing the complete story)
8. Create Title (concise and descriptive)

**Remember**: Bullet points are for planning only—the final manuscript must be in complete paragraphs.

**Stage 3: Revision**
1. Check logical flow and "red thread" throughout
2. Verify consistency in terminology and notation
3. Ensure figures/tables are self-explanatory
4. Confirm adherence to reporting guidelines
5. Verify all citations are accurate and properly formatted
6. Check word counts for each section
7. Proofread for grammar, spelling, and clarity

**Stage 4: Final Preparation**
1. Format according to journal requirements
2. Prepare supplementary materials
3. Write cover letter highlighting significance
4. Complete submission checklists
5. Gather all required statements and forms

## Integration with Other Scientific Skills

This skill works effectively with:
- **Data analysis skills**: For generating results to report
- **Statistical analysis**: For determining appropriate statistical presentations
- **Literature review skills**: For contextualizing research
- **Figure creation tools**: For developing publication-quality visualizations
- **Venue-templates skill**: For venue-specific writing styles and formatting (journal manuscripts)
- **scientific_report.sty**: For professional reports, white papers, and technical documents

### Professional Reports vs. Journal Manuscripts

**Choose the right formatting approach:**

| Document Type | Formatting Approach |
|---------------|---------------------|
| Journal manuscripts | Use `venue-templates` skill |
| Conference papers | Use `venue-templates` skill |
| Research reports | Use `scientific_report.sty` (this skill) |
| White papers | Use `scientific_report.sty` (this skill) |
| Technical reports | Use `scientific_report.sty` (this skill) |
| Grant reports | Use `scientific_report.sty` (this skill) |

### Venue-Specific Writing Styles

**Before writing for a specific venue, consult the venue-templates skill for writing style guides:**

Different venues have dramatically different writing expectations:
- **Nature/Science**: Accessible, story-driven, broad significance
- **Cell Press**: Mechanistic depth, graphical abstracts, Highlights
- **Medical journals (NEJM, Lancet)**: Structured abstracts, evidence language
- **ML conferences (NeurIPS, ICML)**: Contribution bullets, ablation studies
- **CS conferences (CHI, ACL)**: Field-specific conventions

The venue-templates skill provides:
- `venue_writing_styles.md`: Master style comparison
- Venue-specific guides: `nature_science_style.md`, `cell_press_style.md`, `medical_journal_styles.md`, `ml_conference_style.md`, `cs_conference_style.md`
- `reviewer_expectations.md`: What reviewers look for at each venue
- Writing examples in `assets/examples/`

**Workflow**: First use this skill for general scientific writing principles (IMRAD, clarity, citations), then consult venue-templates for venue-specific style adaptation.

## References

This skill includes comprehensive reference files covering specific aspects of scientific writing:

- `references/imrad_structure.md`: Detailed guide to IMRAD format and section-specific content
- `references/citation_styles.md`: Complete citation style guides (APA, AMA, Vancouver, Chicago, IEEE)
- `references/figures_tables.md`: Best practices for creating effective data visualizations
- `references/reporting_guidelines.md`: Study-specific reporting standards and checklists
- `references/writing_principles.md`: Core principles of effective scientific communication
- `references/professional_report_formatting.md`: Guide to professional report styling with `scientific_report.sty`

## Assets

This skill includes LaTeX style packages and templates for professional report formatting:

- `assets/scientific_report.sty`: Professional LaTeX style package with Helvetica fonts, colored boxes, and attractive tables
- `assets/scientific_report_template.tex`: Complete report template demonstrating all style features
- `assets/REPORT_FORMATTING_GUIDE.md`: Quick reference guide for the style package

**Key Features of `scientific_report.sty`:**
- Helvetica font family for modern, professional appearance
- Professional color scheme (blues, greens, oranges, purples)
- Box environments: `keyfindings`, `methodology`, `resultsbox`, `recommendations`, `limitations`, `criticalnotice`, `definition`, `executivesummary`, `hypothesis`
- Tables with alternating row colors and professional headers
- Scientific notation commands for p-values, effect sizes, confidence intervals
- Professional headers and footers

**For venue-specific writing styles** (tone, voice, abstract format, reviewer expectations), see the **venue-templates** skill which provides comprehensive style guides for Nature/Science, Cell Press, medical journals, ML conferences, and CS conferences.

Load these references as needed when working on specific aspects of scientific writing.

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.