flaqai/Awesome_SEO_Writing_Skill / writer
writer
VerifiedSEO-friendly article writing, audit, and humanization workflow for Markdown content. Use when creating, outlining, editing, auditing, rewriting, or quality-checking blog posts, tutorials, comparisons, listicles, explainers, FAQ sections, excerpts, SEO titles, meta descriptions, tags, or Google-friendly content briefs that need clear topics, natural keyword use, on-page SEO review, reader-friendly prose, and iterative optimization.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 22.7 KB |
| config/r2.config.example.json | config | 287 B |
| references/fact-check-and-style.md | markdown | 5.1 KB |
| references/humanization.md | markdown | 7.8 KB |
| references/output-packaging.md | markdown | 6.3 KB |
| references/r2-image-upload.md | markdown | 4.3 KB |
| references/r2-security.md | markdown | 2.0 KB |
| references/seo-article-template.md | markdown | 9.8 KB |
| references/seo-audit-checklist.md | markdown | 7.7 KB |
| scripts/upload-r2.mjs | script | 18.5 KB |
scripts/upload-r2.mjs
View on GitHub#!/usr/bin/env node
import { spawn } from 'node:child_process';
import { createHash, createHmac } from 'node:crypto';
import { access, mkdir, readFile, stat, writeFile } from 'node:fs/promises';
import { basename, delimiter, dirname, extname, join, posix } from 'node:path';
const DEFAULT_CONFIG = 'writer/config/r2.config.json';
const args = parseArgs(process.argv.slice(2));
if (args.help || !args.file) {
printUsage();
process.exit(args.help ? 0 : 1);
}
const filePath = args.file;
await access(filePath);
const configSource = await loadConfig(args);
if (!configSource) {
console.log(JSON.stringify({
ok: true,
skipped: true,
reason: 'r2-config-not-found',
config: DEFAULT_CONFIG,
file: filePath,
localReference: `./${basename(filePath)}`,
articleUpdated: false,
manifestUpdated: false,
}, null, 2));
process.exit(0);
}
const config = configSource.config;
validateConfig(config, configSource.label);
const uploadPreparation = await prepareImageForUpload(filePath, args);
const uploadFilePath = uploadPreparation.uploadFile;
const body = await readFile(uploadFilePath);
const contentType = args.contentType || contentTypeFor(uploadFilePath);
const uploadAlt = args.alt || '';
const uploadKeyword = args.keyword || '';
const uploadTopic = args.topic || '';
const uploadDate = parseUploadDate(args.date || new Date());
const objectKey = normalizeKey(args.key
? sanitizeObjectKeyFilename(args.key, uploadFilePath)
: buildDefaultKey({
keyPrefix: config.keyPrefix,
blogDirectory: args.blogDir || config.blogDirectory || 'blog',
date: uploadDate,
filePath,
extensionPath: uploadFilePath,
seoName: args.seoName || uploadKeyword || uploadTopic || '',
}));
const endpoint = `https://${config.accountId}.r2.cloudflarestorage.com`;
const uploadUrl = `${endpoint}/${encodePath(config.bucket)}/${encodePath(objectKey)}`;
if (!args.dryRun) {
await putObject({
url: uploadUrl,
region: config.region || 'auto',
accessKeyId: config.accessKeyId,
secretAccessKey: config.secretAccessKey,
body,
contentType,
});
}
const publicUrl = joinPublicUrl(config.publicBaseUrl, objectKey);
if (args.article && !args.dryRun) {
await replaceArticleImageUrl(args.article, filePath, publicUrl, args.alt);
}
const result = {
ok: true,
file: filePath,
uploadedFile: uploadFilePath,
compression: uploadPreparation.compression,
seoName: args.seoName || null,
alt: uploadAlt || null,
keyword: uploadKeyword || null,
topic: uploadTopic || null,
bucket: config.bucket,
key: objectKey,
blogDirectory: args.blogDir || config.blogDirectory || 'blog',
datePath: formatDatePath(uploadDate),
contentType,
url: publicUrl,
r2: {
bucket: config.bucket,
key: objectKey,
publicUrl,
publicBaseUrl: config.publicBaseUrl,
blogDirectory: args.blogDir || config.blogDirectory || 'blog',
datePath: formatDatePath(uploadDate),
},
articleUpdated: Boolean(args.article && !args.dryRun),
dryRun: Boolean(args.dryRun),
};
if (args.manifest && !args.dryRun) {
await updateManifest(args.manifest, result);
}
console.log(JSON.stringify(result, null, 2));
function parseArgs(argv) {
const parsed = {};
for (let i = 0; i < argv.length; i += 1) {
const item = argv[i];
if (item === '--help' || item === '-h') {
parsed.help = true;
} else if (item.startsWith('--')) {
const key = item.slice(2);
const value = argv[i + 1];
if (!value || value.startsWith('--')) {
parsed[key] = true;
} else {
parsed[key] = value;
i += 1;
}
}
}
return parsed;
}
function printUsage() {
console.log(`Usage:
node writer/scripts/upload-r2.mjs --file <image-path> [options]
Options:
--config <path> Local config path; defaults to writer/config/r2.config.json
If the default config is absent, upload is skipped successfully
--key <object-key> Override object key; default is <keyPrefix>/<blogDirectory>/yyyy/mm/dd/<filename>
--blogDir <dir> Blog image directory; defaults to config.blogDirectory or blog
--date <yyyy-mm-dd> Upload date path; defaults to today
--seoName <text> SEO-friendly image basename source; sanitized to letters/numbers
--keyword <text> Keyword metadata and fallback SEO filename source
--topic <text> Topic metadata and fallback SEO filename source
--article <path> Replace local Markdown image references in article.md
--manifest <path> Save/update upload URL mapping JSON
--alt <text> Alt text to use when inserting/replacing image Markdown
--contentType <type> Defaults by file extension
--noCompress Upload the source file without local image compression
--compressionQuality <1-100>
WebP quality for local compression; defaults to 88
--compressionFormat <webp>
Compressed upload format; defaults to webp
--compressedFile <path>
Override the local compressed image output path
--minCompressionSavingsPercent <number>
Use compressed file only when savings meet this percent; defaults to 3
--dryRun Print key and URL without uploading or editing article/manifest files
Example:
node writer/scripts/upload-r2.mjs \\
--file writer/output/my-post/hero-16x9.png \\
--seoName "Seedance 2.0 AI video hero" \\
--keyword "Seedance 2.0 AI" \\
--topic "AI video generation" \\
--article writer/output/my-post/article.md \\
--manifest writer/output/my-post/image-urls.json \\
--alt "Seedance 2.0 AI video generation hero image"`);
}
function validateConfig(config, configPath) {
const required = ['accountId', 'bucket', 'accessKeyId', 'secretAccessKey', 'publicBaseUrl'];
const missing = required.filter((key) => !config[key] || String(config[key]).startsWith('your-'));
if (missing.length) {
throw new Error(`Missing or placeholder R2 config fields in ${configPath}: ${missing.join(', ')}`);
}
}
async function loadConfig(parsedArgs) {
const configPath = parsedArgs.config || DEFAULT_CONFIG;
if (!await fileExists(configPath)) {
if (parsedArgs.config) {
throw new Error(`R2 config not found: ${configPath}`);
}
return null;
}
return {
label: configPath,
config: JSON.parse(await readFile(configPath, 'utf8')),
};
}
async function fileExists(path) {
try {
await access(path);
return true;
} catch {
return false;
}
}
async function prepareImageForUpload(filePath, parsedArgs) {
const originalStats = await stat(filePath);
const compression = {
enabled: !parsedArgs.noCompress,
attempted: false,
usedCompressed: false,
sourceFile: filePath,
uploadFile: filePath,
originalBytes: originalStats.size,
compressedFile: null,
compressedBytes: null,
savedBytes: 0,
savedPercent: 0,
format: null,
quality: null,
tool: null,
skippedReason: null,
};
if (!compression.enabled) {
compression.skippedReason = 'disabled';
return { uploadFile: filePath, compression };
}
const sourceExt = extname(filePath).toLowerCase();
if (!['.png', '.jpg', '.jpeg', '.webp'].includes(sourceExt)) {
compression.skippedReason = `unsupported image type: ${sourceExt || 'none'}`;
return { uploadFile: filePath, compression };
}
const format = String(parsedArgs.compressionFormat || 'webp').toLowerCase();
if (format !== 'webp') {
throw new Error(`Unsupported --compressionFormat "${format}". Currently supported: webp.`);
}
const cwebpPath = await findExecutable('cwebp');
if (!cwebpPath) {
compression.skippedReason = 'cwebp not found';
return { uploadFile: filePath, compression };
}
const quality = parseCompressionQuality(parsedArgs.compressionQuality || parsedArgs.quality || 88);
const minSavingsPercent = parseNonNegativeNumber(
parsedArgs.minCompressionSavingsPercent,
3,
'--minCompressionSavingsPercent',
);
const compressedFile = parsedArgs.compressedFile || buildCompressedFilePath(filePath, format);
if (compressedFile === filePath) {
throw new Error('--compressedFile must be different from --file.');
}
compression.attempted = true;
compression.compressedFile = compressedFile;
compression.format = format;
compression.quality = quality;
compression.tool = cwebpPath;
await mkdir(dirname(compressedFile), { recursive: true });
try {
await runProcess(cwebpPath, [
'-quiet',
'-q',
String(quality),
'-alpha_q',
'95',
'-m',
'6',
'-metadata',
'none',
filePath,
'-o',
compressedFile,
]);
} catch (error) {
compression.skippedReason = `compression failed: ${error.message}`;
return { uploadFile: filePath, compression };
}
const compressedStats = await stat(compressedFile);
const savedBytes = originalStats.size - compressedStats.size;
const savedPercent = originalStats.size > 0
? Number(((savedBytes / originalStats.size) * 100).toFixed(2))
: 0;
compression.compressedBytes = compressedStats.size;
compression.savedBytes = savedBytes;
compression.savedPercent = savedPercent;
if (savedBytes <= 0) {
compression.skippedReason = 'compressed file is not smaller than source';
return { uploadFile: filePath, compression };
}
if (savedPercent < minSavingsPercent) {
compression.skippedReason = `savings below ${minSavingsPercent}% threshold`;
return { uploadFile: filePath, compression };
}
compression.usedCompressed = true;
compression.uploadFile = compressedFile;
return { uploadFile: compressedFile, compression };
}
function buildCompressedFilePath(filePath, format) {
const sourceExt = extname(filePath);
const sourceBase = basename(filePath, sourceExt);
return join(dirname(filePath), `${sourceBase}-r2.${format}`);
}
function parseCompressionQuality(value) {
const quality = Number(value);
if (!Number.isFinite(quality) || quality < 1 || quality > 100) {
throw new Error(`Invalid --compressionQuality value "${value}". Use a number from 1 to 100.`);
}
return Math.round(quality);
}
function parseNonNegativeNumber(value, fallback, label) {
if (value === undefined || value === null || value === true || value === '') return fallback;
const parsed = Number(value);
if (!Number.isFinite(parsed) || parsed < 0) {
throw new Error(`Invalid ${label} value "${value}". Use a non-negative number.`);
}
return parsed;
}
async function findExecutable(name) {
const pathValues = [
...String(process.env.PATH || '').split(delimiter),
'/opt/homebrew/bin',
'/usr/local/bin',
'/usr/bin',
'/bin',
].filter(Boolean);
for (const dir of pathValues) {
const candidate = join(dir, name);
try {
await access(candidate);
return candidate;
} catch {
// Try the next path.
}
}
return null;
}
function runProcess(command, processArgs) {
return new Promise((resolve, reject) => {
const child = spawn(command, processArgs, {
stdio: ['ignore', 'pipe', 'pipe'],
});
let stdout = '';
let stderr = '';
child.stdout.on('data', (chunk) => {
stdout += chunk.toString();
});
child.stderr.on('data', (chunk) => {
stderr += chunk.toString();
});
child.on('error', reject);
child.on('close', (code) => {
if (code === 0) {
resolve({ stdout, stderr });
return;
}
const message = (stderr || stdout || `${command} exited with code ${code}`).trim();
reject(new Error(message));
});
});
}
function buildDefaultKey({ keyPrefix, blogDirectory, date, filePath, extensionPath, seoName }) {
const { yyyy, mm, dd } = dateParts(date);
return posix.join(
keyPrefix || '',
blogDirectory || 'blog',
yyyy,
mm,
dd,
buildSeoFilename({ filePath, extensionPath, seoName }),
);
}
function normalizeKey(key) {
return key.replace(/^\/+/, '').replace(/\\/g, '/');
}
function sanitizeObjectKeyFilename(key, extensionPath) {
const normalized = normalizeKey(key);
const parts = normalized.split('/');
const filename = parts.pop() || 'image.png';
parts.push(sanitizeFilename(filename, extensionPath));
return parts.join('/');
}
function contentTypeFor(filePath) {
const ext = extname(filePath).toLowerCase();
if (ext === '.png') return 'image/png';
if (ext === '.jpg' || ext === '.jpeg') return 'image/jpeg';
if (ext === '.webp') return 'image/webp';
if (ext === '.gif') return 'image/gif';
if (ext === '.svg') return 'image/svg+xml';
return 'application/octet-stream';
}
function sanitizeFilename(filename, extensionPath) {
const sourceExt = extname(filename).toLowerCase();
const ext = extname(extensionPath || filename).toLowerCase() || sourceExt || '.png';
const base = basename(filename, sourceExt);
const cleanedBase = base.replace(/[^a-zA-Z0-9]/g, '') || 'image';
const cleanedExt = ext.replace(/[^a-zA-Z0-9.]/g, '');
return `${cleanedBase}${cleanedExt}`;
}
function buildSeoFilename({ filePath, extensionPath, seoName }) {
const sourceExt = extname(filePath);
const ext = extname(extensionPath || filePath).toLowerCase().replace(/[^a-zA-Z0-9.]/g, '') || '.png';
const source = String(seoName || basename(filePath, sourceExt)).trim();
const words = source.match(/[a-zA-Z0-9]+/g) || ['image'];
const basenameOnly = words
.map((word, index) => {
const lower = word.toLowerCase();
if (/^\d+$/.test(lower)) return lower;
return index === 0
? lower
: `${lower.slice(0, 1).toUpperCase()}${lower.slice(1)}`;
})
.join('')
.replace(/[^a-zA-Z0-9]/g, '') || 'image';
return `${basenameOnly}${ext}`;
}
function encodePath(path) {
return path.split('/').map(encodeURIComponent).join('/');
}
function joinPublicUrl(publicBaseUrl, key) {
const normalizedBaseUrl = /^https?:\/\//i.test(publicBaseUrl)
? publicBaseUrl
: `https://${publicBaseUrl}`;
return `${normalizedBaseUrl.replace(/\/+$/, '')}/${encodePath(key)}`;
}
async function replaceArticleImageUrl(articlePath, imagePath, publicUrl, altText) {
const filename = basename(imagePath);
const escapedFilename = escapeRegExp(filename);
const markdownAlt = altText || filename.replace(/\.[^.]+$/, '').replace(/[-_]+/g, ' ');
const article = await readFile(articlePath, 'utf8');
const localImagePattern = new RegExp(`!\\[[^\\]]*\\]\\((?:\\./)?${escapedFilename}\\)`, 'g');
const replacement = ``;
const next = localImagePattern.test(article)
? article.replace(localImagePattern, replacement)
: article.replace(/^# .+$/m, (heading) => `${heading}\n\n${replacement}`);
await writeFile(articlePath, next);
}
async function updateManifest(manifestPath, result) {
let current = [];
try {
current = JSON.parse(await readFile(manifestPath, 'utf8'));
if (!Array.isArray(current)) current = [];
} catch (error) {
if (error.code !== 'ENOENT') throw error;
}
const next = [
...current.filter((item) => item.file !== result.file && item.key !== result.key),
{
file: result.file,
uploadedFile: result.uploadedFile,
compression: result.compression,
seoName: result.seoName,
alt: result.alt,
keyword: result.keyword,
topic: result.topic,
key: result.key,
blogDirectory: result.blogDirectory,
datePath: result.datePath,
url: result.url,
r2: result.r2,
contentType: result.contentType,
uploadedAt: new Date().toISOString(),
},
];
await writeFile(manifestPath, `${JSON.stringify(next, null, 2)}\n`);
}
function parseUploadDate(value) {
if (value instanceof Date) return value;
const match = String(value).match(/^(\d{4})-(\d{2})-(\d{2})$/);
if (!match) {
throw new Error(`Invalid --date value "${value}". Use yyyy-mm-dd.`);
}
const date = new Date(Number(match[1]), Number(match[2]) - 1, Number(match[3]));
if (Number.isNaN(date.getTime())) {
throw new Error(`Invalid --date value "${value}". Use yyyy-mm-dd.`);
}
return date;
}
function dateParts(date) {
const yyyy = String(date.getFullYear());
const mm = String(date.getMonth() + 1).padStart(2, '0');
const dd = String(date.getDate()).padStart(2, '0');
return { yyyy, mm, dd };
}
function formatDatePath(date) {
const { yyyy, mm, dd } = dateParts(date);
return `${yyyy}/${mm}/${dd}`;
}
function escapeRegExp(value) {
return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
}
async function putObject({ url, region, accessKeyId, secretAccessKey, body, contentType }) {
const target = new URL(url);
const now = new Date();
const amzDate = toAmzDate(now);
const dateStamp = amzDate.slice(0, 8);
const payloadHash = sha256Hex(body);
const service = 's3';
const credentialScope = `${dateStamp}/${region}/${service}/aws4_request`;
const encodedPath = target.pathname
.split('/')
.map((part) => encodeURIComponent(decodeURIComponent(part)))
.join('/');
const headers = {
'content-type': contentType,
host: target.host,
'x-amz-content-sha256': payloadHash,
'x-amz-date': amzDate,
};
const signedHeaders = Object.keys(headers).sort().join(';');
const canonicalHeaders = Object.keys(headers)
.sort()
.map((key) => `${key}:${headers[key]}\n`)
.join('');
const canonicalRequest = [
'PUT',
encodedPath,
'',
canonicalHeaders,
signedHeaders,
payloadHash,
].join('\n');
const stringToSign = [
'AWS4-HMAC-SHA256',
amzDate,
credentialScope,
sha256Hex(canonicalRequest),
].join('\n');
const signingKey = getSignatureKey(secretAccessKey, dateStamp, region, service);
const signature = hmacHex(signingKey, stringToSign);
headers.authorization = [
`AWS4-HMAC-SHA256 Credential=${accessKeyId}/${credentialScope}`,
`SignedHeaders=${signedHeaders}`,
`Signature=${signature}`,
].join(', ');
const response = await fetch(target, {
method: 'PUT',
headers,
body,
});
if (!response.ok) {
const responseBody = await response.text();
throw new Error(`R2 upload failed: ${response.status} ${response.statusText}\n${responseBody}`);
}
}
function toAmzDate(date) {
return date.toISOString().replace(/[:-]|\.\d{3}/g, '');
}
function sha256Hex(value) {
return createHash('sha256').update(value).digest('hex');
}
function hmac(key, value) {
return createHmac('sha256', key).update(value).digest();
}
function hmacHex(key, value) {
return createHmac('sha256', key).update(value).digest('hex');
}
function getSignatureKey(secretAccessKey, dateStamp, region, service) {
const kDate = hmac(`AWS4${secretAccessKey}`, dateStamp);
const kRegion = hmac(kDate, region);
const kService = hmac(kRegion, service);
return hmac(kService, 'aws4_request');
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |