skilld
All skills
softaworks avatar

/crafting-effective-readmes

@1c0662a
by softaworkssoftaworks/agent-toolkit2.5k stars
230

Use when writing or improving README files. Not all READMEs are the same — provides templates and guidance matched to your audience and project type.

Ask your Agent

Use this Skill: https://skilld.dev/gh/softaworks/agent-toolkit/crafting-effective-readmes

This session only. Nothing lands on disk.

templatesxdg-config.md

≈370 tokens on demand. Your agent reads this file only when SKILL.md points to it.

Config Directory README Template

Use this template for XDG config directories, dotfiles, script folders, and any local directory you'll return to later wondering "what is this?"

The audience is future-you, probably confused.

[Tool/Directory Name] Config

Last reviewed: [YYYY-MM-DD]

[One sentence: what this directory configures and why you have custom config]

What's Here

Path Purpose
[file-or-dir] [What it does]
[file-or-dir] [What it does]
[file-or-dir] [What it does]

[Subdirectory 1] (if complex enough to warrant detail)

[Brief explanation of what's in this subdirectory]

[Subdirectory 2]

[Brief explanation]

Why This Setup

[1-2 paragraphs explaining your philosophy or goals for this config. What problems were you solving? What workflow are you optimizing for?]

How to Extend

Adding a new [thing]

  1. [Step 1]
  2. [Step 2]
  3. [Step 3]

Adding a new [other thing]

  1. [Steps]

Dependencies

[What needs to be installed for this config to work]

[Install commands if applicable]

Gotchas

  • [Thing that will confuse future-you]
  • [Non-obvious behavior]
  • [Files that shouldn't be edited directly]
  • [Order dependencies or load sequences]

Sync/Backup

[How this config is backed up or synced across machines, if applicable]

Related

  • [Link to tool's official docs]
  • [Link to your dotfiles repo if this is part of it]
  • [Other relevant resources]

Source: SKILL.md on GitHub

Third-party checks

No alerts16d5 checks · Risk SAFE
  • Gen Agent Trust Hub16d

    The skill is a collection of Markdown templates and documentation guidelines designed to help generate README files. It contains no executable code, automation scripts, or sensitive data access patterns.

  • Socket16d

    No alerts

  • Snyk16d

    Risk: LOW · No issues

  • Runlayer7mo

    14 files scanned · No issues

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at 1c0662a. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 2 months ago.

Dormantupdated 9 months ago

Topics

  • Documentation
  • readme
  • templates
  • open-source
  • contributing
  • project-setup
  • technical-writing

README badge

README badge for softaworks/agent-toolkit/crafting-effective-readmes

What it does

This skill guides you through writing or updating README files by identifying your audience and task type, then providing templates and section checklists matched to whether you're documenting an open source project, internal tool, personal project, or config folder.

Generated from the current SKILL.md.

Frequently asked

Does this skill work for all project types?
Yes. The skill includes templates and guidance for open source, personal projects, internal tools, and config folders. Ask the skill which project type you're working on if it's not clear.
Can this skill help update an existing README?
Yes. The skill can identify stale sections by comparing your README to the actual project state (package.json, main files, etc.) and propose specific edits.
Does this skill provide templates?
Yes. It includes templates for OSS projects, personal projects, internal tools, and config folders, plus a section checklist and style guide.
What if I'm not sure what type of README I'm writing?
The skill asks you to identify your audience first — contributors, teammates, future you, or portfolio viewers — and matches guidance to that audience rather than assuming defaults.

Generated from the current SKILL.md. These answers refresh after source changes.