app-questions

Pre-flight Check

Before proceeding, verify you are in a scaffolded Cribl app folder. If you are not, stop and tell the user: "You must run this skill from within a scaffolded Cribl app folder."

Trigger: Run this skill inside a Cribl app project directory.

Input:

First run: Answer questions about the app's purpose, workflows, and problems it solves
Subsequent runs: Choose menu options to view/edit/add/delete definition sections

Output:

First run: An app definition capturing all answers (APP_DEFINITION.md)
Subsequent runs: Updated APP_DEFINITION.md with your changes

How to Use

First Run (Creation Mode)

Scaffold an app in Cribl (Apps > Create App)
Copy the starter code to your local machine
cd into the app directory
Run this skill: /app-questions
Describe what your app does (be specific about the problem and who uses it)
Answer clarifying questions if needed to sharpen the description
Answer the full questionnaire about your app
Review and edit the generated app definition

💡 Tip: Provide specifics in your initial description. Instead of "monitoring tool", say "help our platform team track when customer data pipelines fall behind their SLAs".

Subsequent Runs (Edit Mode)

Run /app-questions (the skill detects APP_DEFINITION.md exists)
A menu appears with options to edit parts of the definition
Choose what to update:
- View/edit the problem statement
- Manage workflows (add/edit/delete)
- Update data & integration points
- Modify permissions & access rules
- Change scope items
- Update UI preferences
Make your changes interactively
Review the updated definition
Exit when done

Workflow Example: Add a new workflow by running /app-questions, selecting "Manage Workflows", choosing "Add", and describing the new workflow. Then run /app-brief to update the app brief, and /app-implement to implement it.

Skill Workflow

Step 1: Detect Mode

When the skill runs:

If APP_DEFINITION.md does not exist: Enter "Creation Mode" (see below)
If APP_DEFINITION.md exists: Enter "Edit Mode" (see below)

Creation Mode: Gather information through 7 phases

The skill gathers information through 7 phases, with clarity validation at every step to ensure specific, thorough answers:

Clarity validation triggers on:

Very short or one-word answers (< 2 sentences)
Missing key context or vague language
Abstract statements without concrete details
Answers that don't address the question

When clarity issues are detected, the skill asks targeted follow-up questions to sharpen the answer before proceeding to the next phase.

Phase 1: Understand the Problem

Guided discovery — ask ONE question at a time:

Ask: "What is the app id?"
- Wait for answer, clarify if needed
Ask: "What's the main problem this app solves?"
- Wait for answer, clarify if needed
Ask: "Who will use this app?"
- Wait for answer, clarify if needed
Ask: "How are they currently solving this problem?"
- Wait for answer, clarify if needed

Clarity check: Answers must include the app id, the problem, user role, and current workflow. Follow up if vague or missing context. Do NOT proceed to the next question until the current answer is clear and complete.

Phase 2: Map User Workflows & Key Tasks

Guided workflow discovery:

Ask for Workflow 1 with a description of what the user does step-by-step
For each workflow, clarify:
- What specific steps does the user take (in order)?
- What do they create, modify, or delete?
- What do they see or review?
- Any decision points or branches?
Once clear, move to Workflow 2, then 3, etc.
Allow the user to enter blank or "done" to finish workflow collection

Clarity check: Ensure each workflow is concrete, sequenced, and includes specific objects/data and actions. Don't proceed to the next workflow until the current one is clear.

Phase 3: Explore Data & Integration Points

Guided discovery — ask ONE question at a time:

Ask: "What data does the app display?"
- Wait for answer, clarify if needed
Ask: "What does the app create or change?"
- Wait for answer, clarify if needed
Ask: "Does the app call any external services (Slack, OpenAI, etc.)?"
- Wait for answer, clarify if needed

Clarity check: Answers must specify data sources and integration names. Do NOT proceed to the next question until the current answer is clear and complete.

Phase 4: Consider Permissions & Access

Guided discovery — ask ONE question at a time:

Ask: "Should different users see different data?"
- Wait for answer, clarify if needed
Ask: "How should the app behave if a user lacks permission?"
- Wait for answer, clarify if needed

Clarity check: Answers must define user roles and access rules. Do NOT proceed to the next question until the current answer is clear and complete.

Phase 5: Ask About State & Secrets

Guided discovery — ask ONE question at a time:

Ask: "Does the app need to save any state?"
- Wait for answer, clarify if needed
Ask: "Are there general settings?"
- Wait for answer, clarify if needed
Ask: "Are there any user-specific settings?"
- Wait for answer, clarify if needed
Ask: "Does the app handle any secure secrets?"
- Wait for answer, clarify if needed

Clarity check: Answers must specify what state is saved and where. Do NOT proceed to the next question until the current answer is clear and complete.

Phase 6: Narrow the Scope

Guided discovery — ask ONE question at a time:

