golang-swagger

Golang OpenAPI/Swagger documentation with swaggo/swag — annotation comments (@Summary, @Param, @Success, @Router, @Security), swag init code generation, framework integrations (gin, echo, fiber, chi, net/http), security definitions (Bearer/JWT, OAuth2, API key), and struct tags (swaggertype, enums, example, swaggerignore). Apply when adding or maintaining Swagger/OpenAPI docs in a Go project, or when the codebase imports github.com/swaggo/swag, github.com/swaggo/gin-swagger, github.com/swaggo/echo-swagger, github.com/swaggo/http-swagger, or github.com/swaggo/files.

Quality

87%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

82%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is an actionable, well-structured reference with executable code and a properly offloaded CLI reference file. Its main gaps are a missing explicit validation checkpoint in the setup workflow and a little inline material that could live in references.

Suggestions

Add an explicit validation step to the Setup workflow, e.g. 'After swag init, open /swagger/index.html and confirm the spec and security lock icons render; if empty, check the blank docs import.'

Consider moving the full Security Definitions and Struct Tags reference blocks into a separate references file, keeping only a minimal example inline in SKILL.md.

Trim the 'Persona' and 'Modes' intro lines or fold them into a single sentence to reduce non-actionable tokens.

Dimension	Reasoning	Score
Conciseness	The body is dense and reference-style, assuming Claude's knowledge of Go and Swagger with minimal concept explanation, but the 'Persona' and 'Modes' flavor lines and a few orienting sentences could be trimmed.	4 / 5
Actionability	Provides copy-paste-ready commands ('swag init -g cmd/api/main.go'), framework wiring snippets for all five frameworks, struct-tag examples, and a common-mistakes table — fully executable guidance covering the common cases.	5 / 5
Workflow Clarity	The Setup section gives a clear three-step sequence with concrete commands and the mistakes table supplies error-recovery guidance, but the main flow lacks an explicit validation checkpoint (e.g. 'confirm the UI loads at /swagger/index.html after regenerating').	4 / 5
Progressive Disclosure	Content is well-organized with section headers and a clearly signaled, verified one-level-deep reference ('[Full CLI reference](references/swag-cli.md)' pointing to a real file), though some inline reference-like material (full security definitions, struct tags) could be split out.	4 / 5
	Total	17 / 20 Passed

Description

92%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is specific, complete, and distinctive, clearly stating both the skill's capabilities and its trigger conditions with named packages. Only minor synonym coverage in trigger terms keeps it from a perfect mark.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete capabilities — 'annotation comments (@Summary, @Param, @Success, @Router, @Security)', 'swag init code generation', 'framework integrations (gin, echo, fiber, chi, net/http)', 'security definitions', and 'struct tags' — giving comprehensive coverage of the skill's actions.	5 / 5
Completeness	Explicitly answers both what ('Golang OpenAPI/Swagger documentation with swaggo/swag — ...') and when ('Apply when adding or maintaining Swagger/OpenAPI docs in a Go project, or when the codebase imports ...') with concrete trigger phrases.	5 / 5
Trigger Term Quality	Includes natural terms like 'Swagger/OpenAPI docs' and 'Go project' plus concrete import-path triggers, but misses common synonyms a user might say such as 'REST API documentation' or 'API docs'.	4 / 5
Distinctiveness Conflict Risk	Tightly scoped to swaggo/swag for Go with named packages, creating a clear niche with minimal conflict risk against other skills.	5 / 5
	Total	19 / 20 Passed

Validation

87%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
allowed_tools_field	'allowed-tools' contains unusual tool name(s)	Warning
metadata_field	'metadata' should map string keys to string values	Warning

	Total	14 / 16 Passed

Repository: samber/cc-skills-golang
Path: skills/golang-swagger/SKILL.md
Commit: 19a0626

Reviewed: 6 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.