Installation

Open Claude Code and run this command:

/plugin install grammarly-pack@claude-code-plugins-plus

Use --global to install for all projects, or --project for current project only.

Skills (24)

grammarly-ci-integration SKILL.md View full skill →

Configure Grammarly CI/CD integration with GitHub Actions and testing.

ReadWriteEditBash(gh:*)

Grammarly CI Integration

Overview

Set up CI/CD for Grammarly text analysis integrations: run unit tests with mocked grammar check and suggestion responses on every PR, validate live API connectivity for text scoring on merge to main. Grammarly's Text API provides writing quality scores, grammar corrections, and tone detection, so CI pipelines verify content quality gates, documentation linting, and automated writing feedback workflows.

GitHub Actions Workflow


# .github/workflows/grammarly-ci.yml
name: Grammarly CI
on:
  pull_request:
    paths: ['src/**', 'docs/**', 'tests/**']
  push:
    branches: [main]

jobs:
  unit-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npm test -- --reporter=verbose

  integration-tests:
    if: github.ref == 'refs/heads/main'
    needs: unit-tests
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npm run test:integration
        env:
          GRAMMARLY_CLIENT_ID: ${{ secrets.GRAMMARLY_CLIENT_ID }}
          GRAMMARLY_CLIENT_SECRET: ${{ secrets.GRAMMARLY_CLIENT_SECRET }}

Mock-Based Unit Tests


// tests/grammarly-service.test.ts
import { describe, it, expect, vi } from 'vitest';
import { checkDocumentation } from '../src/grammarly-service';

vi.mock('../src/grammarly-client', () => ({
  GrammarlyClient: vi.fn().mockImplementation(() => ({
    checkText: vi.fn().mockResolvedValue({
      overall_score: 87,
      alerts: [
        { type: 'grammar', message: 'Subject-verb disagreement', offset: 12, length: 5, replacements: ['are'] },
        { type: 'clarity', message: 'Consider simplifying', offset: 45, length: 20, replacements: ['use'] },
      ],
      tone: { formal: 0.8, confident: 0.7 },
    }),
    getSuggestions: vi.fn().mockResolvedValue({
      suggestions: [{ text: 'Rephrase for clarity', category: 'engagement' }],
    }),
  })),
}));

describe('Grammarly Service', () => {
  it('checks documentation quality and returns score', async () => {
    const result = await checkDocumentation('The data is ready for review.');
    expect(result.overall_score).toBeGreaterThan(80);
    expect(result.alerts).toHaveLength(2);
  });
});

Integration Tests


// tests/integration/grammarly.integration.test.ts
import { describe, it, expect } from 'vitest';

const hasCredentials = !!process.env.GRAMMARLY_CLIENT_ID;

describe.skipIf(!hasCredentials)('Grammarly Live API', () => {
  it('analyzes text via


                
                  
                  
                  grammarly-common-errors
                  SKILL.md
                  View full skill →
                
                
                  Diagnose and fix Grammarly common errors and exceptions.
                  
                      ReadGrepBash(curl:*)
                    
                
                
                  Grammarly Common Errors
Error Reference
400 Bad Request — Text Too Short
Cause: Text has fewer than 30 words.
Fix: Ensure minimum 30 words. Pad short texts with context if needed.
401 Unauthorized
Cause: Token expired or invalid.
Fix: Re-authenticate with client credentials grant.
413 Payload Too Large
Cause: Text exceeds 100,000 characters or 4 MB.
Fix: Split into chunks using paragraph boundaries. See grammarly-sdk-patterns for chunking function.
429 Too Many Requests
Cause: Rate limit exceeded.
Fix: Implement exponential backoff. See grammarly-rate-limits.
Plagiarism Check Stuck on "pending"
Cause: Large document processing or service delay.
Fix: Poll every 3-5 seconds, timeout after 90 seconds.
AI Detection — Inconsistent Scores
Cause: Short text produces unreliable results.
Fix: AI detection works best on 200+ words. Scores on short text are less reliable.
Quick Diagnostics

# Test API connectivity
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $GRAMMARLY_ACCESS_TOKEN" \
  https://api.grammarly.com/ecosystem/api/v2/scores

# Test with sample text
curl -X POST https://api.grammarly.com/ecosystem/api/v2/scores \
  -H "Authorization: Bearer $GRAMMARLY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "This is a test sentence that has more than thirty words so that the API will accept it and return a valid writing score for our diagnostic purposes."}' | python3 -m json.tool

Resources

Grammarly API Support

Next Steps
For debugging tools, see grammarly-debug-bundle.


                
                  
                  
                  grammarly-core-workflow-a
                  SKILL.md
                  View full skill →
                
                
                  Execute Grammarly primary workflow: Core Workflow A.
                  
                      ReadWriteEditBash(npm:*)Grep
                    
                
                
                  Grammarly Writing Score Integration
Overview
Integrate Grammarly's Writing Score API into your application. Score documents, track writing quality over time, and provide feedback. The API evaluates text across four dimensions: engagement, correctness, clarity, and tone.
Prerequisites

Completed grammarly-install-auth setup
Understanding of score dimensions

Instructions
Step 1: Typed Score Client

// src/grammarly/scoring.ts
interface WritingScore {
  overallScore: number;
  engagement: number;
  correctness: number;
  clarity: number;
  tone: number;
}

interface ScoreRequest {
  text: string;
  audienceType?: 'general' | 'knowledgeable' | 'expert';
  domain?: 'academic' | 'business' | 'general' | 'email' | 'casual';
}

async function scoreDocument(req: ScoreRequest, token: string): Promise<WritingScore> {
  const response = await fetch('https://api.grammarly.com/ecosystem/api/v2/scores', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
    body: JSON.stringify(req),
  });
  if (!response.ok) throw new Error(`Grammarly API ${response.status}: ${await response.text()}`);
  return response.json();
}

Step 2: Batch Document Scoring

async function batchScore(documents: string[], token: string): Promise<WritingScore[]> {
  const results: WritingScore[] = [];
  for (const doc of documents) {
    if (doc.split(/\s+/).length < 30) {
      console.warn('Skipping: minimum 30 words required');
      continue;
    }
    const score = await scoreDocument({ text: doc }, token);
    results.push(score);
    await new Promise(r => setTimeout(r, 500)); // Rate limit buffer
  }
  return results;
}

Step 3: Quality Threshold Enforcement

interface QualityGate {
  minOverall: number;
  minCorrectness: number;
  minClarity: number;
}

function checkQualityGate(score: WritingScore, gate: QualityGate): { passed: boolean; issues: string[] } {
  const issues: string[] = [];
  if (score.overallScore < gate.minOverall) issues.push(`Overall ${score.overallScore} < ${gate.minOverall}`);
  if (score.correctness < gate.minCorrectness) issues.push(`Correctness ${score.correctness} < ${gate.minCorrectness}`);
  if (score.clarity < gate.minClarity) issues.push(`Clarity ${score.clarity} < ${gate.minClarity}`);
  return { passed: issues.length === 0, issues };
}

// Usage: enforce quality before publishing
const score = await scoreDocument({ text: blogPost }, token);
const gate = checkQualityGate(score, { minOverall: 80, minCorrectness: 90, minClarity: 75 });
if (!gate.passed) console.error('Quality gate failed:', gate.issues);

                

              

                
                  
                  
                  grammarly-core-workflow-b
                  SKILL.md
                  View full skill →
                
                
                  Execute Grammarly secondary workflow: Core Workflow B.
                  
                      ReadWriteEditBash(npm:*)Grep
                    
                
                
                  Grammarly AI & Plagiarism Detection
Overview
Detect AI-generated content and check for plagiarism using Grammarly's detection APIs. AI Detection returns a score (0-100) indicating likelihood of AI generation. Plagiarism Detection compares text against billions of web pages and academic papers.
Instructions
Step 1: AI Detection Pipeline

interface AIDetectionResult { score: number; status: string; }

async function detectAI(text: string, token: string): Promise<AIDetectionResult> {
  const response = await fetch('https://api.grammarly.com/ecosystem/api/v1/ai-detection', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ text }),
  });
  return response.json();
}

