feat: improve skill review scores (+51% avg)

skills/dockerfile-generation/SKILL.md

@@ -1,36 +1,66 @@
 ---
 name: dockerfile-generation
-description: Build minimal, secure Dockerfiles with verification-first workflow.
+description: "Generate minimal, secure, multi-stage Dockerfiles with layer optimization and non-root execution. Use when the user asks to create a Dockerfile, containerize an application, optimize Docker image size, fix Docker build issues, or harden a container image."
 ---
 
 # Dockerfile Generation
 
 ## Purpose
 
-Create or improve Dockerfiles with secure and efficient containerization practices.
+Create or improve Dockerfiles using secure, efficient containerization practices including multi-stage builds, minimal base images, and non-root execution.
 
 ## Inputs
 
-- app runtime and entrypoint
-- build tooling and artifacts
-- runtime environment constraints
+- App runtime and entrypoint (e.g., `node server.js`, `python -m app`)
+- Build tooling and artifacts (e.g., `npm run build` producing `dist/`)
+- Runtime environment constraints (ports, volumes, env vars)
 
 ## Process
 
-1. Identify build-time vs runtime dependencies.
-2. Prefer multi-stage builds for smaller images.
-3. Use pinned base image tags and non-root user.
-4. Add healthcheck and sensible default command.
-5. Verify build and run behavior locally.
+1. **Identify build-time vs runtime dependencies** and select appropriate base images:
+   ```dockerfile
+   # Build stage - includes dev tools
+   FROM node:20-alpine AS builder
+   WORKDIR /app
+   COPY package*.json ./
+   RUN npm ci --ignore-scripts
+   COPY . .
+   RUN npm run build
+
+   # Runtime stage - minimal image
+   FROM node:20-alpine AS runtime
+   RUN addgroup -S app && adduser -S app -G app
+   WORKDIR /app
+   COPY --from=builder /app/dist ./dist
+   COPY --from=builder /app/node_modules ./node_modules
+   USER app
+   EXPOSE 3000
+   HEALTHCHECK CMD wget -qO- http://localhost:3000/health || exit 1
+   CMD ["node", "dist/server.js"]
+   ```
+2. **Apply security defaults**: pin base image tags, run as non-root, avoid `COPY . .` in the runtime stage to exclude source and secrets.
+3. **Optimize layers**: order instructions from least to most frequently changing (OS deps > app deps > source code) for better cache hits.
+4. **Add healthcheck** and sensible default `CMD`.
+5. **Verify build and run locally**:
+   ```bash
+   docker build -t app:test .
+   docker run --rm app:test
+   # Verify non-root execution
+   docker run --rm app:test whoami  # should print "app", not "root"
+   # Check image size
+   docker images app:test --format '{{.Size}}'
+   ```
 
 ## Output Format
 
-- Dockerfile path
-- key design decisions
-- build/run verification commands
+- Dockerfile with inline comments explaining key decisions
+- Build and run verification commands
+- Image size comparison if replacing an existing Dockerfile
 
 ## Quality Checks
 
-- [ ] Uses minimal runtime image where practical
+- [ ] Uses multi-stage build with minimal runtime image
 - [ ] Runs as non-root user
-- [ ] No secrets baked into image layers
+- [ ] No secrets or source code leaked into runtime image layers
+- [ ] Base image tags are pinned (e.g., `node:20.11-alpine`, not `node:latest`)
+- [ ] `HEALTHCHECK` instruction is present

skills/git-workflows/SKILL.md

@@ -1,35 +1,68 @@
 ---
 name: git-workflows
-description: Safe day-to-day git workflows for branching, sync, and cleanup.
+description: "Safe day-to-day git workflows for branching, syncing, rebasing, and cleanup. Creates feature branches, syncs with remote via pull/rebase, and deletes merged branches. Use when the user asks to create a branch, sync with main, rebase, push changes, clean up stale branches, or manage upstream tracking."
 ---
 
 # Git Workflows
 
 ## Purpose
 
-Standardize safe local git workflows for branch creation, synchronization, and cleanup.
+Standardize safe local git workflows for branch creation, synchronization, and cleanup with explicit commands at every step.
 
 ## Inputs
 
-- branch intent (feature/fix/chore)
-- base branch (usually `main`)
+- Branch intent (feature, fix, chore)
+- Base branch (usually `main`)
 
 ## Process
 
-1. Snapshot state with `git-status` skill.
-2. Create or switch branch with clear naming.
-3. Rebase or merge from base branch intentionally.
-4. Commit in small units with meaningful messages.
-5. Push with upstream tracking.
+1. **Snapshot current state** before any operation:
+   ```bash
+   git status --short --branch
+   git stash list
+   ```
+2. **Create or switch branch** with conventional naming:
+   ```bash
+   # Feature branch
+   git checkout -b feature/add-auth main
+   # Fix branch
+   git checkout -b fix/login-crash main
+   # Chore branch
+   git checkout -b chore/update-deps main
+   ```
+3. **Sync with base branch** using rebase for clean history:
+   ```bash
+   git fetch origin
+   git rebase origin/main
+   # If conflicts arise, resolve then:
+   git rebase --continue
+   ```
+4. **Commit in small units** with meaningful messages:
+   ```bash
+   git add <specific-files>
+   git commit -m "feat: add JWT validation middleware"
+   ```
+5. **Push with upstream tracking**:
+   ```bash
+   git push -u origin feature/add-auth
+   ```
+6. **Cleanup after merge**:
+   ```bash
+   git checkout main && git pull
+   git branch -d feature/add-auth
+   # Remove remote tracking for deleted branches
+   git fetch --prune
+   ```
 
 ## Output Format
 
