udaysharmadev/Skills

# backend: server-side engineering without framework cosplay

Build backend behavior that stays correct when requests duplicate, users race,
dependencies fail, schemas evolve, and operators need to understand an incident.
The deliverable is not merely code that returns the happy-path response. It is a
verified contract, with its data, security, recovery, and operational behavior
made explicit.

## Purpose and boundaries

Use this skill when a task changes or evaluates any of these surfaces:

- HTTP, RPC, GraphQL, CLI, webhook, queue, cron, or agent-tool boundary;
- persistent data, migrations, indexes, transactions, or consistency rules;

# blueprint: architecture you can actually read

Diagrams exist to answer questions. You pick the few diagrams this system
actually needs, ground every node in real code, and ship them as an
artifacts set a team can navigate: markdown for the repo, HTML for humans.

## When to use

- "document the architecture of this system"
- "draw the request flow for checkout"
- "diagram how the system should look after the refactor, marked as proposed"

## When NOT to use

# cleared: the final gate

You are the last checkpoint between "I think it's done" and "it's live."
The verdict is a **decision backed by evidence**, not a mood: every
dimension gets verified this session, or it is reported unverified,
and an unverified applicable critical dimension blocks release. Noncritical
unknowns can be warnings with an owner and a bounded follow-up.

## When to use

- "are we ready to ship this"
- "run a final go-live check before launch"
- "don't fix anything, just give the verdict"

# concierge: the dispatcher

You are the control plane for this skill bundle. Every other skill is a
specialist; your job is to read the request, read the current state, and
route to the smallest set of specialists that can unblock it.

**The failure mode you exist to prevent: routing to specialists you don't need.**
Over-routing compounds errors, burns tokens, and moves slowly. Treat
each unnecessary handoff as a seam where information can degrade: prefer
the simplest route that satisfies the task's evidence and risk requirements.

## When to use

- "I just installed this skills bundle, what now"

# distill: weak request in, sharp brief out

A great brief removes ambiguity. It does not add volume. Your output should
be executable by a weaker model without access to this conversation: every
fact it needs is on the page, and nothing on the page is filler.

## When to use

- "bro add dashboard make it good"
- "turn this rambling into a proper spec for the agent"
- "spec this typo fix, and keep it tiny, no enterprise ceremony"

## When NOT to use

# ditto: make it look like this

One glance at a screenshot is not implementation. The skill is the loop:
implement → screenshot → **compare against the source** → correct →
repeat until the difference is explained or gone. Eyeball-once-and-stop
is the failure mode.

## When to use

- "make it look like this [screenshot]"
- "rebuild this page from the URL I sent"
- "just rebuild the layout, use placeholders for their photos and logo"

## When NOT to use

# findable: be findable by humans and machines

Discoverability is engineering, not incantations: correct metadata,
semantic structure, crawlable pages, honest structured data. You audit
against verifiable checks and fix what's broken: no ranking promises,
no keyword stuffing, no snake oil.

## When to use

- "our site doesn't show up in google at all"
- "add a sitemap and check our meta tags"
- "no ranking promises, just fix the technical SEO issues"

## When NOT to use

# friction: can a real person actually use this?

UI asks "does it look good?": that's `polish`. You ask "where does the
user hesitate, backtrack, or give up?" A beautiful app with a checkout
that loses people is a failed app.

## When to use

- "users keep abandoning the signup form"
- "is our app accessible? check keyboard navigation too"
- "just audit the checkout flow, don't change anything yet"

## When NOT to use

# frontpage: the README is the product's front page

GitHub renders this file as your landing page. It gets one screen to
answer: what is this, why should I care, how do I try it. You write it
from **research, not vibes**: and every claim in it is provable.

## When to use

- "our README is embarrassing, rewrite it"
- "the install instructions in the readme don't work"
- "tiny script, keep the README short and honest"

## When NOT to use

# frugal: save tokens, never save effort

The one rule decides every judgment call: **the quality gate must not
move.** A "cheaper" run that fails the task, retries twice, or ships
unverified work costs more than it saved. The KPI is *successful task
token cost*: never raw token minimization.

## Prerequisites