// Batch check multiple documents
async function batchAIDetection(documents: Array<{ id: string; text: string }>, token: string) {
  const results = [];
  for (const doc of documents) {
    const result = await detectAI(doc.text, token);
    results.push({ ...doc, aiScore: result.score, isLikelyAI: result.score > 70 });
    await new Promise(r => setTimeout(r, 500));
  }
  return results;
}

Step 2: Plagiarism Detection (Async)

async function checkPlagiarism(text: string, token: string) {
  // Create request
  const createRes = await fetch('https://api.grammarly.com/ecosystem/api/v1/plagiarism', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ text }),
  });
  const { id } = await createRes.json();

  // Poll for results (async processing)
  for (let i = 0; i < 30; i++) {
    await new Promise(r => setTimeout(r, 3000));
    const statusRes = await fetch(`https://api.grammarly.com/ecosystem/api/v1/plagiarism/${id}`, {
      headers: { 'Authorization': `Bearer ${token}` },
    });
    const result = await statusRes.json();
    if (result.status !== 'pending') return result;
  }
  throw new Error('Plagiarism check timed out');
}

Step 3: Combined Content Quality Pipeline

async function fullContentAudit(text: string, token: string) {
  const [score, ai, plagiarism] = await Promise.all([
    scoreDocument({ text }, token),
    detectAI(text, token),
    checkPlagiarism(text, token),
  ]);

  return {
    writingScore: score.overallScore,
    correctness: score.correctness,
    clarity: score.clarity,
    aiLikelihood: ai.score,
    plagiarismScore: plagiarism.score,
    plagiarismMatches: plagiarism.matches?.length || 0,
    passed: score.overallScore >= 70 && ai.score < 50 && plagiarism.score < 20,
  };
}

Error Handling

Error
Ca
                
              
                
                  
                  
                  grammarly-cost-tuning
                  SKILL.md
                  View full skill →
                
                
                  Optimize Grammarly costs through tier selection, sampling, and usage monitoring.
                  
                      ReadGrep
                    
                
                
                  Grammarly Cost Tuning
Overview
Grammarly enterprise pricing is per-seat with API costs driven by text check request volume and document length. Each grammar check, tone analysis, and plagiarism scan consumes API quota proportional to word count. For organizations processing thousands of documents daily, unchecked API usage — especially on long documents or duplicate content — creates substantial cost overrun. Implementing validation gates, result caching, and sample-based scoring reduces API spend by 40-60% without sacrificing quality coverage.
Cost Breakdown

Component
Cost Driver
Optimization


Seat licenses
Per-user/month enterprise pricing
Audit active seats quarterly; remove inactive users


Text check requests
Per-call API quota on grammar/tone checks
Cache results for identical text; deduplicate requests


Document length
API cost scales with word count per request
Chunk documents over 10K words; skip boilerplate sections


Plagiarism scans
Higher-cost endpoint for originality checks
Run only on final drafts, not every revision


AI rewrite suggestions
Premium feature with per-request cost
Batch rewrites; limit to flagged passages only


API Call Reduction

class GrammarlyCostGate {
  private resultCache = new Map<string, any>();

  shouldCheck(text: string): boolean {
    const words = text.split(/\s+/).length;
    return words >= 30 && words <= 50_000; // Skip too-short; chunk too-long
  }

  async checkWithCache(text: string, checkFn: (t: string) => Promise<any>): Promise<any> {
    const hash = this.hashText(text);
    if (this.resultCache.has(hash)) return this.resultCache.get(hash);
    const result = await checkFn(text);
    this.resultCache.set(hash, result);
    return result;
  }

  sampleDocuments(documents: string[], rate = 0.2): string[] {
    // For bulk content audits, score a representative sample
    return documents.filter(() => Math.random() < rate);
  }

  private hashText(text: string): string {
    return text.slice(0, 200) + '|' + text.length;
  }
}

Usage Monitoring

class GrammarlyUsageMonitor {
  private daily = { score: 0, ai: 0, plagiarism: 0 };
  private budgets = { score: 5000, ai: 1000, plagiarism: 200 };

  record(type: 'score' | 'ai' | 'plagiarism'): void {
    this.daily[type]++;
    const utilization = (this.daily[type] / this.budgets[type]) * 100;
    if (utilization > 80) {
      console.warn(`Grammarly ${type} budget ${utilization.toFixed(0)}% used: ${this.daily[type]}/${this.budgets[type]}`);
    }
  }

