feat: improve skill scores across standards repo

[yogesh-tessl]

Hey @williamzujkowski 👋

67 skills with progressive disclosure that cuts token usage by 91–99.6%. That's a genuinely clever loading architecture. The fact that you've built NIST-aligned compliance checks alongside practical coding standards for 8+ languages shows this isn't just a collection, it's a system. Wanted to suggest a few improvements to the SKILL.md.

I ran your skills through tessl skill review at work and found some targeted improvements. Here's the full before/after:

Changes Summary

• Rewrote all 5 skill descriptions with action verbs, specific capabilities, and explicit "Use when..." trigger clauses
• Removed identical generic boilerplate from all skills (Common Pitfalls, Integration Points, TODO examples)
• Replaced architecture/patterns hollow template with concrete implementations (Hexagonal, CQRS, Event-Driven, Circuit Breaker)
• Removed redundant sections (duplicate Related Skills, "When to Use This Skill", self-referential metadata)
• Used quoted string format for all descriptions

Honest disclosure. I work at https://github.com/tesslio where we build tooling around skills like these. Not a pitch - just saw room for improvement and wanted to contribute.

Want to self-improve your skills? Just point your agent (Claude Code, Codex, etc.) at this Tessl guide (https://docs.tessl.io/evaluate/optimize-a-skill-using-best-practices) and ask it to optimize your skill. Ping me - @yogesh-tessl (https://github.com/yogesh-tessl) - if you hit any snags.

Thanks in advance 🙏

[williamzujkowski]

Reviewed this on behalf of @williamzujkowski (Claude Code assistant, authorized).

Summary

Recommendation: accept with minor consideration. The changes are high-quality, substantive, and represent a clear improvement over the existing generic boilerplate. Net change: +254 / -473 (removed more than added — good signal for removing template noise).

What's genuinely better

1. Description rewrites — the new descriptions actually tell you when to use the skill ("Use when the user asks about system design, hexagonal architecture..."). The old ones were tautological ("Patterns standards for patterns in Architecture environments").

2. Concrete code examples — replaced "Core Principles: Follow industry-standard patterns" with actual TypeScript implementations of Hexagonal, CQRS, Event-Driven, Circuit Breaker patterns. This is what a skill should teach.

3. Pattern Selection Guide table — trade-off documentation (when to use X vs Y) that wasn't there before.

4. Removed redundant sections — the old files had duplicate "Related Skills", self-referential "When to Use This Skill" blocks, and TODO placeholders. All cleaned up.

Concerns (none blocking)

• Vendor affiliation disclosed — @yogesh-tessl is from https://github.com/tesslio and used their tessl skill review tool. Disclosure is upfront; no pitch embedded in the changes. This seems like good-faith contribution.

• Merge state is UNSTABLE — no CI is running on this branch (no checks reported). Worth verifying the markdown renders cleanly and any skill indexers (if any) still work before merging.

• Only 5 of 67 skills covered — this is a sample, not a full sweep. Follow-up opportunity: if the @williamzujkowski/standards repo adopts this pattern, apply to the remaining 62 using the same approach.

For the maintainer

This PR would improve your SKILL.md quality across 5 high-traffic skills with concrete, testable code examples. The vendor disclosure is clean. Worth merging, then considering a follow-up issue to extend to the other 62 skills with the same pattern.

Not going to merge this myself since it's an external contributor — leaving that call to @williamzujkowski.

[williamzujkowski]

CI Polish — ready-to-apply patch

Tried to push directly to your fork but I don't have write access. Here's a clean patch with the fixes. Apply with git apply pr82-fix.patch or cherry-pick.

3 issues fixed

1. MD024 duplicate heading in `skills/devops/ci-cd/SKILL.md` — two `### Related Skills` sections (lines 749 and 782). Consolidated into one deduplicated list.
2. pretty-format-json — `reports/generated/structure-audit.json` wasn't 2-space indented. Reformatted.
3. markdownlint — `CODE_OF_CONDUCT.md` needed blank line after a heading.

Patch

```diff
From ecf4210 Fri Apr 17 22:51:17 2026
Subject: fix(skills): pre-commit + MkDocs fixes to pass CI

diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -8,6 +8,7 @@ community a harassment-free experience for everyone.

Our Standards

Examples of behavior that contributes to a positive environment:
+

• Using welcoming and inclusive language

diff --git a/reports/generated/structure-audit.json b/reports/generated/structure-audit.json
@@ -1,6 +1,6 @@
{

• "broken_links": 0,
• "orphans": 0,
• "hub_violations": 0,
• "timestamp": "2026-01-01T03:29:23.909136"

• "broken_links": 0,
• "hub_violations": 0,
• "orphans": 0,
• "timestamp": "2026-01-01T03:29:23.909136"
  }

diff --git a/skills/devops/ci-cd/SKILL.md b/skills/devops/ci-cd/SKILL.md
@@ -746,14 +746,6 @@
- run: ./deploy.sh ${{ inputs.environment }}
```

-### Related Skills

-- kubernetes - Container orchestration for deployments
-- docker-standards - Container image best practices
-- security-scanning - Security vulnerability detection
-- monitoring - Production observability

Security Best Practices

@@ -775,5 +767,7 @@

Related Skills

• kubernetes - Container orchestration for deployments
  +- docker-standards - Container image best practices
  +- security-scanning - Security vulnerability detection
• Infrastructure As Code - Infrastructure provisioning
• Monitoring Observability - Production observability
  ```

After applying, this should get the 3 failing checks (Build MkDocs site, Pre-commit Checks) green. The "welcome" check failure is bot-permission and harmless.

Ping me if the patch doesn't apply cleanly and I can reformat.