app-brief
Generates the app brief from the app definition, or updates it if APP_BRIEF.md already exists
How do I install this agent skill?
npx skills add https://github.com/cribl-community/claude-cribl-app-plugins --skill app-briefIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is safe for its intended purpose but processes local files which creates a surface for indirect prompt injection.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
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 in the same folder where the APP_DEFINITION.md resides.
Input: Contents of APP_DEFINITION.md (and optionally existing APP_BRIEF.md if updating)
Output: A comprehensive app brief (with full editing capability) that Claude Code can use to implement the app which is stored in APP_BRIEF.md
How to Use
cdinto the app directory- Run this skill:
/app-brief- First run: Creates
APP_BRIEF.mdfrom the definition - Subsequent runs: Updates
APP_BRIEF.mdbased on changes toAPP_DEFINITION.md
- First run: Creates
- Review and edit the generated brief
- Run the
/app-validateskill - If validation fails, fix the brief.
- Pass the contents of
app-briefto your agentic tool (Claude Code)
Skill Workflow
Step 1: Check for Existing Brief
- If
APP_BRIEF.mddoes not exist: Run the "Generate the Brief" workflow (see below) - If
APP_BRIEF.mdalready exists: Run the "Update the Brief" workflow (see below)
Step 2A: Generate the Brief (First Run)
If APP_BRIEF.md does not exist, generate the implementation brief from scratch based on answers provided in APP_DEFINITION.md
# [App Name] - App Brief
## App ID
[The unique identifier for this app]
## Problem & Vision
[Summary of the problem the app solves and how users benefit]
## Target Users
[Who uses this app and what they're trying to accomplish]
## Key Workflows
### Workflow 1: [Name]
- **User sees**: [What appears on screen]
- **User does**: [What they click/configure/select]
- **Result**: [What gets created/changed/shown]
- **Permissions**: [Who can do this? Any restrictions?]
### Workflow 2: [Name]
- **User sees**: [What appears on screen]
- **User does**: [What they click/configure/select]
- **Result**: [What gets created/changed/shown]
- **Permissions**: [Who can do this? Any restrictions?]
[+ Additional workflows as needed]
## Data & Actions
**The app will fetch from Cribl:**
- [Resource type 1]: [Why? Used in which workflow?]
- [Resource type 2]: [Why? Used in which workflow?]
**The app will create/modify/delete in Cribl:**
- [Resource type 1]: [Which workflow creates/modifies/deletes this?]
- [Resource type 2]: [Which workflow creates/modifies/deletes this?]
**The app will remember (general state):**
- [State 1]: [What should be saved? When should it persist?]
- [State 2]: [What should be saved? When should it persist?]
(Or "None" if no general state)
**User-specific settings (stored per user):**
- [Setting 1]: [What is it? Which user(s) need it?]
- [Setting 2]: [What is it? Which user(s) need it?]
(Or "None" if no per-user settings)
**Secure secrets:**
- [Secret 1]: [What is it? How is it used?]
- [Secret 2]: [What is it? How is it used?]
(Or "None" if no secrets)
## UI Structure
### Overall Layout
[Recommended structure: wizard, dashboard, form, table, etc.]
### Key Screens/Pages
1. **[Screen Name]**: [What it shows, what user can interact with]
2. **[Screen Name]**: [What it shows, what user can interact with]
3. **[Screen Name]**: [What it shows, what user can interact with]
[Add more screens as needed]
## Permissions & Access
- **Who can use this app?**: [All members, or specific roles?]
- **Permission-aware behavior**: [How does the app respond if a user lacks access to an action?]
## External Integrations (if any)
- **[Service name]**: [What does the app do with it?]
- **[Service name]**: [What does the app do with it?]
(Or "None" if the app only works with Cribl)
## MVP Scope
**Must-have:**
- [Feature 1]
- [Feature 2]
**Nice-to-have (defer):**
- [Feature 1]
- [Feature 2]
**Out of scope:**
- [Feature 1]
## Edge Cases & Error Handling
- **If user lacks permission**: [What should the app show?]
- **If data is unavailable**: [What should the app show?]
- **If an action fails**: [What should the app show?]
## Implementation guidance (include this section verbatim)
- Read AGENTS.md first
- Then read openapi.json
- NEVER EVER use local storage
---
Step 2B: Update the Brief (Subsequent Runs)
If APP_BRIEF.md already exists, intelligently update it based on changes to APP_DEFINITION.md:
Detection & Merging Logic:
-
Compare the two files to identify what changed in
APP_DEFINITION.md:- App ID changed
- New workflows added
- Workflows modified (name changed, description changed, or steps changed)
- New data requirements (new fetch sources, create/modify/delete operations, state fields)
- New UI screens or layout changes
- New scope items (must-have, nice-to-have, out-of-scope)
- Changes to permissions, integrations, or edge cases
-
For new workflows: Add them to the "## Key Workflows" section in
APP_BRIEF.md, following the same format as existing workflows -
For modified workflows: Update the corresponding workflow section with the new details, preserving any elaborations or examples that were added to the brief but not in the definition
-
For new data requirements: Add them to the "## Data & Actions" section under the appropriate subsection (fetch, create/modify/delete, state, settings, secrets)
-
For new UI screens: Add them to the "## UI Structure" section's "Key Screens/Pages" list
-
For scope changes: Add new items to "## MVP Scope" under the appropriate subsection
-
For other changes: Update the relevant sections (Problem & Vision, Target Users, Permissions & Access, External Integrations, Edge Cases & Error Handling)
Preservation Rules:
- Never remove sections or workflows that exist in
APP_BRIEF.mdbut are not mentioned in the updatedAPP_DEFINITION.md - Keep any elaborations, examples, or implementation details that were added to the brief beyond what was in the definition
- If a workflow description in the definition is more detailed, replace the brief's version; if the brief is more detailed, keep it
- Always preserve the "## Implementation guidance" section exactly as is
Output:
- Display a summary of what changed: "Added 1 new workflow: [name]. Updated 2 workflows: [names]. Added 3 data requirements."
- Save the updated brief back to
APP_BRIEF.md - Show the user the updated sections for review
Workflow Exit
Once the brief is generated or updated, the final brief is ready for:
- First run: Review, edit if needed, then run
/app-validateto validate alignment - Subsequent runs: Review the delta summary, check the updated sections, then commit changes via
/app-implement
Key Principles
- No technical jargon: Users describe problems; Claude figures out implementation
- Markdown persistence: Easy to read, edit, and version control
- Iterative updates: Brief can be regenerated/updated as requirements evolve
- Incremental updates: Only changed sections are rewritten; existing elaborations are preserved
- Direct file editing: Users can edit
APP_BRIEF.mddirectly for fast iteration - APIs handled by Claude: Claude uses
openapi.jsonto determine which Cribl APIs to call - User-specific storage: Per-user settings automatically prefixed with user ID
- MVP-first: Encourage shipping the minimum and iterating
- External integrations only: List third-party services if the app calls them
- Single source of truth:
APP_DEFINITION.mdis the authoritative source; changes there drive brief updates
Example Workflow: Adding a New Feature
- Edit
APP_DEFINITION.mdto add a new workflow (e.g., "Bulk enable/disable integrations") - Run
/app-brief— the skill detects the new workflow and adds it to the brief - Review the updated brief to see the new workflow integrated with existing ones
- Run
/app-validateto ensure the updated brief is sound - Run
/app-implementto implement the new workflow
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
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/cribl-community/claude-cribl-app-plugins/app-brief">View app-brief on skillZs</a>