  getReport(): Record<string, { us

                

              

                
                  
                  
                  grammarly-data-handling
                  SKILL.md
                  View full skill →
                
                
                  Implement Grammarly data handling patterns for document processing.
                  
                      ReadWriteEdit
                    
                
                
                  Grammarly Data Handling
Overview
Handle large documents, text chunking, and data pipelines for Grammarly API. The API accepts max 100,000 characters (4 MB) with a minimum of 30 words.
Instructions
Step 1: Text Chunking

function chunkText(text: string, maxChars = 90000): string[] {
  if (text.length <= maxChars) return [text];
  const paragraphs = text.split('\n\n');
  const chunks: string[] = [];
  let current = '';
  for (const p of paragraphs) {
    if ((current + '\n\n' + p).length > maxChars && current) {
      chunks.push(current);
      current = p;
    } else {
      current = current ? current + '\n\n' + p : p;
    }
  }
  if (current) chunks.push(current);
  return chunks;
}

Step 2: Aggregate Scores Across Chunks

function aggregateScores(scores: any[]): any {
  const avg = (arr: number[]) => arr.reduce((a, b) => a + b, 0) / arr.length;
  return {
    overallScore: Math.round(avg(scores.map(s => s.overallScore))),
    correctness: Math.round(avg(scores.map(s => s.correctness))),
    clarity: Math.round(avg(scores.map(s => s.clarity))),
    engagement: Math.round(avg(scores.map(s => s.engagement))),
    tone: Math.round(avg(scores.map(s => s.tone))),
    chunkCount: scores.length,
  };
}

Step 3: File Processing Pipeline

import fs from 'fs';

async function scoreFile(filePath: string, token: string) {
  const text = fs.readFileSync(filePath, 'utf-8');
  const chunks = chunkText(text);
  const scores = [];
  for (const chunk of chunks) {
    if (chunk.split(/\s+/).length >= 30) {
      scores.push(await grammarlyClient.score(chunk));
    }
  }
  return aggregateScores(scores);
}

Resources

Writing Score API

                
              

                
                  
                  
                  grammarly-debug-bundle
                  SKILL.md
                  View full skill →
                
                
                  Collect Grammarly debug evidence for support tickets and troubleshooting.
                  
                      ReadBash(grep:*)Bash(curl:*)Bash(tar:*)Grep
                    
                
                
                  Grammarly Debug Bundle
Overview
Collect Grammarly API connectivity status, text analysis response quality, authentication state, and rate limit usage into a single diagnostic archive. This bundle helps troubleshoot text check failures, missing suggestions, OAuth token expiration, and API response latency.
Debug Collection Script

#!/bin/bash
set -euo pipefail
BUNDLE="debug-grammarly-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE"

# Environment check
echo "=== Grammarly Debug Bundle ===" | tee "$BUNDLE/summary.txt"
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$BUNDLE/summary.txt"
echo "GRAMMARLY_API_KEY: ${GRAMMARLY_API_KEY:+[SET]}" >> "$BUNDLE/summary.txt"
echo "GRAMMARLY_CLIENT_ID: ${GRAMMARLY_CLIENT_ID:+[SET]}" >> "$BUNDLE/summary.txt"

# API connectivity — text check endpoint
HTTP=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer ${GRAMMARLY_API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST https://api.grammarly.com/v1/check \
  -d '{"text": "This are a diagnostic test sentence with intentional grammar errors to verify the API returns suggestions."}' \
  2>/dev/null || echo "000")
echo "API Status: HTTP $HTTP" >> "$BUNDLE/summary.txt"

# Full text check response
curl -s -H "Authorization: Bearer ${GRAMMARLY_API_KEY}" \
  -H "Content-Type: application/json" -X POST https://api.grammarly.com/v1/check \
  -d '{"text": "This are a diagnostic test sentence with intentional grammar errors to verify the API returns suggestions."}' \
  > "$BUNDLE/text-check.json" 2>&1 || true

# Account info and rate limit headers
curl -s -D "$BUNDLE/rate-headers.txt" -H "Authorization: Bearer ${GRAMMARLY_API_KEY}" \
  https://api.grammarly.com/v1/account > "$BUNDLE/account.json" 2>&1 || true

tar -czf "$BUNDLE.tar.gz" "$BUNDLE" && rm -rf "$BUNDLE"
echo "Bundle: $BUNDLE.tar.gz"

Analyzing the Bundle

tar -xzf debug-grammarly-*.tar.gz
cat debug-grammarly-*/summary.txt                 # Auth + API status
jq '.alerts | length' debug-grammarly-*/text-check.json  # Suggestion count
jq '.alerts[] | {type, text}' debug-grammarly-*/text-check.json  # Suggestion details
grep -i "ratelimit\|retry" debug-grammarly-*/rate-headers.txt

Common Issues

Symptom
Check in Bundle
Fix


API returns 401
summary.txt shows HTTP 401
Refresh OAuth token or regenerate API key in Grammarly Developer Hub


Zero suggest
                
              
                
                  
                  
                  grammarly-deploy-integration
                  SKILL.md
                  View full skill →
                
                
                  Deploy Grammarly integrations to Vercel, Fly.
                  
                      ReadWriteEditBash(vercel:*)Bash(fly:*)Bash(gcloud:*)
                    
                
                
                  Grammarly Deploy Integration
Overview
Deploy a containerized Grammarly writing assistant integration service with Docker. This skill covers building a production image that connects to the Grammarly Text API for checking grammar, clarity, and tone across submitted text. Includes environment configuration for OAuth client credentials, health checks that verify API token exchange and text analysis endpoints, and rolling update strategies for zero-downtime deployments serving real-time writing feedback.
Docker Configuration

FROM node:20-slim AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY tsconfig.json ./
COPY src/ ./src/
RUN npm run build

FROM node:20-slim
RUN addgroup --system app && adduser --system --ingroup app app
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package*.json ./
USER app
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1
CMD ["node", "dist/index.js"]

Environment Variables

export GRAMMARLY_CLIENT_ID="client_xxxxxxxxxxxx"
export GRAMMARLY_CLIENT_SECRET="secret_xxxxxxxxxxxx"
export GRAMMARLY_BASE_URL="https://api.grammarly.com/ecosystem/api"
export LOG_LEVEL="info"
export PORT="3000"
export NODE_ENV="production"

Health Check Endpoint

import express from 'express';

const app = express();

app.get('/health', async (req, res) => {
  try {
    const tokenRes = await fetch(`${process.env.GRAMMARLY_BASE_URL}/v1/oauth/token`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({
        grant_type: 'client_credentials',
        client_id: process.env.GRAMMARLY_CLIENT_ID!,
        client_secret: process.env.GRAMMARLY_CLIENT_SECRET!,
      }),
    });
    if (!tokenRes.ok) throw new Error(`Grammarly OAuth returned ${tokenRes.status}`);
    res.json({ status: 'healthy', service: 'grammarly-integration', timestamp: new Date().toISOString() });
  } catch (error) {
    res.status(503).json({ status: 'unhealthy', error: (error as Error).message });
  }
});

Deployment Steps
Step 1: Build

docker build -t grammarly-integration:latest .

Step 2: Run

docker run -d --name grammarly-integration \
  -p 3000:3000 \
  -e GRAMMARLY_CLIENT_ID -e GRAMMARLY_CLIENT_SECRET -e GRAMMARLY_BASE_URL \
  grammarly-integration:latest

Step 3: Verify

curl -s http://localhost:3000/health | jq .

Step 4: Rolling Update
                
                  
                  
                  grammarly-enterprise-rbac
                  SKILL.md
                  View full skill →
                
                
                  Configure Grammarly enterprise role-based access control.
                  
                      ReadWriteGrep
                    
                
                
                  Grammarly Enterprise RBAC
Overview
Grammarly enterprise deployments manage writing quality across teams with different access levels. Organization admins control style guides, tone profiles, and brand rules. Team admins assign seats and configure suggestion types (clarity, engagement, delivery). Members write with team defaults while guests get read-only access to shared documents. HIPAA and SOC 2 compliance in regulated industries require audit trails on who accessed which writing suggestions and AI detection results.
Role Hierarchy

Role
Permissions
Scope


Org Admin
Manage billing, SSO config, all style guides, API credentials
Organization-wide


Team Admin
Assign seats, configure suggestion settings, manage style guides
Own team


Member
Write with team settings, access scoring and AI detection APIs
Own team


Guest
View shared documents, read-only style guide access
Invited documents only


API Service
OAuth-scoped access to scoring, AI detection, plagiarism APIs
Per-credential scope


Permission Check

async function checkGrammarlyAccess(userId: string, team: string, scope: string): Promise<boolean> {
  const response = await fetch(`${GRAMMARLY_API}/organizations/${ORG_ID}/permissions`, {
    headers: { Authorization: `Bearer ${GRAMMARLY_OAUTH_TOKEN}`, 'Content-Type': 'application/json' },
  });
  const perms = await response.json();
  const userPerms = perms.members.find((m: any) => m.id === userId);
  if (!userPerms) return false;
  return userPerms.team === team && userPerms.scopes.includes(scope);
}

Role Assignment

async function assignTeamRole(email: string, team: string, role: 'admin' | 'member' | 'guest'): Promise<void> {
  await fetch(`${GRAMMARLY_API}/organizations/${ORG_ID}/teams/${team}/members`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${GRAMMARLY_OAUTH_TOKEN}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ email, role }),
  });
}