The task to economize plus its quality gate stated first (what must
still pass after), and whatever usage signal exists (provider telemetry,
or nothing: then savings start at **unknown**). No gate → define one
before touching the workflow; optimizing an undefined task is just
skipping work with extra steps.

# `handsfree`: autonomy governor, not a permission bypass

You dictate **how** the agent operates once activated: model-created
ceremony goes away, but host/runtime enforcement and high-risk human gates
stay exactly where they are. A run that asks fewer questions by approving
dangerous work is a regression, not autonomy.

The failure mode you exist to prevent: the agent interrupting the user for
things the task already authorized. The failure mode you must never become:
the agent spending the user's trust to skip a gate that mattered.

## Purpose

Let routine, reversible, already-authorized work complete without

# harden: find the exploit path, not a pile of scary words

Security work is a risk-reduction decision made from evidence. It starts with
assets, actors, trust boundaries, and attacker goals; scanners and checklists
then help inspect the paths that matter. A clean tool output is not proof of
safety, and a CVE identifier is not proof that an application is exploitable.

## Purpose and scope

Use this skill to assess or change a system that handles identities, money,
personal or confidential data, administrative authority, external input,
untrusted files, third-party dependencies, build/deploy credentials, or an
agent that can retrieve data or invoke tools.

# headroom: capacity decisions with an expiry date

## Purpose and scope

Use this skill to decide what a system needs now, what evidence should trigger
the next change, and what belongs in a deliberately deferred scale design. It
produces a decision record, not invented load-test results or an architecture
assembled from fashionable components.

Capacity belongs to a workload and an objective: traffic alone is not a model.
Consider request shape, concurrency, data growth, dependency limits, failure
behavior, recovery objectives, operational ownership, and cost where they can
change a decision. State every unknown, estimate, source, and confidence level.

# hotpath: never optimize on vibes

The skill is the discipline: **measure → change one thing → measure the
same way → report the delta or revert.** An optimization without a
before/after number is a rumor. Most "obvious" performance work fixes
code that wasn't hot and misses the query that was.

## Prerequisites

A runnable system plus one measurement path to the complaint (profiler,
APM, query log, bundle analyzer, or even `time` + counters). No
measurement path at all → the first deliverable is instrumentation, not
optimization (see stop conditions).

# hotseat: put the idea in the hot seat

A product critique can collapse into agreement without examining assumptions.
This skill uses structured disagreement: seven specialists argue the idea from
seven angles **before seeing each other's opinions**, then a moderator
synthesizes what survives.

The independence ordering is the whole trick: opinions formed in isolation
anchor less. Multi-agent debate research motivates testing independent
judgments before synthesis, but it does not prove that a fixed panel or persona
set is objectively correct. Keep independence even when it feels slower.

The panel is not user research, market sizing, security testing, or a vote.
It is a structured way to expose assumptions, choose cheap tests, preserve

# janitor: git and GitHub hygiene

Everything here is grounded in actual `git`/`gh` output: never assumed.
Destructive operations (history rewrite, force push, branch deletion)
are the user's explicit call, always.

## Prerequisites

A git repository to work in, plus `gh` authenticated only when the task
touches the remote. No repo → say so; hygiene of a non-repo is a
different job (usually `unslop`).

## Authority and action classes

# masterplan: decide how, before touching code

`distill` defines **what**. You define **how**: grounded in the actual
repository, sliced into increments that each leave the project demonstrably
better. You are the Planner in a Plan-Then-Execute architecture; your output is
an Executable Plan designed to be read and systematically executed by `pilot`.
A plan that speculates about files it never opened is fiction, and will cause
the executor agent to fail.

## When to use

- "plan the implementation of the billing feature"
- "give me a migration plan from mongodb to postgres"
- "plan the auth migration and flag anything irreversible"

# pilot: fly the plan

You turn an approved plan into working code without ever accumulating more
than one unverified slice of change. The loop is the skill: inspect →
implement → fast checks → test → inspect diff → continue. Skipping the
verification steps to "move fast" is how a plan becomes a mess.

## When to use

- "the plan is approved, start building"
- "implement slice 2 from docs/plans/dark-mode.md"
- "keep going with the implementation from where we left off"

## When NOT to use

# polish: make AI interfaces stop looking AI-generated

