Gemini Skill Guide

Default Behavior: Gemini defaults to read-only mode (suggest). Use -y (yolo) for auto-approve if code changes needed.

Use Cases

Running a Task

Defaults

• Model: gemini-3-flash-preview
• Approval mode: suggest (read-only, requires confirmation)
• Output format: text

Invocation Modes

Mode 1: Template invocation (from commands like /ultra-research)

• Use template config directly, NO user interaction
• Templates define model/approval/prompt

Mode 2: Regular invocation (user requests gemini directly)

1. Display current defaults
2. Use AskUserQuestion:
   • Option A: "Use default config" (Recommended) - gemini-3-flash-preview, suggest mode
   • Option B: "Custom config" - then ask model/approval mode/output format
3. Execute with chosen config

Configuration Options

Models:

• gemini-3-flash-preview (default, latest and fastest)
• gemini-3-pro-preview (most powerful, deep reasoning)
• gemini-2.5-pro (1M context, stable)
• gemini-2.5-flash (balanced, stable)
• gemini-2.5-flash-lite (lightweight, fast)

Approval modes:

• suggest (default) - requires user confirmation for actions, read-only
• yolo (-y) - auto-approve all actions, can modify files

Output formats:

• text (default) - human-readable
• json - structured output for automation

Context options:

• @./path - inject file content into prompt
• --include-directories dir1 dir2 - add directories to context
• -a, --all-files - include all files in context

Command template

gemini \
  -m gemini-3-flash-preview \
  -p "prompt here"

With file context

gemini -p "Analyze the architecture of this codebase @./src/"

With directory context

gemini --include-directories src docs -p "Review the documentation coverage"

Execution rules

• Default: NO -y flag (suggest mode, read-only)
• Use -y only when user explicitly chooses yolo mode in custom config
• Run the command and show complete output to user
• After completion: summarize findings and suggest next steps

Quick Reference

Following Up

• After every gemini command, summarize key findings
• Use AskUserQuestion to confirm next steps
• If code changes needed and not in yolo mode, ask user to enable -y or use codex skill

Error Handling

• If gemini exits non-zero, show the error and ask user for direction
• -y (yolo mode) requires explicit confirmation in Mode 2 custom config flow
• If output shows concerns, summarize and recommend actions

Templates

Use these predefined templates when commands reference gemini skill with template: <name>.

tech-research

Purpose: Deep technical research with evidence gathering

Prompt:

Conduct technical research on the specified topic:

[Research Protocol]
1. Search for official documentation and authoritative sources
2. Gather community best practices and real-world examples
3. Identify potential risks and trade-offs
4. Compare alternatives with evidence

[Evidence Requirements]
- Every claim must have verifiable source
- Priority: 1) Official docs 2) Benchmarks 3) Community practices
- Label findings: Fact | Inference | Speculation

[Output Format]
1. Executive Summary (2-3 sentences)
2. Key Findings (with sources)
3. Comparison Matrix (if alternatives exist)
4. Risks & Trade-offs
5. Recommendation (with confidence %)

Minimum 90% confidence required for recommendations.

architecture-review

Purpose: Validate architecture decisions against best practices

Prompt:

Review this architecture against these criteria:

[Critical State Management]
- Is critical state (funds/permissions/external API) persistable?
- Is recovery/replay mechanism in place?
- Is observability (logging/metrics/tracing) adequate?

[Modularity & Boundaries]
- Are module boundaries clear and well-defined?
- Is coupling between modules appropriate?
- Are interfaces stable and versioned?

[Scalability & Performance]
- Are there obvious bottlenecks?
- Is horizontal scaling possible?
- Are resource limits defined?

[Security]
- Are authentication/authorization properly separated?
- Is input validation at system boundaries?
- Are secrets properly managed?

[Maintainability]
- Is the codebase navigable?
- Are patterns consistent?
- Is technical debt visible and managed?

Provide findings with file:line references.
Rate each area: Good | Needs Improvement | Critical Issue

documentation-gen

Purpose: Generate or review documentation

Prompt:

Generate/review documentation for the specified code:

[Documentation Standards]
- Clear purpose statement
- Usage examples (production-ready, no TODO/placeholder)
- Parameter descriptions with types
- Return value documentation
- Error handling documentation
- Edge cases noted

[Quality Criteria]
- Accurate (matches actual implementation)
- Complete (all public APIs documented)
- Concise (no redundant information)
- Current (reflects latest code)

Output format: Markdown
Include code examples where helpful.

spec-validation

Purpose: Validate implementation against specifications

Prompt:

Validate the implementation against the specification:

[Compliance Check]
- Does implementation match spec requirements?
- Are all acceptance criteria covered?
- Are edge cases from spec handled?

[Gap Analysis]
- What spec requirements are NOT implemented?
- What implementation exists that's NOT in spec?
- Are there implicit assumptions not documented?

[Risk Assessment]
- What could break if spec changes?
- What's the impact of each gap?

Output:
1. Compliance Score (%)
2. Gaps List (with severity)
3. Recommendations

code-review

Purpose: Review code for issues (default read-only, can enable yolo for fixes)

Prompt:

Review this code (READ-ONLY - do not suggest exact code changes):

[Code Quality]
- TODO/FIXME/placeholder present?
- Deep nesting issues (>3 levels)?
- Hardcoded secrets or credentials?

[Security Concerns]
- Injection vulnerabilities?
- Auth bypass risks?
- Input validation gaps?

[Architecture Issues]
- Critical state not persisted?
- In-memory-only storage for important data?
- Breaking API changes without migration?

[Logic Problems]
- Race conditions?
- Resource leaks?
- Edge cases not handled?

[Testing Gaps]
- Core logic mocked inappropriately?
- Missing test coverage for critical paths?

Provide findings with file:line references.
Severity: Critical | High | Medium | Low
DO NOT provide code fixes - only identify issues.
If code changes needed, recommend using codex skill.