async function revokeTeamAccess(email: string, team: string): Promise<void> {
  await fetch(`${GRAMMARLY_API}/organizations/${ORG_ID}/teams/${team}/members/${email}`, {
    method: 'DELETE',
    headers: { Authorization: `Bearer ${GRAMMARLY_OAUTH_TOKEN}` },
  });
}

Audit Logging

interface GrammarlyAuditEntry {
  timestamp: string; userId: string; team: string;
  action: 'score_check' | 'ai_detection' | 'plagiarism_scan' | 'style_guide_edit' | 'seat_change';
  scope: string; docume

                

              

                
                  
                  
                  grammarly-hello-world
                  SKILL.md
                  View full skill →
                
                
                  Create a minimal working Grammarly example.
                  
                      ReadWriteEditBash(npm:*)Bash(curl:*)
                    
                
                
                  Grammarly Hello World
Overview
Score a text document using Grammarly's Writing Score API. Returns an overall score plus sub-scores for engagement, correctness, tone, and clarity.
Prerequisites

Completed grammarly-install-auth setup
Valid access token with scores-api:read scope

Instructions
Step 1: Score a Document

// hello-grammarly.ts
import 'dotenv/config';

const TOKEN = process.env.GRAMMARLY_ACCESS_TOKEN!;

async function scoreText(text: string) {
  const response = await fetch('https://api.grammarly.com/ecosystem/api/v2/scores', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ text }),
  });

  const result = await response.json();
  console.log('Overall Score:', result.overallScore);
  console.log('Engagement:', result.engagement);
  console.log('Correctness:', result.correctness);
  console.log('Clarity:', result.clarity);
  console.log('Tone:', result.tone);
  return result;
}

scoreText('Their going to the store tommorow to buy there supplys for the trip.').catch(console.error);

Step 2: AI Detection

async function detectAI(text: string) {
  const response = await fetch('https://api.grammarly.com/ecosystem/api/v1/ai-detection', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ text }),
  });
  const result = await response.json();
  console.log('AI Score:', result.score); // 0-100, higher = more likely AI
  return result;
}

Step 3: Plagiarism Detection

async function checkPlagiarism(text: string) {
  // Step 1: Create score request
  const createRes = await fetch('https://api.grammarly.com/ecosystem/api/v1/plagiarism', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ text }),
  });
  const { id } = await createRes.json();

  // Step 2: Poll for results
  let result;
  do {
    await new Promise(r => setTimeout(r, 3000));
    const statusRes = await fetch(`https://api.grammarly.com/ecosystem/api/v1/plagiarism/${id}`, {
      headers: { 'Authorization': `Bearer ${TOKEN}` },
    });
    result = await statusRes.json();
  } while (result.status === 'pending');

  console.log('Plagiarism score:', result.score);
  console.log('Matches:', result.matches?.length || 0);
  return result;
}

Step 4: curl Quick Test

curl -X POST https://a

                

              

                
                  
                  
                  grammarly-incident-runbook
                  SKILL.md
                  View full skill →
                
                
                  Follow Grammarly incident response runbook for API outages.
                  
                      ReadBash(curl:*)Grep
                    
                
                
                  Grammarly Incident Runbook
Overview
Incident response procedures for Grammarly writing API integration failures. Covers text check timeouts, suggestion quality degradation, OAuth token failures, and rate limit storms. Grammarly powers real-time writing assistance, so API incidents directly impact user-facing text checking, scoring workflows, and content quality pipelines. Classify severity immediately using the matrix below and follow the corresponding playbook.
Severity Levels

Level
Definition
Response Time
Example


P1 - Critical
Full API outage, all scoring requests fail
15 min
5xx on /v2/scores for all requests


P2 - High
OAuth token failures or sustained timeouts
30 min
All authenticated requests return 401


P3 - Medium
Rate limit storms or elevated latency
2 hours
429 responses, scoring takes 10s+ per request


P4 - Low
Suggestion quality drift or single endpoint issue
8 hours
Scores returning but correctness values seem off


Diagnostic Steps

# Test API health (unauthenticated)
curl -s -o /dev/null -w "HTTP %{http_code}\n" \
  https://api.grammarly.com/ecosystem/api/v2/scores

# Test authenticated scoring
curl -s -w "\nHTTP %{http_code}\n" \
  -H "Authorization: Bearer $GRAMMARLY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST https://api.grammarly.com/ecosystem/api/v2/scores \
  -d '{"text": "Test sentence for Grammarly API diagnostic health check."}'

# Check OAuth token validity
curl -s -o /dev/null -w "HTTP %{http_code}\n" \
  -H "Authorization: Bearer $GRAMMARLY_ACCESS_TOKEN" \
  https://api.grammarly.com/ecosystem/api/v2/account

Incident Playbooks
API Outage

Confirm with unauthenticated health check (see diagnostics)
Check Grammarly status page and developer announcements
Activate fallback mode — return placeholder scores to avoid blocking users
Queue text submissions for retry when API recovers
Notify downstream consumers that scores are unavailable

Authentication Failure

Test token validity with the account endpoint diagnostic above
If 401: OAuth access token has expired — trigger token refresh flow
If refresh token also fails: re-authorize via OAuth consent flow
Verify client ID and client secret are correct in environment config
Deploy refreshed tokens and confirm scoring requests succeed

Data Sync Failure

Identify if scoring results are stale or inconsistent across requests
Check if Grammarly upda
                
              

                
                  
                  
                  grammarly-install-auth
                  SKILL.md
                  View full skill →
                
                
                  Install and configure Grammarly SDK/CLI authentication.
                  
                      ReadWriteEditBash(npm:*)Bash(curl:*)Grep
                    
                
                
                  Grammarly Install & Auth
Overview
Configure Grammarly API authentication using OAuth 2.0 Bearer tokens. Grammarly provides three main APIs: Writing Score API, AI Detection API, and Plagiarism Detection API. All use the same auth pattern via api.grammarly.com.
Prerequisites

Grammarly Enterprise account with API access
OAuth credentials from Grammarly admin portal
Required scopes: scores-api:read, scores-api:write

Instructions
Step 1: Configure Environment

# .env (NEVER commit)
GRAMMARLY_CLIENT_ID=your_client_id
GRAMMARLY_CLIENT_SECRET=your_client_secret
GRAMMARLY_ACCESS_TOKEN=  # Populated after OAuth

Step 2: Obtain Access Token

// auth.ts
import 'dotenv/config';

async function getAccessToken(): Promise<string> {
  const response = await fetch('https://api.grammarly.com/ecosystem/api/v1/oauth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      client_id: process.env.GRAMMARLY_CLIENT_ID!,
      client_secret: process.env.GRAMMARLY_CLIENT_SECRET!,
    }),
  });
  const { access_token, expires_in } = await response.json();
  console.log(`Token obtained, expires in ${expires_in}s`);
  return access_token;
}

Step 3: Verify Connection

async function verify(token: string) {
  const response = await fetch('https://api.grammarly.com/ecosystem/api/v2/scores', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ text: 'This is a test sentence for verification.' }),
  });
  if (response.ok) console.log('Grammarly API connection verified');
  else console.error('Verification failed:', response.status);
}

