Adept code style

Skill itaywol/adeptability/.adeptability/staging/.claude/skills/adept-code-style

Cross-harness AI skill portability CLI. Author an agent skill once, sync it into Claude Code, Cursor, Copilot, Codex, OpenCode & 45+ AI coding agents. Safety scanner, content-hash drift detection. A package manager / dotfiles for AI coding agent skills.

Install

npx -y skills add itaywol/adeptability --skill adept-code-style

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

8 stars8 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Go code style and conventions for the adept codebase — formatting, linters, error wrapping with sentinels, the composition-root/no-globals rule, and core invariants. Apply when writing or reviewing Go in this repo. (matches: **/*.go)

SKILL.md

2.8 KB, as published. Nobody here has run it

adept code style

Conventions for Go in github.com/itaywol/adeptability. CI enforces formatting and lint; the rest is reviewed.

Formatting & lint (enforced)

gofmt + goimports — tabs for indentation, grouped imports (stdlib / third-party / local). CI fails on any unformatted file.
golangci-lint run (.golangci.yml): errcheck (incl. type assertions), staticcheck, govet, gocritic, revive (every exported symbol needs a doc comment), errorlint, nilerr, bodyclose, prealloc, unconvert, misspell, unused, ineffassign.

Errors

Always wrap with context and %w: fmt.Errorf("clone %s: %w", url, err).
Compare with errors.Is against the sentinels in pkg/adept/errors.go (ErrSkillNotFound, ErrMergeConflict, ErrBudgetOverflow, …). Never match on error strings. Need a new category? Add a sentinel there.
errcheck is strict — handle or explicitly _ = an ignored error, and say why if it isn't obvious. Don't drop an error that loses data.

Structure

Composition root, no globals. Concrete implementations are wired behind interfaces into *Deps in internal/cli/deps.go. No package-level mutable state, no init() side effects. Take dependencies as parameters so code is testable with fakes/mocks.
pkg/adept is types-only. Keep it dependency-light and stable; behavior lives in internal/. (Example: SkillIDPattern is a string in pkg/adept, compiled in internal/canonical — don't add a regexp import to pkg/adept.)
Doc comments are full sentences starting with the symbol name (// NewRoot builds …).

Readability

Small, single-purpose functions; prefer early returns over deep nesting.
Name things for what they are; avoid one-letter names outside tight loops/receivers.
No magic numbers/strings — name on-disk paths and limits as constants (see pkg/adept/constants.go).
Comments explain why, not what. Keep them in sync with the code — a stale comment is a bug.

Invariants you must not break

Identity is (id, content-hash) — no version numbers as a sync signal.
Secrets never written to disk — API keys come from the environment at call time.
Harness models differ (per-skill / single-file / aggregator) — renderers and importers must respect each; aggregators parse their own section markers and honor byte budgets.
Canonical layout <root>/skills/<id>/SKILL.md; the directory name is the authoritative id.