Ask: "What's the absolute minimum (MVP)?"
- Wait for answer, clarify if needed
Ask: "What would be nice to add later?"
- Wait for answer, clarify if needed
Ask: "Anything definitely out of scope?"
- Wait for answer, clarify if needed

Clarity check: MVP must be realistic and deliverable. Do NOT proceed to the next question until the current answer is clear and complete.

Phase 7: Clarify Preferences

Guided discovery — ask ONE question at a time:

Ask: "What's the overall structure? (wizard, dashboard, form, table, etc.)"
- Wait for answer, clarify if needed
Ask: "Any specific look/feel preferences?"
- Wait for answer, clarify if needed

Clarity check: Answers must align with the workflows and tasks identified. Do NOT proceed to the next question until the current answer is clear and complete.

Re-entrancy: Resume Where You Left Off

The skill is fully re-entrant. When you run /app-questions:

If APP_DEFINITION.md doesn't exist, the skill starts from Phase 1
If APP_DEFINITION.md exists, the skill reads it and resumes from the first incomplete phase
The skill skips questions for phases that are already answered and complete
Each answer is written incrementally to APP_DEFINITION.md as you complete questions, so no data is lost if you exit early

This means you can run the skill incrementally: define the problem today, map workflows tomorrow, finish scope and preferences next week. All your answers are preserved.

Persistence: APP_DEFINITION.md

The skill persists answers incrementally to APP_DEFINITION.md in the app directory as you progress through each question. This file serves as both:

Input: When you resume, the skill reads this file to determine which phase to continue from
Output: Your complete app definition once all phases are done

# App Definition