Error Handling

Error
Cause
Solution


401 Unauthorized
Invalid or expired token
Re-authenticate


403 Forbidden
Missing API scopes
Check enterprise admin settings


invalid_client
Wrong credentials
Verify client ID and secret


Resources

Grammarly Developer Portal
Your First API Request
API Support

Next Steps
After auth, proceed to grammarly-hello-world.
                
              

                
                  
                  
                  grammarly-local-dev-loop
                  SKILL.md
                  View full skill →
                
                
                  Configure Grammarly local development with hot reload and testing.
                  
                      ReadWriteEditBash(npm:*)Bash(pnpm:*)Grep
                    
                
                
                  Grammarly Local Dev Loop
Overview
Set up a development workflow for Grammarly API integrations with mocked responses and vitest.
Instructions
Step 1: Project Structure

grammarly-integration/
├── src/grammarly/
│   ├── client.ts       # API client with token management
│   ├── scoring.ts      # Writing Score API
│   ├── detection.ts    # AI + Plagiarism detection
│   └── types.ts        # TypeScript interfaces
├── tests/
│   ├── fixtures/       # Mock API responses
│   └── scoring.test.ts
├── .env.local
└── package.json

Step 2: Mocked Tests

import { describe, it, expect, vi } from 'vitest';

const mockFetch = vi.fn();
vi.stubGlobal('fetch', mockFetch);

describe('Writing Score', () => {
  it('should return scores for valid text', async () => {
    mockFetch.mockResolvedValueOnce({
      ok: true,
      json: async () => ({ overallScore: 85, engagement: 80, correctness: 90, clarity: 85, tone: 82 }),
    });
    // Test scoring logic
  });

  it('should reject text under 30 words', async () => {
    mockFetch.mockResolvedValueOnce({ ok: false, status: 400, text: async () => 'Text too short' });
    // Test error handling
  });
});

Resources

Grammarly API Docs

Next Steps
See grammarly-sdk-patterns for production patterns.
                
              

                
                  
                  
                  grammarly-migration-deep-dive
                  SKILL.md
                  View full skill →
                
                
                  Deep dive into Grammarly API migration patterns.
                  
                      ReadWriteEditBash(npm:*)Bash(git:*)
                    
                
                
                  Grammarly Migration Deep Dive
Overview
The Grammarly Text Editor SDK was deprecated January 2024. Current APIs are Writing Score (v2), AI Detection (v1), and Plagiarism Detection (v1). This skill covers migrating from the deprecated SDK to the current REST APIs.
Migration: Text Editor SDK to REST APIs
Before (Deprecated SDK)

<!-- The deprecated approach embedded Grammarly in text editors -->
<script src="https://cdn.grammarly.com/grammarly-sdk.js"></script>
<grammarly-editor-plugin client-id="YOUR_ID">
  <textarea></textarea>
</grammarly-editor-plugin>

After (Current REST APIs)

// Server-side scoring replaces client-side editor integration
async function scoreContent(text: string) {
  const token = await getAccessToken();
  const response = await fetch('https://api.grammarly.com/ecosystem/api/v2/scores', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ text }),
  });
  return response.json();
}

Key Differences

Feature
Deprecated SDK
Current API


Execution
Client-side
Server-side


Real-time suggestions
Yes
No


Writing scores
No
Yes


AI detection
No
Yes


Plagiarism detection
No
Yes


Resources

Text Editor SDK Deprecation
Current APIs

                
              

                
                  
                  
                  grammarly-multi-env-setup
                  SKILL.md
                  View full skill →
                
                
                  Configure Grammarly across multiple environments.
                  
                      ReadWriteEditGrep
                    
                
                
                  Grammarly Multi-Environment Setup
Overview
Grammarly integration requires environment separation to isolate API credentials, enforce team-scoped style guides, and manage rate limits per tier. Development uses mock API responses for fast iteration without consuming quota, staging connects to the Grammarly sandbox for real grammar checks with test content, and production runs against the live API with full team configurations. Each environment has its own client credentials and style guide settings to prevent dev experiments from affecting production writing standards.
Environment Configuration

const grammarlyConfig = (env: string) => ({
  development: {
    clientId: process.env.GRAMMARLY_DEV_CLIENT_ID!, clientSecret: process.env.GRAMMARLY_DEV_CLIENT_SECRET!,
    baseUrl: "http://localhost:3100/mock-grammarly", useMockApi: true, concurrency: 1, intervalCap: 2,
  },
  staging: {
    clientId: process.env.GRAMMARLY_STG_CLIENT_ID!, clientSecret: process.env.GRAMMARLY_STG_CLIENT_SECRET!,
    baseUrl: "https://api.grammarly.com/sandbox", useMockApi: false, concurrency: 2, intervalCap: 5,
  },
  production: {
    clientId: process.env.GRAMMARLY_PROD_CLIENT_ID!, clientSecret: process.env.GRAMMARLY_PROD_CLIENT_SECRET!,
    baseUrl: "https://api.grammarly.com", teamId: process.env.GRAMMARLY_TEAM_ID!, concurrency: 5, intervalCap: 10,
  },
}[env]);

Environment Files

