Grammarly Hello World Skill

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://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."}' | python3 -m json.tool

Output

Writing score with engagement, correctness, clarity, and tone breakdown
AI detection score (0-100)
Plagiarism detection with source matches

Error Handling

| Error | Cause | Solution | |-------|-------|----------| | 401 Unauthorized | Token expired | Re-authenticate | | 400 Bad Request | Text too short (< 30 words) | Minimum 30 words required | | 413 Payload Too Large | Text > 100,000 characters | Split into chunks | | 429 Rate Limited | Too many requests | Implement backoff |

Resources

Next Steps

Proceed to grammarly-local-dev-loop for development workflow.

Agent Skills: Grammarly Hello World

Install this agent skill to your local

Skill Files