pragmatic-writing — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited pragmatic-writing (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
Writing style modeled on the masters of technical communication: Andy Hunt, Dave Thomas (The Pragmatic Programmer), and Joel Spolsky (Joel on Software). This skill transforms technical content into engaging, memorable prose.
This skill applies when:
"The difference between 'almost right' and 'right' is the difference between the lightning bug and the lightning." — Mark Twain (quoted by Pragmatic Programmers)
Technical writing doesn't have to be dry. The best technical writers make complex ideas feel obvious, use concrete examples before abstract theory, and treat the reader as a smart colleague.
Reference the complete technique guide at techniques.md.
Always start with a concrete example, then extract the principle.
❌ "Dependency injection is a design pattern where dependencies are passed
to objects rather than created by them."
✅ "Imagine your class needs a database connection. You could create it
yourself:
def initialize
@db = Database.new("localhost:5432")
end
But now your class is stuck with that exact database. What if you
want to test with a fake one? What if production uses a different host?
Instead, accept it as a parameter:
def initialize(db)
@db = db
end
That's dependency injection. Simple."Map abstract concepts to physical experiences readers already understand.
See examples.md for analogy patterns:
Write like you're explaining to a smart colleague at a whiteboard.
Markers of conversational register:
Use humor strategically, not decoratively:
Build to moments of realization:
Like this.
Code examples should:
After a concrete exploration, box the principle:
Tip 23: Always Design for Concurrency Allow for concurrency, and you will design cleaner interfaces with fewer assumptions.
When discussing pitfalls:
See anti-patterns.md for common technical writing mistakes.
End by connecting back to the opening example or question. Close the loop.
Use: specific, concrete, everyday words Avoid: jargon without explanation, buzzwords, corporate-speak
Before publishing, verify:
~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.