A curated set of AI skills for developing and contributing to ThunderID

[ayshsandu]

Proposal

As more of us develop ThunderID with AI assistants, our conventions only help when the assistant loads the right guidance at the right moment. Skills are built for exactly that: a short SKILL.md (name + one-line "use when…" description) that the assistant pulls in on demand when a task matches.

We already have contributor skills (db, console) under .agent/skills/, but that path isn't auto-discovered by Claude Code, and some of the guidance (observability, debugging, frontend practices) lives in the docs agent never loads on its own.

Current state (context)

The contributor guidance is spread across three mechanisms that don't reinforce each other:

CLAUDE.md ──@──> AGENTS.md ──┬──> "Agent Skills"      ──> .agent/skills/{db,console}/SKILL.md
                             ├──> "Agent Guidance Index" ──> .agent/skills/db  (console dropped)
                             └──> "Contributing Guidelines" ──> {backend,frontend}/overview.mdx
                                                                 (dead-ends — no links onward)

The following are available in the docs for human developers, but not optimized for coding assistants

docs/content/.../contributing-code/
   backend-development/overview.mdx*   observability.mdx      (orphaned, 231 lines)
   frontend-development/overview.mdx*   best-practices.mdx     (orphaned, 39 lines)
                                          conventions.mdx        (orphaned, 12 lines)
   debugging.mdx (orphaned, 238 lines)   
   pull-request-workflow.mdx (orphaned, 101 lines)

Suggestions

1. Make contributor skills first-class (auto-loaded / invokable) instead of prose; an agent has to be pointed at.
2. Convert orphaned guidance into small, trigger-mapped skills.
3. Keep one source of truth per rule — skill or doc, not multiple drifting copies.

Possible skills

Starter set — keep it small, each mapped to a real task trigger:

Skill	Source material	Use when…
db (exists)	.agent/skills/db	changing schema, queries, store constants
console (exists)	.agent/skills/console	navigating/testing the console UI
backend-development (new)	backend overview.mdx + logging rules	adding/modifying a Go domain package
frontend-development (new)	frontend overview.mdx + conventions.mdx + best-practices.mdx	covers writing ui features UX guidelines: Oxygen UI component patterns, hook conventions, i18n usage in components, and the custom eslint-plugin/prettier rules.
│ api-design *(new)	TODO	adding/changing an endpoint, request/response shape, or error in the OpenAPI specs under api/ │
observability (new)	observability.mdx	adding a backend component that emits events/traces
│ documentation *(new)	TODO	creating/editing docs content (.mdx) or doc components under docs/
pr-workflow (new, optional)	pull-request-workflow.mdx + AGENTS.md Git/PR rules	preparing a commit/PR
feature development (new)	Compliments feature scpec #3292	How to approach and what to cover in end-to-end feature, covering completeness designing, backend, api, frontend, SDK, doc

[ayshsandu]

Sub issue - #3796

[darshanasbg]

+1 for the proposal in general..

@senthalan and I was planning on to have dedicated effort on improving the contributor-dev-ex and these suggestions seems falls to that overall work..

This involves finalizing the development process, deliverables & tools to use at each step/deliverable.

Still, without blocking to that effort, we can start with the most needed ones that specially require the consistency, like the docs and UI skills.