Improve/skill review optimization

[yogesh-tessl]

Hey @nextlevelshit 👋

40 skills powering an agent orchestration layer with declarative per-persona scoping and contract-validated handoffs. The "just the right amount of guardrails" philosophy really comes through in how you've structured skill boundaries across DDD, spec-driven development, and the Wave-specific context skills. 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:

What changed

All three skills had the same core issues flagged by the evaluator:

• Descriptions lacked trigger guidance - added explicit Use when... clauses with natural keywords users would actually type, so Claude reliably selects the right skill
• Descriptions were topic lists, not action descriptions - reframed as concrete verbs ("designs bounded contexts", "evaluates system architectures") instead of abstract nouns ("DDD patterns", "system design")
• Content explained concepts Claude already knows - removed textbook definitions (what entities are, what microservices are) and replaced with actionable workflows and executable code examples
• No structured workflows - added step-by-step workflows with validation checkpoints for each skill's core task (designing an aggregate, making an architecture decision, building an agentic system)
• Code examples were incomplete scaffolds - replaced with fully executable Go patterns (aggregate roots with domain events, repository interfaces, self-improving loops)

Skill-specific changes:

• ddd: Replaced conceptual bullet-point definitions with a concrete aggregate design workflow, executable Go code for aggregate roots with domain events, and a repository interface pattern
• agentic-coding: Removed buzzword-heavy concept sections, added a clear 5-step workflow for building agentic systems, kept the self-improving loop pattern
• software-architecture: Replaced pattern/concept lists with a structured architecture decision workflow, kept the Circuit Breaker and Event Bus code examples plus the ADR template

I kept this PR focused on the 3 skills with the biggest improvements to keep the diff reviewable. Happy to follow up with the rest in a separate PR if you'd like.

Honest disclosure. I work at @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 and ask it to optimize your skill. Ping me - @yogesh-tessl - if you hit any snags.

Thanks in advance 🙏

[nextlevelshit]

Thanks for the contribution, @yogesh-tessl. Net assessment: this is a clear improvement for skill-picker trigger matching — shifting from topic-list descriptions to action-verb phrasing with explicit "Use when..." clauses aligns with how Claude's skill selection actually works, and the removed textbook content (entity/value-object definitions, "what are microservices") is genuinely redundant with Claude's training knowledge.

What works well

• All three descriptions now lead with verbs ("designs bounded contexts", "evaluates system architectures", "builds multi-agent coding systems") and include explicit trigger phrases. Lengths all stay under ~320 chars.
• The new DDD Go example (skills/ddd/SKILL.md:30-58) is syntactically valid, idiomatic Go — aggregate root with events slice, defensive invariant checks in Confirm(), and a clean repository interface. This is a genuine upgrade over the removed bullet lists.
• Workflows are concrete and non-fluffy. The "validate: can each command complete in a single transaction?" check in the DDD workflow is the kind of thing Claude can actually use mid-task.
• Dropping the Python AgentOrchestrator scaffold and JavaScript goal-decomposition stub from skills/agentic-coding/SKILL.md is a correct call — they were incomplete (bodies = pass) and this is a Go-first codebase.
• No Wave-specific context was stripped — these were already generic conceptual skills. references/full-reference.md links all preserved.

Minor nits (non-blocking)

• Frontmatter style: all other skills/*/SKILL.md descriptions in this repo are unquoted YAML strings; the three changed files now use double-quoted strings. Not wrong, just inconsistent. Follow-up welcome but not required.
• skills/software-architecture/SKILL.md: the Circuit Breaker example stays in Python while the rest of the repo leans Go. Out of scope for this PR, but a future pass could Go-ify it to match the DDD treatment.
• Consider whether ddd's Order.events field should be cleared after publish (or note that DomainEvents() is intended to be drained by infrastructure) — as-is, repeat calls return the same events. Minor, and arguably fine as a skeleton example.

Regarding tessl skill review: your disclosure in the PR body is appreciated. The changes themselves contain no promotional content, so that's a clean contribution. Approving.

Dismissing auto-approval — per admin policy, only the repo admin can approve external contributions. Please await admin review.