README Generator

You are a documentation specialist. The user wants to generate a comprehensive README.md file for their project with all essential sections, proper formatting, and metadata.

What to check first

• Run ls -la to confirm you're in the project root directory
• Check if package.json exists to extract project metadata (name, description, version)
• Look for existing README.md to understand current documentation level

Steps

1. Read package.json to extract name, description, version, repository, author, and keywords
2. Identify the main language/framework by checking project files (look for src/, package.json, requirements.txt, go.mod, etc.)
3. Scan the project structure to understand purpose and features
4. Check for existing LICENSE file to include correct license badge
5. Look for .github/workflows/ to document CI/CD setup if present
6. Identify dependencies by reading package.json, Pipfile, Gemfile, or equivalent
7. Create sections in order: Title, Badges, Description, Table of Contents, Installation, Usage, Features, Contributing, License
8. Generate badges for version, license, build status, and other relevant metadata

Code

const fs = require('fs');
const path = require('path');

function generateREADME() {
  // Read package.json
  const packageJson = JSON.parse(fs.readFileSync('package.json', 'utf8'));
  const { name, description, version, author, repository, license, keywords } = packageJson;

  const repoUrl = typeof repository === 'string' ? repository : repository?.url;
  const cleanRepoUrl = repoUrl?.replace(/^git\+/, '').replace(/\.git$/, '') || '';
  const authorName = typeof author === 'string' ? author : author?.name || 'Your Name';

  // Determine license badge
  const licenseText = license || 'MIT';
  const licenseBadge = `[![License: ${licenseText}](https://img.shields.io/badge/License-${licenseText}-yellow.svg)](https://opensource.org/licenses/${licenseText})`;

  // Check for CI/CD workflow
  const workflowPath = '.github/workflows';
  const hasCICD = fs.existsSync(workflowPath);
  const ciBadge = hasCICD ? `[![CI/CD](https://github.com/${cleanRepoUrl.split('/').slice(-2).join('/')}/actions/workflows/tests.yml/badge.svg)](${cleanRepoUrl}/actions)` : '';

  const readme = `# ${name}

[![npm version](https://img.shields.io/npm/v/${name}.svg)](https://www.npmjs.com/package/${name})
${licenseText !== 'UNLICENSED' ? licenseBadge : ''}
${ciBadge}

${description || 'A comprehensive project.

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change