-- actions taken
-- resulting branch state
-- next safe git step
+- Actions taken (exact commands run)
+- Resulting branch state (`git log --oneline -5`)
+- Next safe git step recommendation
 
 ## Quality Checks
 
-- [ ] No destructive commands unless explicitly requested
+- [ ] No destructive commands (`reset --hard`, `push --force`) unless explicitly requested
 - [ ] No force push to protected branches
-- [ ] Working tree state verified after each workflow step
+- [ ] Working tree state verified with `git status` after each workflow step
+- [ ] Stash checked before branch switches to avoid losing work

skills/language-conventions/SKILL.md

@@ -1,35 +1,54 @@
 ---
 name: language-conventions
-description: Project convention references for Python, TypeScript, and Terraform.
+description: "Detect and enforce coding conventions for Python, TypeScript, and Terraform projects. Identifies linters, formatters, and style rules from existing config files and recommends minimal alignment changes. Use when the user asks about coding standards, project conventions, style guides, naming conventions, linting setup, or best practices for Python, TypeScript, or Terraform."
 ---
 
 # Language Conventions
 
 ## Purpose
 
-Enforce consistent coding and tooling conventions across common language stacks.
+Detect existing coding conventions from project configuration and enforce consistent style, tooling, and naming across Python, TypeScript, and Terraform stacks.
 
 ## Inputs
 
-- target language or stack
-- existing repo conventions
-- build/test tooling
+- Target language or stack
+- Existing repo conventions (config files, linter settings)
+- Build/test tooling in use
 
 ## Process
 
-1. Detect current conventions from existing files.
-2. Prefer existing project standards over generic defaults.
-3. Recommend minimal changes for consistency.
-4. Validate with the language-specific quality gates.
+1. **Detect existing conventions** by scanning for config files:
+   ```bash
+   # Python
+   ls pyproject.toml setup.cfg .flake8 .ruff.toml tox.ini 2>/dev/null
+   # TypeScript
+   ls tsconfig.json .eslintrc* .prettierrc* biome.json 2>/dev/null
+   # Terraform
+   ls .terraform-version .tflint.hcl .editorconfig 2>/dev/null
+   ```
+2. **Prefer existing project standards** over generic defaults. If `pyproject.toml` has `[tool.ruff]`, use those rules. If `.eslintrc` exists, prefer ESLint over Biome.
+3. **Recommend minimal changes** for consistency. Example recommendations:
+   - Python: add `ruff check .` to CI if ruff config exists but no CI step runs it
+   - TypeScript: enable `strict: true` in tsconfig if most files already pass
+   - Terraform: run `terraform fmt -check -recursive` in CI
+4. **Validate alignment** with language-specific quality gates:
+   ```bash
+   # Python
+   ruff check . && ruff format --check .
+   # TypeScript
+   npx tsc --noEmit && npx eslint .
+   # Terraform
+   terraform fmt -check -recursive && terraform validate
+   ```
 
 ## Output Format
 
-- detected conventions
-- recommendations
-- commands used to verify alignment
+- Detected conventions (config files found, active rules)
+- Recommendations (specific changes with rationale)
+- Verification commands to confirm alignment
 
 ## Quality Checks
 
-- [ ] Recommendations align with existing repo patterns
-- [ ] Tooling choices are explicit
-- [ ] Verification commands are included
+- [ ] Recommendations align with existing repo patterns, not generic defaults
+- [ ] Tooling choices match what the project already uses
+- [ ] Verification commands are runnable and included in output

skills/terraform-skill/SKILL.md

@@ -1,36 +1,74 @@
 ---
 name: terraform-skill
-description: Terraform/OpenTofu authoring, testing, and security workflow.
+description: "Terraform and OpenTofu authoring, validation, and security workflow. Writes HCL modules, runs plan/apply cycles, and scans for misconfigurations. Use when the user asks about Terraform modules, HCL files, infrastructure as code, terraform plan/apply, tfvars, state management, or OpenTofu configurations."
 ---
 
 # Terraform Skill
 
 ## Purpose
 
-Guide safe infrastructure-as-code changes using Terraform/OpenTofu best practices.
+Guide safe infrastructure-as-code changes using Terraform/OpenTofu best practices with concrete validation at every step.
 
 ## Inputs
 
 - IaC module or environment target
-- provider and backend configuration
-- policy/security constraints
+- Provider and backend configuration
+- Policy/security constraints
 
 ## Process
 