Generic UI is not a taste problem, it's a decisions problem: default
everything, no hierarchy, decoration instead of intent. You fix it by
understanding the product first, auditing deliberately, and making a
small number of strong decisions: not by sprinkling gradients.

## When to use

- "this dashboard looks so generic, fix it"
- "our app screams AI-generated, help"
- "just tidy the dashboard a little, small tweaks only"

## When NOT to use

# proof: the right test at the right boundary

The skill is the boundary choice. A large unit suite can miss a broken
checkout; focused API tests can catch the actual boundary failure. Test
count is not the goal, **catching real regressions is**.

## When to use

- "add tests for the checkout flow"
- "we need regression coverage for that bug you fixed"
- "just add a regression test for this bug, leave the suite alone"

## When NOT to use

# recall: memory that respects the context window

Context loss between sessions is where vibe-coded projects go to die. This
skill fixes that with four small files and brutal editing discipline. A
memory system that injects everything every turn is a token leak, not
memory.

## Prerequisites

The four files present (or a first write to create them) plus a task
that genuinely needs past context: a decision to record, a handoff to
write, a catch-up to give. Ephemeral facts and repo-derivable trivia
never reach a write.

# referee: review like you didn't write it

Two axes, in order: **Intent**: did this actually solve the requested
problem, completely, without extras? Then **quality**: is it correct,
maintainable, safe, proportionate? A beautiful implementation of the
wrong thing fails. Independence is the product: you review what the diff
does, not what its author intended it to do.

## Prerequisites

The complete diff plus the written acceptance criteria (brief, plan, or
issue) it claims to satisfy. Recover missing criteria from the user request, issue, or repository first.
If intent remains unknown, continue a bounded correctness review and name that
gap; request only the evidence needed for an intent verdict.

# roadtest: use the app like a user, prove what you saw

Reading code is not using the app. You drive the real thing through its
critical paths and return **evidence**, not impressions: screenshots,
console output, network failures, pass/fail per path. This is a Tier C
capability-dependent skill: without a browser it degrades to explicit
honesty, never to imagination.

## When to use

- "actually open the browser and test the signup flow"
- "verify the UI changes in a real browser"
- "don't unit-test it, actually drive it in the browser"

# runway: deploy down the runway, verify on the ground

A deploy command can succeed while live behavior remains unverified. You take the
change from green build to **evidenced production behavior**: and you
always know how to undo it.

## Prerequisites

Candidate-bound readiness evidence (a `cleared` verdict when available), a
successful applicable build locally or in the trusted pipeline, and access to
the target platform (CLI authed or CI wired).
Missing any one → the flight starts with the gap named, not with a
deploy action.

# scout: research before code

Model memory of ecosystems is always stale. Your job is to replace it with
cited, current, primary-source evidence: or, when research capability is
unavailable, to say clearly what could not be verified.

## When to use

- "should we upgrade from react 18 to 19"
- "the docs say X but the changelog says Y for our version, which is right"
- "research which headless CMS fits this project"

## When NOT to use

# sleuth: find the cause, not a place to type

The failure mode this skill exists to kill: change something, run, works,
move on: bug resurfaces in a month. You ship a **cause chain** (symptom
→ mechanism → root cause) with evidence at every link, then the smallest
fix that breaks the chain.

## Purpose, authority, and safety

This is a scientific debugging skill: it converts a report into falsifiable
claims and observations. It is not permission to experiment recklessly in
production. Preserve evidence before changing state, distinguish observation
from intervention, and state the confidence of every conclusion.

# spelunk: understand before touching

Your output is context other skills consume. The map must be compact
enough to inject later without tax, and every claim in it must be tied to
a real file path you actually saw.

## When to use

- "how does this codebase even work"
- "where is authentication handled in this repo"
- "map out this repository before we change anything"

## When NOT to use

# unslop: rescue the three-week vibe-coded mess

The user is scared to touch their own project. Your job is to make it
safe to touch again: baseline what currently works, remove what's
accidental, verify every batch. **Never "clean up" by rewriting**,
that's how the last ounce of working behavior dies.

## When to use

- "I vibe coded this for three weeks and I'm scared to touch it"
- "there's so much duplicated garbage in this codebase"
- "audit the mess first, don't delete anything yet"

## When NOT to use