SKILL.md
README.md Expert
Level 1: Quick Reference
Core Capabilities
- Professional Templates: Industry-standard README structures
- Dynamic Analysis: Automatic project detection and analysis
- Multiple Languages: Support for various programming projects
- Visual Elements: Badges, diagrams, and structured formatting
- Best Practices: SEO optimization and engagement techniques
- Automated Generation: Script-based README creation
Quick Setup Examples
# Basic README generation
from readme_expert import ReadmeGenerator
generator = ReadmeGenerator()
readme_content = generator.generate_basic_readme(
project_name="My Awesome Project",
description="A revolutionary application that changes everything",
author="Your Name",
license="MIT"
)
# Save to file
with open("README.md", "w") as f:
f.write(readme_content)# Advanced README with automatic project analysis
generator = ReadmeGenerator()
readme_content = generator.generate_comprehensive_readme(
project_path="./",
include_sections=[
"installation", "usage", "contributing", "license", "changelog"
],
style="professional",
include_badges=True,
include_diagrams=True
)Level 2: Core Patterns
Template Engine Architecture
class ReadmeTemplate:
def __init__(self):
self.templates = self._load_templates()
self.section_generators = {
'installation': self._generate_installation,
'usage': self._generate_usage,
'contributing': self._generate_contributing,
'license': self._generate_license,
'changelog': self._generate_changelog,
'api': self._generate_api_docs,
'testing': self._generate_testing,
'deployment': self._generate_deployment
}
def generate_readme(self, project_info: Dict[str, Any],
template_type: str = 'professional',
sections: List[str] = None) -> str:
"""Generate README from template"""
template = self.templates.get(template_type, self.templates['professional'])
# Generate badges
badges = self._generate_badges(project_info)
# Generate sections
generated_sections = {}
if sections:
for section in sections:
if section in self.section_generators:
generated_sections[f"{section}_section"] = self.section_generators[section](project_info)
# Fill template
readme_content = template.format(
project_name=project_info.get('name', 'Project Name'),
description=project_info.get('description', 'Project description'),
badges=badges,
features_section=generated_sections.get('features', ''),
installation_section=generated_sections.get('installation', ''),
usage_section=generated_sections.get('usage', ''),
api_section=generated_sections.get('api', ''),
testing_section=generated_sections.get('testing', ''),
deployment_section=generated_sections.get('deployment', ''),
contributing_section=generated_sections.get('contributing', ''),
changelog_section=generated_sections.get('changelog', ''),
license_section=generated_sections.get('license', '')
)
return readme_contentProject Analysis System
class ProjectAnalyzer:
def __init__(self):
self.indicators = {
'package.json': self._analyze_nodejs_project,
'requirements.txt': self._analyze_python_project,
'Cargo.toml': self._analyze_rust_project,
'go.mod': self._analyze_go_project,
'pom.xml': self._analyze_java_project
}
def analyze_project(self, project_path: str) -> Dict[str, Any]:
"""Analyze project and extract information"""
project_info = {
'path': project_path,
'name': self._extract_project_name(project_path),
'description': self._extract_description(project_path),
'type': 'unknown',
'dependencies': [],
'version': '1.0.0',
'license': None,
'repository': None,
'author': None
}
# Detect project type
for indicator_file, analyzer in self.indicators.items():
file_path = os.path.join(project_path, indicator_file)
if os.path.exists(file_path):
specific_info = analyzer(file_path)
project_info.update(specific_info)
break
return project_infoLevel 3: Advanced Implementation
Specialized Domain Templates
API Service Template
def _api_service_template(self, project_info: Dict[str, Any]) -> str:
return f"""
# {project_info.get('name', 'API Service')}
{self._generate_api_badges(project_info)}
## Features
- RESTful API design
- JWT authentication
- Rate limiting
- Comprehensive error handling
## API Endpoints
### Authentication
#### POST /api/auth/login
Authenticate user and return JWT token.
**Request Body:**{{ "email": "[email protected]", "password": "password123" }}
## Installation
Clone the repository
git clone {projectinfo.get('repositoryurl', '')}
Install dependencies
{self.getinstallcommand(projectinfo)}
Set up environment variables
cp .env.example .env
Run database migrations
{self.getmigrationcommand(projectinfo)}
Start the server
{self.getstartcommand(projectinfo)}
"""Web Application Template
def _web_app_template(self, project_info: Dict[str, Any]) -> str:
return f"""
# {project_info.get('name', 'Web Application')}
{self._generate_web_app_badges(project_info)}
## Features
- 🚀 **Modern UI/UX**: Built with latest frontend technologies
- 📱 **Responsive Design**: Works on all devices
- 🔐 **Authentication**: Secure user authentication
- ⚡ **Performance**: Optimized for speed
## Technology Stack
### Frontend
- **Framework**: {project_info.get('frontend_framework', 'React')}
- **Styling**: {project_info.get('styling', 'Tailwind CSS')}
- **State Management**: {project_info.get('state_management', 'Redux Toolkit')}
### Backend
- **Runtime**: {project_info.get('backend_runtime', 'Node.js')}
- **Framework**: {project_info.get('backend_framework', 'Express.js')}
- **Database**: {project_info.get('database', 'PostgreSQL')}
## Quick Start
Clone and install
git clone {projectinfo.get('repositoryurl', '')} cd {project_info.get('name', 'my-app')} npm install
Set up environment
cp .env.example .env npm run db:setup
Start development
npm run dev
"""Automated README Generator
class ReadmeGenerator:
def __init__(self):
self.template_engine = ReadmeTemplate()
self.project_analyzer = ProjectAnalyzer()
def generate_comprehensive_readme(self, project_path: str = "./",
template_type: str = 'professional',
sections: List[str] = None,
**overrides) -> str:
"""Generate a comprehensive README by analyzing the project"""
# Analyze project
project_info = self.project_analyzer.analyze_project(project_path)
# Apply overrides
project_info.update(overrides)
# Set default sections
if sections is None:
sections = [
'installation', 'usage', 'api', 'testing',
'deployment', 'contributing', 'license'
]
# Generate README
readme_content = self.template_engine.generate_readme(
project_info=project_info,
template_type=template_type,
sections=sections
)
return readme_content
def validate_readme(self, readme_path: str = "README.md") -> Dict[str, Any]:
"""Validate README content for best practices"""
if not os.path.exists(readme_path):
return {'valid': False, 'errors': ['README.md file not found']}
with open(readme_path, 'r', encoding='utf-8') as f:
content = f.read()
validation_results = {
'valid': True,
'warnings': [],
'suggestions': [],
'stats': {
'character_count': len(content),
'line_count': len(content.split('\n')),
'word_count': len(content.split())
}
}
# Check for required sections
required_sections = ['installation', 'usage']
for section in required_sections:
if f"## {section.title()}" not in content:
validation_results['warnings'].append(f"Missing '{section}' section")
# Check for badges
if '![' not in content:
validation_results['suggestions'].append("Consider adding badges for build status, license, etc.")
# Check for code examples
if '```' not in content:
validation_results['suggestions'].append("Add code examples to demonstrate usage")
return validation_resultsLevel 4: Reference & Integration
Badge Generation System
def _generate_badges(self, project_info: Dict[str, Any]) -> str:
"""Generate project badges"""
badges = []
# Build status badge
if project_info.get('ci_platform') and project_info.get('repository'):
ci_badge = self._get_ci_badge(project_info['ci_platform'], project_info['repository'])
badges.append(ci_badge)
# License badge
if project_info.get('license'):
license_badge = f"}-blue.svg)"
badges.append(license_badge)
# Version badge
if project_info.get('version'):
version_badge = f""
badges.append(version_badge)
return " ".join(badges) if badges else ""
def _get_ci_badge(self, ci_platform: str, repository: str) -> str:
"""Get CI platform badge"""
ci_badges = {
'github': f"",
'travis': f"",
'circleci': f"",
'gitlab': f""
}
return ci_badges.get(ci_platform, "")Installation Command Generator
def _generate_installation(self, project_info: Dict[str, Any]) -> str:
"""Generate installation section"""
project_type = project_info.get('type', 'nodejs')
install_commands = {
'nodejs': """Using npm
npm install {package_name}
Using yarn
yarn add {package_name}
""".strip(),
'python': """Using pip
pip install {package_name}
Using conda
conda install {package_name}
""".strip(),
'rust': """Using Cargo
cargo install {package_name}
Or add to Cargo.toml
[dependencies] {package_name} = "{version}"
""".strip(),
'go': """Using go get
go get {package_path}
Or add to go.mod
require {package_path} {version}
""".strip()
}
template = install_commands.get(project_type, install_commands['nodejs'])
return template.format(
package_name=project_info.get('package_name', project_info.get('name', '')),
package_path=project_info.get('package_path', ''),
version=project_info.get('version', 'latest')
)Related Skills
- moai-document-processing: Document generation and formatting
- moai-domain-testing: Documentation testing and validation
- moai-core-workflow: README generation automation
- moai-essentials-refactor: Content optimization and refactoring
Quick Start Checklist
- Analyze project structure and dependencies
- Choose appropriate README template
- Generate badges for project status
- Include installation and usage instructions
- Add API documentation if applicable
- Include testing and deployment guides
- Add contributing guidelines
- Validate README for best practices
README Best Practices
- Clear Title: Make the project name prominent and descriptive
- Badges: Add relevant badges for status and information
- Table of Contents: Help users navigate long READMEs
- Installation: Provide clear, copy-pasteable installation instructions
- Usage Examples: Include practical examples that work out-of-the-box
- Screenshots: Add visual elements for better understanding
- Contributing: Encourage contributions with clear guidelines
- License: Clearly state the project license
- Links: Include links to documentation, issues, and discussions
- Regular Updates: Keep README updated with project changes
README.md Expert - Create professional, comprehensive README files that effectively showcase your projects and follow industry best practices.