-1. Read current module patterns and state implications.
-2. Implement minimal, reviewable IaC changes.
-3. Run `fmt`, `validate`, and plan checks.
-4. Add or update tests (native tests or Terratest when needed).
-5. Report security and drift considerations.
+1. **Read current module patterns** and understand state implications:
+   ```bash
+   # Check existing structure
+   ls *.tf terraform.tfstate.d/ .terraform/ 2>/dev/null
+   # Review what providers and backends are configured
+   grep -r 'provider\|backend' *.tf
+   ```
+2. **Implement minimal, reviewable changes** following conventions:
+   ```hcl
+   # Use variables with descriptions and validation
+   variable "instance_type" {
+     description = "EC2 instance type for the web server"
+     type        = string
+     default     = "t3.micro"
+     validation {
+       condition     = can(regex("^t3\\.", var.instance_type))
+       error_message = "Only t3 instance types are allowed."
+     }
+   }
+   ```
+3. **Run format, validate, and plan checks**:
+   ```bash
+   terraform fmt -recursive
+   terraform validate
+   terraform plan -out=tfplan
+   # Review plan for unintended changes
+   terraform show tfplan
+   ```
+4. **Add or update tests** when applicable:
+   ```bash
+   # Native Terraform test (1.6+)
+   terraform test
+   # Or run Terratest if the project uses it
+   cd test/ && go test -v -timeout 30m
+   ```
+5. **Check for security issues**:
+   ```bash
+   # If tfsec is available
+   tfsec .
+   # Or checkov
+   checkov -d .
+   ```
 
 ## Output Format
 
-- changed modules/resources
-- validation and plan summary
-- risk notes and rollout guidance
+- Changed modules/resources with rationale
+- `terraform plan` summary (resources to add/change/destroy)
+- Risk notes and rollout guidance
 
 ## Quality Checks
 
-- [ ] `fmt` and `validate` performed
-- [ ] Plan output reviewed for unintended changes
-- [ ] Sensitive values are not exposed in code or logs
+- [ ] `terraform fmt` and `terraform validate` pass
+- [ ] Plan output reviewed — no unintended resource destruction
+- [ ] Sensitive values use `sensitive = true` and are not exposed in logs
+- [ ] State is not modified directly; changes go through plan/apply

skills/workflow/SKILL.md

@@ -1,36 +1,58 @@
 ---
 name: workflow
-description: Development workflow, quality gates, and disciplined delivery.
+description: "Structured development workflow from planning through implementation and verification. Runs repo-specific quality gates, commits in small testable steps, and documents decisions. Use when the user asks to implement a feature end-to-end, follow a development process, run quality checks, or deliver a task with verification."
 ---
 
 # Workflow
 
 ## Purpose
 
-Provide a consistent delivery flow from plan to implementation and verification.
+Provide a consistent delivery flow from planning through implementation and verification, with concrete quality gates at each stage.
 
 ## Inputs
 
-- task goal
-- repository context
-- available quality gates
+- Task goal and acceptance criteria
+- Repository context (language, framework, existing CI)
+- Available quality gates (linters, tests, type checks)
 
 ## Process
 
-1. Clarify outcome and constraints.
-2. Implement in small, testable steps.
-3. Run quality gates relevant to the repo.
-4. Summarize decisions and remaining risks.
+1. **Clarify outcome and constraints** before writing code:
+   - Restate the goal in one sentence
+   - List files likely to change
+   - Identify which quality gates apply (detect from repo):
+     ```bash
+     # Detect available quality gates
+     [ -f package.json ] && echo "node: $(jq -r '.scripts.test // empty' package.json)"
+     [ -f Makefile ] && grep -E '^(test|lint|check):' Makefile
+     [ -f pyproject.toml ] && grep -A2 '\[tool.pytest' pyproject.toml
+     ```
+2. **Implement in small, testable steps** — one logical change per commit. Run tests after each change:
+   ```bash
+   # Example: after each change
+   npm test        # or pytest, go test, cargo test, etc.
+   git add <files>
+   git commit -m "feat: add input validation for email field"
+   ```
+3. **Run all quality gates** relevant to the repo before finalizing:
+   ```bash
+   # Common patterns
+   npm run lint && npm test           # Node.js
+   ruff check . && pytest             # Python
+   cargo clippy && cargo test         # Rust
+   go vet ./... && go test ./...      # Go
+   ```
+4. **Summarize decisions and remaining risks** in the output.
 
 ## Output Format
 
-- Goal
-- Changes made
-- Verification performed
-- Remaining risks
+- Goal (one sentence)
+- Changes made (files modified, rationale)
+- Verification performed (commands run, pass/fail)
+- Remaining risks (what could not be verified and why)
 
 ## Quality Checks
 
-- [ ] No unrelated refactors
-- [ ] Verification commands executed
-- [ ] Risks documented when checks cannot run
+- [ ] No unrelated refactors included in changes
+- [ ] All available verification commands executed and passing
+- [ ] Risks documented when checks cannot run (e.g., missing test environment)