mgajewskik/crafting-effective-readmes
skills/crafting-effective-readmes/SKILL.md
Use when writing or improving README files. Not all READMEs are the same — provides templates and guidance matched to your audience and project type.
$ install --global
skillsauthnpx skillsauth add mgajewskik/opencode-config crafting-effective-readmesInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 30, 2026, 7:04 AM11.2s14 files scanned
SKILL.md
- name:
- crafting-effective-readmes
- description:
- Use when writing or improving README files. Not all READMEs are the same — provides templates and guidance matched to your audience and project type.
Crafting Effective READMEs
Overview
READMEs answer questions your audience will have. Different audiences need different information - a contributor to an OSS project needs different context than future-you opening a config folder.
Always ask: Who will read this, and what do they need to know?
Process
Step 1: Identify the Task
Ask: "What README task are you working on?"
| Task | When | |------|------| | Creating | New project, no README yet | | Adding | Need to document something new | | Updating | Capabilities changed, content is stale | | Reviewing | Checking if README is still accurate |
Step 2: Task-Specific Questions
Creating initial README:
- What type of project? (see Project Types below)
- What problem does this solve in one sentence?
- What's the quickest path to "it works"?
- Anything notable to highlight?
Adding a section:
- What needs documenting?
- Where should it go in the existing structure?
- Who needs this info most?
Updating existing content:
- What changed?
- Read current README, identify stale sections
- Propose specific edits
Reviewing/refreshing:
- Read current README
- Check against actual project state (package.json, main files, etc.)
- Flag outdated sections
- Update "Last reviewed" date if present
Step 3: Always Ask
After drafting, ask: "Anything else to highlight or include that I might have missed?"
Project Types
| Type | Audience | Key Sections | Template |
|------|----------|--------------|----------|
| Open Source | Contributors, users worldwide | Install, Usage, Contributing, License | templates/oss.md |
| Personal | Future you, portfolio viewers | What it does, Tech stack, Learnings | templates/personal.md |
| Internal | Teammates, new hires | Setup, Architecture, Runbooks | templates/internal.md |
| Config | Future you (confused) | What's here, Why, How to extend, Gotchas | templates/xdg-config.md |
Ask the user if unclear. Don't assume OSS defaults for everything.
Essential Sections (All Types)
Every README needs at minimum:
- Name - Self-explanatory title
- Description - What + why in 1-2 sentences
- Usage - How to use it (examples help)
References
section-checklist.md- Which sections to include by project typestyle-guide.md- Common README mistakes and prose guidanceusing-references.md- Guide to deeper reference materials
Related Skills
mgajewskik/dossier
documentation
VerifiedTrustedCommunity
Create senior-level deep research dossiers and roadmap companions. Use when the user asks for a dossier, senior research, deep research, in-depth research, mental models for a topic, senior perspective on a topic, how something actually works, ramp up on a topic, architectural deep dive, tradeoffs, failure modes, or what a senior would notice. Produces current-directory research-* and roadmap-* markdown artifacts, not a tutorial or short summary.
3SKILL.mdUpdated May 8, 2026
mgajewskik/knative
development
VerifiedTrustedCommunity
Senior-level Knative and OpenShift Serverless guidance for Serving, Eventing, Functions, autoscaling, scale-to-zero, CloudEvents, RabbitMQ/Kafka sources, Lambda migration, Harbor/OCI images, debugging, operations, and production rollout. Use when working with Knative Service, Revision, Route, KPA, activator, queue-proxy, Broker, Trigger, Source, Sink, kn func, OpenShift Serverless, Kourier, eventing-rabbitmq, Knative Kafka, or serverless workloads on Kubernetes/OpenShift.
3SKILL.mdUpdated May 4, 2026
mgajewskik/rhel
development
VerifiedTrustedCommunity
Senior-level RHEL-family Linux operations. Use when running, debugging, hardening, patching, installing, upgrading, or operating Red Hat Enterprise Linux, Rocky Linux, AlmaLinux, CentOS Stream, Fedora-as-upstream, or related enterprise Linux hosts: systemd, RPM/DNF, SELinux, NetworkManager, firewalld, storage, kernel/kdump, FIPS/STIG, Satellite, IdM, Podman, bootc, air-gapped fleets.
3SKILL.mdUpdated Apr 30, 2026
mgajewskik/proxmox
development
VerifiedTrustedCommunity
Senior-level Proxmox VE guidance for VM creation, templates, storage, ZFS, Ceph, networking, clusters, HA, PBS backups, debugging, upgrades, security, and production/homelab operations. Use when working with Proxmox, PVE, Proxmox VE, qm, pct, pvesm, pvecm, pmxcfs, HA manager, Proxmox Backup Server, VM migration, Proxmox incidents, or Ceph/ZFS/Corosync/VLAN bridges in a Proxmox VE context.
3SKILL.mdUpdated Apr 30, 2026