# Per-env files: .env.development, .env.staging, .env.production
GRAMMARLY_{DEV|STG|PROD}_CLIENT_ID=<client-id>
GRAMMARLY_{DEV|STG|PROD}_CLIENT_SECRET=<secret>
GRAMMARLY_BASE_URL={http://localhost:3100/mock|https://api.grammarly.com/sandbox|https://api.grammarly.com}
GRAMMARLY_TEAM_ID=<team-id>          # staging + production only

Environment Validation

function validateGrammarlyEnv(env: string): void {
  const suffix = { development: "_DEV", staging: "_STG", production: "_PROD" }[env];
  const required = [`GRAMMARLY${suffix}_CLIENT_ID`, `GRAMMARLY${suffix}_CLIENT_SECRET`];
  if (env === "production") required.push("GRAMMARLY_TEAM_ID");
  const missing = required.filter((k) => !process.env[k]);
  if (missing.length) throw new Error(`Missing Grammarly vars for ${env}: ${missing.join(", ")}`);
}

Promotion Workflow

# 1. Verify mock API coverage in dev
npm test -- --grep "grammarly" --env development

# 2. Run style guide checks against Grammarly sandbox
curl -X POST "https://api.grammarly.com/sandbox/check" \
  -H "Authorization: Bearer $GRAMMARLY_STG_TOKEN" -d @test-content.json

# 3. Compare suggestion quality between staging and baseline
node scripts/grammarly-diff.js --env staging --baseline expected-suggestions.json

# 4. Rota

                

              

                
                  
                  
                  grammarly-observability
                  SKILL.md
                  View full skill →
                
                
                  Implement Grammarly observability with metrics and logging.
                  
                      ReadWriteEdit
                    
                
                
                  Grammarly Observability
Overview
Grammarly API integrations process user text through scoring, AI rewriting, and plagiarism endpoints where latency and accuracy directly affect user experience. Monitor text check response times, suggestion quality signals, API error rates, and token consumption to stay within rate limits. Catching degradation early prevents users from seeing stale suggestions or silent failures in real-time editing flows.
Key Metrics

Metric
Type
Target
Alert Threshold


Text check latency p95
Histogram
< 300ms
> 800ms


API error rate
Gauge
< 1%
> 5%


Suggestion acceptance rate
Gauge
> 40%
< 20% (quality signal)


Token usage (daily)
Counter
< 80% quota
> 90% quota


Plagiarism check latency
Histogram
< 2s
> 5s


AI rewrite throughput
Counter
Stable
Drop > 30%


Instrumentation

async function trackGrammarlyCall(api: 'score' | 'ai' | 'plagiarism', textLen: number, fn: () => Promise<any>) {
  const start = Date.now();
  try {
    const result = await fn();
    metrics.histogram('grammarly.api.latency', Date.now() - start, { api });
    metrics.increment('grammarly.api.calls', { api });
    metrics.gauge('grammarly.text.length', textLen, { api });
    return result;
  } catch (err) {
    metrics.increment('grammarly.api.errors', { api, status: err.status });
    throw err;
  }
}

Health Check Dashboard

async function grammarlyHealth(): Promise<Record<string, string>> {
  const latencyP95 = await metrics.query('grammarly.api.latency', 'p95', '5m');
  const errorRate = await metrics.query('grammarly.api.error_rate', 'avg', '5m');
  const quotaUsed = await grammarlyAdmin.getQuotaUsage();
  return {
    api_latency: latencyP95 < 300 ? 'healthy' : 'slow',
    error_rate: errorRate < 0.01 ? 'healthy' : 'degraded',
    quota: quotaUsed < 0.8 ? 'healthy' : 'at_risk',
  };
}

Alerting Rules

const alerts = [
  { metric: 'grammarly.api.latency_p95', condition: '> 800ms', window: '10m', severity: 'warning' },
  { metric: 'grammarly.api.error_rate', condition: '> 0.05', window: '5m', severity: 'critical' },
  { metric: 'grammarly.quota.daily_pct', condition: '> 0.90', window: '1h', severity: 'warning' },
  { metric: '

                

              

                
                  
                  
                  grammarly-performance-tuning
                  SKILL.md
                  View full skill →
                
                
                  Optimize Grammarly API performance with caching, batching, and connection pooling.
                  
                      ReadWriteEdit
                    
                
                
                  Grammarly Performance Tuning
Latency Benchmarks

API
Typical Latency
Notes


Writing Score
1-3s
Depends on text length


AI Detection
1-2s
Fast for short text


Plagiarism
10-60s
Async, requires polling


Instructions
Cache Score Results

import { LRUCache } from 'lru-cache';
import { createHash } from 'crypto';

const scoreCache = new LRUCache<string, any>({ max: 500, ttl: 3600000 });

async function cachedScore(text: string, token: string) {
  const key = createHash('sha256').update(text).digest('hex');
  const cached = scoreCache.get(key);
  if (cached) return cached;
  const score = await grammarlyClient.score(text);
  scoreCache.set(key, score);
  return score;
}

Parallel API Calls

// Score + AI detect in parallel (they're independent)
async function fullAudit(text: string, token: string) {
  const [score, ai] = await Promise.all([
    grammarlyClient.score(text),
    grammarlyClient.detectAI(text),
  ]);
  return { score, ai };
}

Resources

Grammarly API

Next Steps
For cost optimization, see grammarly-cost-tuning.
                
              

                
                  
                  
                  grammarly-prod-checklist
                  SKILL.md
                  View full skill →
                
                
                  Production readiness checklist for Grammarly API integrations.
                  
                      ReadWriteEditBash(curl:*)Grep
                    
                
                
                  Grammarly Production Checklist
Overview
Grammarly provides AI-powered writing assistance with grammar checking, tone detection, plagiarism scanning, and style suggestions. A production integration processes user-submitted text through Grammarly's API and returns actionable suggestions. Failures mean unchecked content goes live, suggestion latency degrades UX, or sensitive text leaks outside approved processing boundaries.
Authentication & Secrets

[ ] GRAMMARLYAPIKEY stored in secrets manager (not config files)
[ ] Client credentials (ID + secret) separated from application code
[ ] Token refresh logic handles expiry before API calls fail
[ ] Separate credentials for dev/staging/prod environments
[ ] Key rotation schedule documented (90-day cycle)

API Integration

[ ] Production base URL configured (https://api.grammarly.com/v1)
[ ] Rate limit handling with exponential backoff
[ ] Text chunking implemented for documents > 100K characters
[ ] Minimum 30-word validation before sending to API
[ ] Suggestion categories configured per use case (grammar, tone, clarity)
[ ] AI detection endpoint integrated if content authenticity required
[ ] Plagiarism check timeout handling (longer processing for large docs)

Error Handling & Resilience

[ ] Circuit breaker configured for Grammarly API outages
[ ] Retry with backoff for 429/5xx responses
[ ] Writing score thresholds defined per content type
[ ] Graceful degradation when API is unavailable (queue, not block)
[ ] Error responses logged with request IDs for support escalation
[ ] Partial suggestion results handled (incomplete analysis on timeout)

Monitoring & Alerting

[ ] API latency tracked per request type (check, detect, plagiarism)
[ ] Error rate alerts set (threshold: >5% over 5 minutes)
[ ] Token refresh failures trigger immediate notification
[ ] Suggestion acceptance rate tracked for quality feedback loop
[ ] Daily API usage against plan limits monitored

Validation Script

async function checkGrammarlyReadiness(): Promise<void> {
  const checks: { name: string; pass: boolean; detail: string }[] = [];
  // API connectivity
  try {
    const res = await fetch('https://api.grammarly.com/v1/check', {
      method: 'POST',
      headers: { Authorization: `Bearer ${process.env.GRAMMARLY_API_KEY}`, 'Content-Type': 'application/json' },
      body: JSON.stringify({ text: 'This is a production readiness test sentence for validation.' }),
    });
    checks.push({ name: 'Grammarly API', pass: res.ok, detail: res.ok ? 'Connected' : `HTTP ${res.status}` });
  } catch (

                

              

                
                  
                  
                  grammarly-rate-limits
                  SKILL.md
                  View full skill →
                
                
                  Implement Grammarly rate limiting, backoff, and idempotency patterns.
                  
                      ReadWriteEdit
                    
                
                
                  Grammarly Rate Limits
Overview
Grammarly's Text API enforces plan-dependent rate limits across its writing score, AI detection, and plagiarism endpoints. The plagiarism checker is asynchronous and requires polling, which adds complexity to rate management. Token endpoints are separately throttled at roughly 10 requests per hour, so credential rotation during high-throughput batch processing of documents (e.g., scanning an entire content library) requires careful token lifecycle management to avoid auth-layer 429s on top of API-layer throttling.
Rate Limit Reference

Endpoint
Limit
Window
Scope


Writing score
100 req (Business)
1 minute
Per API key


AI content detection
60 req (Business)
1 minute
Per API key


Plagiarism check (submit)
30 req
1 minute
Per API key


Plagiarism check (poll)
120 req
1 minute
Per API key


Token refresh
10 req
1 hour
Per client credentials


Rate Limiter Implementation

class GrammarlyRateLimiter {
  private tokens: number;
  private lastRefill: number;
  private readonly max: number;
  private readonly refillRate: number;
  private queue: Array<{ resolve: () => void }> = [];

  constructor(maxPerMinute: number) {
    this.max = maxPerMinute;
    this.tokens = maxPerMinute;
    this.lastRefill = Date.now();
    this.refillRate = maxPerMinute / 60_000;
  }

  async acquire(): Promise<void> {
    this.refill();
    if (this.tokens >= 1) { this.tokens -= 1; return; }
    return new Promise(resolve => this.queue.push({ resolve }));
  }

  private refill() {
    const now = Date.now();
    this.tokens = Math.min(this.max, this.tokens + (now - this.lastRefill) * this.refillRate);
    this.lastRefill = now;
    while (this.tokens >= 1 && this.queue.length) {
      this.tokens -= 1;
      this.queue.shift()!.resolve();
    }
  }
}

const scoreLimiter = new GrammarlyRateLimiter(90);
const plagiarismLimiter = new GrammarlyRateLimiter(25);

Retry Strategy

async function grammarlyRetry<T>(
  limiter: GrammarlyRateLimiter, fn: () => Promise<Response>, maxRetries = 3
): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    await limiter.acquire();
    const res = await fn();
    if (res.ok) return res.json();
    if (res.status === 429) {
      const retryAfter = parseInt(res.headers.get("Retry-After") || "20", 10);
      const jitter = Math.random() * 2000;
      await new Promise(r => setTimeout(r, retryAfter * 1000 + jitter));
      continue;
    }
    if (res.status >= 500 &&

                

              

                
                  
                  
                  grammarly-reference-architecture
                  SKILL.md
                  View full skill →
                
                
                  Implement Grammarly reference architecture with best-practice project layout.
                  
                      ReadGrep
                    
                
                
                  Grammarly Reference Architecture
Architecture

┌────────────────────────────────────┐
│         Your Application            │
├────────────────────────────────────┤
│    Content Quality Service          │
│  (Score, AI Detect, Plagiarism)     │
├────────────────────────────────────┤
│    Grammarly API Client             │
│  (Auth, Retry, Cache, Chunking)     │
├────────────────────────────────────┤
│    Grammarly APIs                   │
│  api.grammarly.com                  │
└────────────────────────────────────┘

Project Structure

grammarly-integration/
├── src/grammarly/
│   ├── client.ts        # API client with token management
│   ├── scoring.ts       # Writing Score API
│   ├── detection.ts     # AI + Plagiarism detection
│   ├── chunking.ts      # Large document splitting
│   └── types.ts         # TypeScript interfaces
├── src/services/
│   ├── quality-gate.ts  # Threshold enforcement
│   └── content-audit.ts # Full audit pipeline
├── tests/
└── .env.example

API Decision Matrix

Need
API
Notes


Grammar/style quality
Writing Score v2
Sync, fast


AI content detection
AI Detection v1
Sync, fast


Source matching
Plagiarism v1
Async, poll


All three
Combined pipeline
Parallel where possible


Resources

Grammarly Developer Portal

Next Steps
Start with grammarly-install-auth.
                
              

                
                  
                  
                  grammarly-sdk-patterns
                  SKILL.md
                  View full skill →
                
                
                  Apply production-ready Grammarly SDK patterns for TypeScript and Python.
                  
                      ReadWriteEdit
                    
                
                
                  Grammarly SDK Patterns
Overview
Production patterns for Grammarly API: typed client, token management, text chunking for large documents, and Python integration.
Instructions
Step 1: Typed API Client

class GrammarlyClient {
  private token: string;
  private expiresAt: number = 0;
  private base = 'https://api.grammarly.com/ecosystem/api';

  constructor(private clientId: string, private clientSecret: string) {}

  private async ensureToken() {
    if (Date.now() < this.expiresAt - 60000) return;
    const res = await fetch(`${this.base}/v1/oauth/token`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({ grant_type: 'client_credentials', client_id: this.clientId, client_secret: this.clientSecret }),
    });
    const { access_token, expires_in } = await res.json();
    this.token = access_token;
    this.expiresAt = Date.now() + expires_in * 1000;
  }

  async score(text: string) {
    await this.ensureToken();
    const res = await fetch(`${this.base}/v2/scores`, {
      method: 'POST',
      headers: { 'Authorization': `Bearer ${this.token}`, 'Content-Type': 'application/json' },
      body: JSON.stringify({ text }),
    });
    return res.json();
  }

  async detectAI(text: string) {
    await this.ensureToken();
    const res = await fetch(`${this.base}/v1/ai-detection`, {
      method: 'POST',
      headers: { 'Authorization': `Bearer ${this.token}`, 'Content-Type': 'application/json' },
      body: JSON.stringify({ text }),
    });
    return res.json();
  }
}

Step 2: Text Chunking for Large Documents

function chunkText(text: string, maxChars = 90000): string[] {
  if (text.length <= maxChars) return [text];
  const chunks: string[] = [];
  const paragraphs = text.split('\n\n');
  let current = '';
  for (const p of paragraphs) {
    if ((current + '\n\n' + p).length > maxChars) {
      if (current) chunks.push(current);
      current = p;
    } else {
      current = current ? current + '\n\n' + p : p;
    }
  }
  if (current) chunks.push(current);
  return chunks;
}

Step 3: Python Client

import os, requests
from dotenv import load_dotenv

load_dotenv()

class GrammarlyClient:
    BASE = 'https://api.grammarly.com/ecosystem/api'

    def __init__(self):
        self.token = None
        self._authenticate()

    def _authenticate(self):
        r = requests.post(f'{self.BASE}/v1/oauth/token', data={
            'grant_type': 'client_credentials',
            'client_id': os.environ['GRAMMARLY_CLIENT_ID'],
            'client_secret': os.environ['GRAMMARLY_CLIENT_SECRET']

                

              

                
                  
                  
                  grammarly-security-basics
                  SKILL.md
                  View full skill →
                
                
                  Security fundamentals for Grammarly API credential management.
                  
                      ReadWriteEditBash(curl:*)Grep
                    
                
                
                  Grammarly Security Basics
Overview
Grammarly processes user-written text content for grammar, tone, and style suggestions. Integrations handle document text that may contain confidential business communications, legal drafts, or personal correspondence. Security concerns include OAuth client credential management, ensuring user text is not persisted or logged unnecessarily, and protecting access tokens that grant read/write access to user documents and suggestion history.
API Key Management

function createGrammarlyClient(): { clientId: string; clientSecret: string } {
  const clientId = process.env.GRAMMARLY_CLIENT_ID;
  const clientSecret = process.env.GRAMMARLY_CLIENT_SECRET;
  if (!clientId || !clientSecret) {
    throw new Error("Missing GRAMMARLY_CLIENT_ID or GRAMMARLY_CLIENT_SECRET");
  }
  // Access tokens from client_credentials grant — never persist to disk
  console.log("Grammarly client initialized (client ID:", clientId.slice(0, 8), "...)");
  return { clientId, clientSecret };
}

Webhook Signature Verification

import crypto from "crypto";
import { Request, Response, NextFunction } from "express";

function verifyGrammarlyWebhook(req: Request, res: Response, next: NextFunction): void {
  const signature = req.headers["x-grammarly-signature"] as string;
  const secret = process.env.GRAMMARLY_WEBHOOK_SECRET!;
  const expected = crypto.createHmac("sha256", secret).update(req.body).digest("hex");
  if (!signature || !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    res.status(401).send("Invalid signature");
    return;
  }
  next();
}

Input Validation

import { z } from "zod";

const TextAnalysisSchema = z.object({
  document_id: z.string().uuid(),
  text: z.string().min(1).max(100_000),
  language: z.enum(["en-US", "en-GB", "en-AU", "en-CA"]).default("en-US"),
  domain: z.enum(["general", "academic", "business", "casual"]).default("general"),
  goals: z.array(z.enum(["clarity", "engagement", "delivery", "correctness"])).optional(),
});

function validateTextAnalysis(data: unknown) {
  return TextAnalysisSchema.parse(data);
}

Data Protection

const GRAMMARLY_SENSITIVE_FIELDS = ["document_text", "user_email", "access_token", "client_secret", "suggestion_context"];

function redactGrammarlyLog(record: Record<string, unknown>): Record<string, unknown> {
  const redacted = { ...record };
  for (const field of GRAMMARLY_SENSITIVE_FIELDS) {
    if (field in redacted) redacted[field] = 

                

              

                
                  
                  
                  grammarly-upgrade-migration
                  SKILL.md
                  View full skill →
                
                
                  Upgrade and migration guidance for Grammarly API version changes.
                  
                      ReadWriteEditBash(curl:*)Grep
                    
                
                
                  Grammarly Upgrade & Migration
Overview
Grammarly exposes versioned APIs for writing analysis, AI detection, and plagiarism checking. Each API family versions independently — the Writing Score API may be on v2 while AI Detection remains on v1. Tracking these versions matters because Grammarly deprecates older API versions on a fixed timeline, and the response schemas differ significantly between versions (score breakdowns, suggestion categories, and confidence thresholds all change). Missing a version cutover means silent failures or degraded writing feedback quality.
Version Detection

const GRAMMARLY_BASE = "https://api.grammarly.com/ecosystem/api";

interface GrammarlyVersionMap {
  scores: string;
  aiDetection: string;
  plagiarism: string;
  latestAvailable: Record<string, string>;
}

async function detectGrammarlyVersions(apiKey: string): Promise<GrammarlyVersionMap> {
  const endpoints = {
    scores: `${GRAMMARLY_BASE}/v2/scores`,
    aiDetection: `${GRAMMARLY_BASE}/v1/ai-detection`,
    plagiarism: `${GRAMMARLY_BASE}/v1/plagiarism`,
  };

  const versions: Record<string, string> = {};
  for (const [api, url] of Object.entries(endpoints)) {
    const res = await fetch(url, {
      method: "HEAD",
      headers: { Authorization: `Bearer ${apiKey}` },
    });
    versions[api] = res.headers.get("x-grammarly-api-version") ?? "unknown";
    const deprecated = res.headers.get("x-grammarly-deprecated");
    if (deprecated) console.warn(`${api} endpoint deprecated: ${deprecated}`);
  }
  return { scores: "v2", aiDetection: "v1", plagiarism: "v1", latestAvailable: versions };
}

Migration Checklist

[ ] Audit codebase for all api.grammarly.com endpoint references
[ ] Map each endpoint to its current API version (v1 vs. v2)
[ ] Check if Writing Score v2 response includes new sub-score categories
[ ] Verify AI Detection confidence threshold changes between versions
[ ] Update plagiarism check response parser if source attribution format changed
[ ] Test OAuth token flow — scope names may differ between API versions
[ ] Validate suggestion category enums (clarity, engagement, delivery, correctness)
[ ] Update error handling for new rate limit headers in v2
[ ] Check if text submission size limits changed between versions
[ ] Run A/B comparison of v1 vs. v2 scores on sample corpus to verify parity

Schema Migration

// Grammarly scores response changed from flat scores to structured breakdown
interface OldScoreResponse {
  overall: number;
  correctness: number;
  clarity: number;
  engagement: number;
  delivery: number;
}

interface NewScoreResponse {
  overall: { score: number; label: string };
  dimensions: Ar

                

              

                
                  
                  
                  grammarly-webhooks-events
                  SKILL.md
                  View full skill →
                
                
                  Implement Grammarly webhook signature validation and event handling.
                  
                      ReadWriteEditBash(curl:*)
                    
                
                
                  Grammarly Webhooks & Events
Overview
Grammarly's current API is request/response based — there are no push webhooks. For async operations (plagiarism detection), you poll for results. Build your own event system around Grammarly API results.
Instructions
Step 1: Plagiarism Polling with Callback

async function plagiarismWithCallback(
  text: string,
  token: string,
  onComplete: (result: any) => void
) {
  const createRes = await fetch('https://api.grammarly.com/ecosystem/api/v1/plagiarism', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ text }),
  });
  const { id } = await createRes.json();

  const poll = async () => {
    const res = await fetch(`https://api.grammarly.com/ecosystem/api/v1/plagiarism/${id}`, {
      headers: { 'Authorization': `Bearer ${token}` },
    });
    const result = await res.json();
    if (result.status === 'pending') { setTimeout(poll, 3000); return; }
    onComplete(result);
  };
  poll();
}

Step 2: Build Event Bus for Score Results

import { EventEmitter } from 'events';

const grammarlyEvents = new EventEmitter();

grammarlyEvents.on('score.completed', (data) => {
  if (data.overallScore < 60) console.warn('Low quality content detected');
});

grammarlyEvents.on('ai.detected', (data) => {
  if (data.score > 70) console.warn('Likely AI-generated content');
});

Resources

Grammarly API

Next Steps
For performance, see grammarly-performance-tuning.
                
              

          

        


      
      

      
      

      
      

      
      
  Ready to use grammarly-pack?
  
    
    
  




      
      
          Related Plugins
          
            
                ai-ethics-validator
                AI ethics and fairness validation
              
                ai-experiment-logger
                Track and analyze AI experiments with a web dashboard and MCP tools
              
                ai-ml-engineering-pack
                Professional AI/ML Engineering toolkit: Prompt engineering, LLM integration, RAG systems, AI safety with 12 expert plugins
              
                ai-sdk-agents
                Multi-agent orchestration with AI SDK v5 - handoffs, routing, and coordination for any AI provider (OpenAI, Anthropic, Google)
              
                anomaly-detection-system
                Detect anomalies and outliers in data
              
                automl-pipeline-builder
                Build AutoML pipelines
              
          
        

      
      
          Tags
          
            grammarlysaassdkintegration
          
        
    
  

  

    

    
    
        
            
                Stay in the Loop
                
                    
                    
                    
                
                No spam. Unsubscribe anytime.
            

            
                
                    Product
                    
                        Explore
                        Skills
                        Cowork
                        Compare
                        Tools
                    
                
                
                    Resources
                    
                        Docs
                        Changelog
                        Collections
                        Playbooks
                        Research
                        Learning
                    
                
                
                    Company
                    
                        Community
                        Spotlight
                        GitHub
                    
                
                
                    Legal
                    
                        Privacy
                        Terms
                        Acceptable Use
                    
                
            

            
                Tons of Skills by Intent Solutions. Marine. Citadel Grad. 20 years ops → self-taught dev → AI architect.
                © 2026 Tons of Skills | Intent Solutions