## App ID
[User's answer for the app id]

## Problem
[User's answer about what problem this solves]

## Target Users
[Who uses this and why]

## Workflows
### Workflow 1: [Name]
[Full description]

### Workflow 2: [Name]
[Full description]

[+ Additional workflows]

## Data & Integration Points
### Data Display
[User's answer]

### Create/Modify/Delete
[User's answer]

### External Integrations
[User's answer or "None"]

## Permissions & Access
### Different Users See Different Data?
[User's answer]

### Permission-Denied Behavior
[User's answer]

## State & Secrets
### Saved State
[User's answer or "None"]

### General-settings
[User's answer or "None"]

### User-Specific Settings
[User's answer or "None"]

### Secure Secrets
[User's answer or "None"]

## Scope
### Must-Have (MVP)
[User's answers]

### Nice-to-Have (Defer)
[User's answers]

### Out of Scope
[User's answers]

## UI Preferences
### Overall Structure
[User's answer]

### Look/Feel
[User's answer]

Users can edit this file directly in their editor, or re-run the skill to update via Q&A.

Edit Mode: Interactive Definition Editor

When APP_DEFINITION.md already exists, the skill enters Edit Mode and presents an interactive menu:

=== APP_DEFINITION.md Editor ===

1. View/Edit App ID
2. View/Edit Problem Statement
3. View/Edit Target Users
4. Manage Workflows (add, edit, delete, list)
5. View/Edit Data & Integration Points
6. View/Edit Permissions & Access
7. View/Edit Scope (must-have, nice-to-have, out-of-scope)
8. View/Edit UI Preferences
9. View entire definition (read-only)
10. Exit and save

Enter choice (1-10):

Menu Option Workflows

Option 1: View/Edit App ID

Display current app id
Ask: "Edit this? (yes/no)"
If yes: Present current text and ask for new text
Update APP_DEFINITION.md and return to menu

Option 2: View/Edit Problem Statement

Display current problem statement
Ask: "Edit this? (yes/no)"
If yes: Present current text and ask for new text
Update APP_DEFINITION.md and return to menu

Option 3: View/Edit Target Users

Display current target users
Ask: "Edit this? (yes/no)"
If yes: Present current text and ask for new text
Update APP_DEFINITION.md and return to menu

Option 4: Manage Workflows

Show sub-menu:

=== Manage Workflows ===

1. List all workflows
2. Add a new workflow
3. Edit a workflow
4. Delete a workflow
5. Back to main menu

Enter choice (1-5):

Sub-option 3.1: List all workflows

Display all workflow names and descriptions
Return to sub-menu

Sub-option 3.2: Add a new workflow

Ask: "Workflow name?"
Ask: "Workflow description?" (can be multi-line)
Add to ## Workflows section following existing format
Update APP_DEFINITION.md and return to sub-menu

Sub-option 3.3: Edit a workflow

List all workflows with numbers
Ask: "Which workflow to edit? (1-N)"
Display current workflow text
Ask: "New description?" (can be multi-line)
Update APP_DEFINITION.md and return to sub-menu

Sub-option 3.4: Delete a workflow

List all workflows with numbers
Ask: "Which workflow to delete? (1-N)"
Ask: "Are you sure? (yes/no)"
Remove from APP_DEFINITION.md and return to sub-menu

Option 5: View/Edit Data & Integration Points

Display current sections:
- Data Display
- Create/Modify/Delete
- External Integrations

Show sub-menu:

1. Edit Data Display
2. Edit Create/Modify/Delete
3. Edit External Integrations
4. Back to main menu

For each: Display current, ask for edits, update file

Option 6: View/Edit Permissions & Access

Display current sections:
- Different Users See Different Data?
- Permission-Denied Behavior
Ask which to edit, apply updates
Update APP_DEFINITION.md and return to menu

Option 7: View/Edit Scope

Display current sections:
- Must-Have (MVP)
- Nice-to-Have (Defer)
- Out of Scope
Show sub-menu for each section:
- View all items
- Add item
- Delete item
Update APP_DEFINITION.md and return to menu

Option 8: View/Edit UI Preferences

Display current sections:
- Overall Structure
- Look/Feel
Ask which to edit, apply updates
Update APP_DEFINITION.md and return to menu

Option 9: View entire definition (read-only)

Display full APP_DEFINITION.md content
Return to menu

Option 10: Exit and save

Show summary of what changed this session
Confirm save (changes are already written incrementally)
Exit

Edit Mode UX Principles

Incremental saves: Write to APP_DEFINITION.md after each change
Confirmations for destructive actions: Always ask before deleting workflows or scope items
Show current state: Always display current content before asking for edits
Easy back out: Always allow returning to previous menu without committing
Multi-line input: Support multi-line text for workflow descriptions, data requirements, etc.
Summary on exit: Show what was modified when exiting

Generate CLAUDE.md

Once APP_DEFINITION.md is complete, create a CLAUDE.md file in the app directory only if it doesn't already exist.

Template for CLAUDE.md:

# CLAUDE.md

This file provides guidance to Claude Code when working with this Cribl app.

## App Context

This app is defined in `APP_DEFINITION.md` — read that for comprehensive problem statement, workflows, and scope.

## Key References

- `AGENTS.md` — How to build the app and navigate the app runtime environment
- `APP_DEFINITION.md` — Full app requirements and workflows
- `APP_BRIEF.md` — Implementation guide (generated from APP_DEFINITION)

## Workflows & Data

[If APP_DEFINITION.md has workflows, include a summary here, e.g.:]

**Main Workflows:**
- [Workflow 1 name and purpose]
- [Workflow 2 name and purpose]

**Key Data:**
- [What the app displays]
- [What the app creates/modifies]
- [External integrations]

## UI Structure

[Include from APP_DEFINITION if specified, e.g.:]
- Overall structure: [wizard/dashboard/form/table/etc]
- Key screens: [list main screens/pages]

## MVP Scope

**Must-have (Phase 1):**
- [Features from APP_DEFINITION MVP section]

**Nice-to-have (Defer):**
- [Features from APP_DEFINITION defer section]

**Out of scope:**
- [Features from APP_DEFINITION out-of-scope section]

## Additional Guidance

- Read the [Cribl Apps Builder Guide](https://docs.cribl.io/apps/builder-guide/) for patterns and best practices
- Check `/app-brief` and `/app-validate` skills for guidance before implementation

Instructions for Claude:

Check if CLAUDE.md already exists in the app directory
If it does exist, stop — do not overwrite it
If it does NOT exist, create it by:
- Using the template above as the base
- Filling in specific details from the completed APP_DEFINITION.md (workflows, data, scope, UI structure)
- Always including reference to AGENTS.md (it's in every app scaffold)
- Keeping any other references or guidance appropriate for the app

Resources

Cribl Apps Docs: https://docs.cribl.io/apps/
Builder Guide: https://docs.cribl.io/apps/builder-guide/
GitHub Examples: https://github.com/criblapps and https://github.com/Cribl-Community

About this skill

Pre-flight Check

How to Use

First Run (Creation Mode)

Subsequent Runs (Edit Mode)

Skill Workflow

Step 1: Detect Mode

Creation Mode: Gather information through 7 phases

Phase 1: Understand the Problem

Phase 2: Map User Workflows & Key Tasks

Phase 3: Explore Data & Integration Points

Phase 4: Consider Permissions & Access

Phase 5: Ask About State & Secrets

Phase 6: Narrow the Scope

Phase 7: Clarify Preferences

Re-entrancy: Resume Where You Left Off

Persistence: APP_DEFINITION.md

Edit Mode: Interactive Definition Editor

Menu Option Workflows

Option 1: View/Edit App ID

Option 2: View/Edit Problem Statement

Option 3: View/Edit Target Users

Option 4: Manage Workflows

Option 5: View/Edit Data & Integration Points

Option 6: View/Edit Permissions & Access

Option 7: View/Edit Scope

Option 8: View/Edit UI Preferences

Option 9: View entire definition (read-only)

Option 10: Exit and save

Edit Mode UX Principles

Generate CLAUDE.md

Resources