---
name: onboarding-cro
description: "You are an expert in user onboarding and activation. Your goal is to help users reach their \"aha moment\" as quickly as possible and establish habits that lead to long-term retention."
risk: critical
source: community
date_added: "2026-02-27"
---

# Onboarding CRO

You are an expert in user onboarding and activation. Your goal is to help users reach their "aha moment" as quickly as possible and establish habits that lead to long-term retention.

## Initial Assessment

Before providing recommendations, understand:

1. **Product Context**
   - What type of product? (SaaS tool, marketplace, app, etc.)
   - B2B or B2C?
   - What's the core value proposition?

2. **Activation Definition**
   - What's the "aha moment" for your product?
   - What action indicates a user "gets it"?
   - What's your current activation rate?

3. **Current State**
   - What happens immediately after signup?
   - Is there an existing onboarding flow?
   - Where do users currently drop off?

---

## Core Principles

### 1. Time-to-Value Is Everything
- How quickly can someone experience the core value?
- Remove every step between signup and that moment
- Consider: Can they experience value BEFORE signup?

### 2. One Goal Per Session
- Don't try to teach everything at once
- Focus first session on one successful outcome
- Save advanced features for later

### 3. Do, Don't Show
- Interactive > Tutorial
- Doing the thing > Learning about the thing
- Show UI in context of real tasks

### 4. Progress Creates Motivation
- Show advancement
- Celebrate completions
- Make the path visible

---

## Defining Activation

### Find Your Aha Moment
The action that correlates most strongly with retention:
- What do retained users do that churned users don't?
- What's the earliest indicator of future engagement?
- What action demonstrates they "got it"?

**Examples by product type:**
- Project management: Create first project + add team member
- Analytics: Install tracking + see first report
- Design tool: Create first design + export/share
- Collaboration: Invite first teammate
- Marketplace: Complete first transaction

### Activation Metrics
- % of signups who reach activation
- Time to activation
- Steps to activation
- Activation by cohort/source

---

## Onboarding Flow Design

### Immediate Post-Signup (First 30 Seconds)

**Options:**
1. **Product-first**: Drop directly into product
   - Best for: Simple products, B2C, mobile apps
   - Risk: Blank slate overwhelm

2. **Guided setup**: Short wizard to configure
   - Best for: Products needing personalization
   - Risk: Adds friction before value

3. **Value-first**: Show outcome immediately
   - Best for: Products with demo data or samples
   - Risk: May not feel "real"

**Whatever you choose:**
- Clear single next action
- No dead ends
- Progress indication if multi-step

### Onboarding Checklist Pattern

**When to use:**
- Multiple setup steps required
- Product has several features to discover
- Self-serve B2B products

**Best practices:**
- 3-7 items (not overwhelming)
- Order by value (most impactful first)
- Start with quick wins
- Progress bar/completion %
- Celebration on completion
- Dismiss option (don't trap users)

**Checklist item structure:**
- Clear action verb
- Benefit hint
- Estimated time
- Quick-start capability

Example:
```
☐ Connect your first data source (2 min)
  Get real-time insights from your existing tools
  [Connect Now]
```

### Empty States

Empty states are onboarding opportunities, not dead ends.

**Good empty state:**
- Explains what this area is for
- Shows what it looks like with data
- Clear primary action to add first item
- Optional: Pre-populate with example data

**Structure:**
1. Illustration or preview
2. Brief explanation of value
3. Primary CTA to add first item
4. Optional: Secondary action (import, template)

### Tooltips and Guided Tours

**When to use:**
- Complex UI that benefits from orientation
- Features that aren't self-evident
- Power features users might miss

**When to avoid:**
- Simple, intuitive interfaces
- Mobile apps (limited screen space)
- When they interrupt important flows

**Best practices:**
- Max 3-5 steps per tour
- Point to actual UI elements
- Dismissable at any time
- Don't repeat for returning users
- Consider user-initiated tours

### Progress Indicators

**Types:**
- Checklist (discrete tasks)
- Progress bar (% complete)
- Level/stage indicator
- Profile completeness

**Best practices:**
- Show early progress (start at 20%, not 0%)
- Quick early wins (first items easy to complete)
- Clear benefit of completing
- Don't block features behind completion

---

## Multi-Channel Onboarding

### Email + In-App Coordination

**Trigger-based emails:**
- Welcome email (immediate)
- Incomplete onboarding (24h, 72h)
- Activation achieved (celebration + next step)
- Feature discovery (days 3, 7, 14)
- Stalled user re-engagement

**Email should:**
- Reinforce in-app actions
- Not duplicate in-app messaging
- Drive back to product with specific CTA
- Be personalized based on actions taken

### Push Notifications (Mobile)

- Permission timing is critical (not immediately)
- Clear value proposition for enabling
- Reserve for genuine value moments
- Re-engagement for stalled users

---

## Engagement Loops

### Building Habits
- What regular action should users take?
- What trigger can prompt return?
- What reward reinforces the behavior?

**Loop structure:**
Trigger → Action → Variable Reward → Investment

**Examples:**
- Trigger: Email digest of activity
- Action: Log in to respond
- Reward: Social engagement, progress, achievement
- Investment: Add more data, connections, content

### Milestone Celebrations
- Acknowledge meaningful achievements
- Show progress relative to journey
- Suggest next milestone
- Shareable moments (social proof generation)

---

## Handling Stalled Users

### Detection
- Define "stalled" criteria (X days inactive, incomplete setup)
- Monitor at cohort level
- Track recovery rate

### Re-engagement Tactics
1. **Email sequence for incomplete onboarding**
   - Reminder of value proposition
   - Address common blockers
   - Offer help/demo/call
   - Deadline/urgency if appropriate

2. **In-app recovery**
   - Welcome back message
   - Pick up where they left off
   - Simplified path to activation

3. **Human touch**
   - For high-value accounts: personal outreach
   - Offer live walkthrough
   - Ask what's blocking them

---

## Measurement

### Key Metrics
- **Activation rate**: % reaching activation event
- **Time to activation**: How long to first value
- **Onboarding completion**: % completing setup
- **Day 1/7/30 retention**: Return rate by timeframe
- **Feature adoption**: Which features get used

### Funnel Analysis
Track drop-off at each step:
```
Signup → Step 1 → Step 2 → Activation → Retention
100%      80%       60%       40%         25%
```

Identify biggest drops and focus there.

---

## Output Format

### Onboarding Audit
For each issue:
- **Finding**: What's happening
- **Impact**: Why it matters
- **Recommendation**: Specific fix
- **Priority**: High/Medium/Low

### Onboarding Flow Design
- **Activation goal**: What they should achieve
- **Step-by-step flow**: Each screen/state
- **Checklist items**: If applicable
- **Empty states**: Copy and CTA
- **Email sequence**: Triggers and content
- **Metrics plan**: What to measure

### Copy Deliverables
- Welcome screen copy
- Checklist items with microcopy
- Empty state copy
- Tooltip content
- Email sequence copy
- Milestone celebration copy

---

## Common Patterns by Product Type

### B2B SaaS Tool
1. Short setup wizard (use case selection)
2. First value-generating action
3. Team invitation prompt
4. Checklist for deeper setup

### Marketplace/Platform
1. Complete profile
2. First search/browse
3. First transaction
4. Repeat engagement loop

### Mobile App
1. Permission requests (strategic timing)
2. Quick win in first session
3. Push notification setup
4. Habit loop establishment

### Content/Social Platform
1. Follow/customize feed
2. First content consumption
3. First content creation
4. Social connection/engagement

---

## Experiment Ideas

### Flow Simplification Experiments

**Reduce Friction**
- Add or remove email verification during onboarding
- Test empty states vs. pre-populated dummy data
- Provide pre-filled templates to accelerate setup
- Add OAuth options for faster account linking
- Reduce number of required onboarding steps

**Step Sequencing**
- Test different ordering of onboarding steps
- Lead with highest-value features first
- Move friction-heavy steps later in flow
- Test required vs. optional step balance

**Progress & Motivation**
- Add progress bars or completion percentages
- Test onboarding checklists (3-5 items vs. 5-7 items)
- Gamify milestones with badges or rewards
- Show "X% complete" messaging

---

### Guided Experience Experiments

**Product Tours**
- Add interactive product tours (Navattic, Storylane)
- Test tooltip-based guidance vs. modal walkthroughs
- Video tutorials for complex workflows
- Self-paced vs. guided tour options

**CTA Optimization**
- Test CTA text variations during onboarding
- Test CTA placement within onboarding screens
- Add in-app tooltips for advanced features
- Sticky CTAs that persist during onboarding

---

### Personalization Experiments

**User Segmentation**
- Segment users by role to show relevant features
- Segment by goal to customize onboarding path
- Create role-specific dashboards
- Ask use-case question to personalize flow

**Dynamic Content**
- Personalized welcome messages
- Industry-specific examples and templates
- Dynamic feature recommendations based on answers

---

### Quick Wins & Engagement Experiments

**Time-to-Value**
- Highlight quick wins early ("Complete your first X")
- Show success messages after key actions
- Display progress celebrations at milestones
- Suggest next steps after each completion

**Support & Help**
- Offer free onboarding calls for complex products
- Add contextual help throughout onboarding
- Test chat support availability during onboarding
- Proactive outreach for stuck users

---

### Email & Multi-Channel Experiments

**Onboarding Emails**
- Personalized welcome email from founder
- Behavior-based emails (triggered by actions/inactions)
- Test email timing and frequency
- Include quick tips and video content

**Feedback Loops**
- Add NPS survey during onboarding
- Ask "What's blocking you?" for incomplete users
- Follow-up based on NPS score

---

## Questions to Ask

If you need more context:
1. What action most correlates with retention?
2. What happens immediately after signup?
3. Where do users currently drop off?
4. What's your activation rate target?
5. Do you have cohort analysis on successful vs. churned users?

---

## Related Skills

- **signup-flow-cro**: For optimizing the signup before onboarding
- **email-sequence**: For onboarding email series
- **paywall-upgrade-cro**: For converting to paid during/after onboarding
- **ab-test-setup**: For testing onboarding changes

## When to Use
This skill is applicable to execute the workflow or actions described in the overview.

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: onboarding-psychologist
description: "One sentence - what this skill does and when to invoke it"
risk: safe
source: community
date_added: "2026-04-04"
---
You are a **Behavioral Psychologist specializing in habit formation and user retention**. Your task is to engineer first-use product experiences that create psychological investment, early wins, habit formation triggers, and identity adoption.

## When to Use
- Use when onboarding needs to reduce friction, uncertainty, and early drop-off.
- Use when the first-use experience should build confidence, momentum, and habit formation.

## CONTEXT GATHERING

Before designing onboarding, establish:

1. **The Target Human** - psychographic profile, JTBD, and emotional state.
2. **The Objective** - the first meaningful success the user must reach.
3. **The Output** - onboarding flow with rationale and habit integration points.
4. **Constraints** - time-to-value, platform, and ethical limits.

If the user's first win is unclear, ask before proceeding.

## PSYCHOLOGICAL FRAMEWORK: IDENTITY-TO-HABIT ONBOARDING

### Mechanism
People commit when they feel early progress, competence, and ownership. Onboarding should create an immediate win, reduce uncertainty, and shift the user's self-perception from outsider to participant. Habit formation is supported by cues, small actions, and repeated success, not by feature tours (Volpp & Loewenstein, 2020; Stawarz et al., 2015; Gillison et al., 2019; Sheeran et al., 2020).

### Execution Steps

**Step 1 - Define the first win**
Choose the smallest meaningful success that proves value.
*Research basis: the progress principle shows that small wins create motivation and momentum (Amabile & Kramer; Gillison et al., 2019).*

**Step 2 - Remove unnecessary setup**
Minimize early decisions, fields, and feature exposure.
*Research basis: early overload interrupts competence and increases drop-off (Hick's Law; Stawarz et al., 2015).*

**Step 3 - Create ownership through action**
Have the user do a small, meaningful task that creates investment.
*Research basis: labor increases attachment and self-perception shifts after action (endowment effect; self-perception theory).*

**Step 4 - Attach a stable cue**
Link the desired behavior to an existing routine or trigger.
*Research basis: habit support is stronger when contextual cues and implementation intentions are explicit (Stawarz et al., 2015).*

**Step 5 - Reinforce identity**
Reflect the user as someone who uses the product successfully.
*Research basis: identity-based behavior change and autonomous motivation improve persistence (Sheeran et al., 2020; Ng et al., 2012).*

## DECISION MATRIX

### Variable: user readiness
- If low -> shorten the path and make the first win almost effortless.
- If medium -> introduce one guided challenge and one visible payoff.
- If high -> move quickly to depth and configuration.

### Variable: habit target
- If the product is used daily -> optimize for cue stability and repeated success.
- If the product is used occasionally -> optimize for recall, return, and quick re-entry.
- If the product is high stakes -> optimize for confidence and reassurance, not streak pressure.

### Variable: motivation source
- If motivation is intrinsic -> emphasize autonomy and mastery.
- If motivation is extrinsic -> emphasize outcome, reward, and deadline.
- If motivation is mixed -> layer both carefully.

## FAILURE MODES - DO NOT DO THESE

**Failure Mode 1**
- Agents typically: give users a tour of every feature.
- Why it fails psychologically: feature tours delay value and increase cognitive load.
- Instead: get to the first win fast.

**Failure Mode 2**
- Agents typically: over-automate the first session.
- Why it fails psychologically: no action means no ownership or identity shift.
- Instead: preserve one meaningful action by the user.

**Failure Mode 3**
- Agents typically: use habit language before value is felt.
- Why it fails psychologically: habit cannot form before competence and reward exist.
- Instead: prove value first, then build routine.

## ETHICAL GUARDRAILS

This skill must:
- Build habits through value, not addiction mechanics.
- Preserve user autonomy.
- Avoid streak pressure that harms users.

The line between persuasion and manipulation is helping the user experience genuine progress versus engineering compulsive engagement detached from user benefit. Never cross it.

## SKILL CHAINING

Before invoking this skill, the agent should have completed:
- [ ] `@customer-psychographic-profiler`
- [ ] `@jobs-to-be-done-analyst`
- [ ] `@ux-persuasion-engineer`

This skill's output feeds into:
- [ ] `@sequence-psychologist`
- [ ] `@identity-mirror`
- [ ] `@copywriting-psychologist`

## OUTPUT QUALITY CHECK

Before finalizing output, the agent asks:
- [ ] Did I define the first win clearly?
- [ ] Did I reduce setup friction?
- [ ] Did I create ownership and identity shift?
- [ ] Did I attach a stable cue to the behavior?
- [ ] Does the flow feel supportive rather than coercive?

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: one-drive-automation
description: "Automate OneDrive file management, search, uploads, downloads, sharing, permissions, and folder operations via Rube MCP (Composio). Always search tools first for current schemas."
risk: critical
source: community
date_added: "2026-02-27"
---

# OneDrive Automation via Rube MCP

Automate OneDrive operations including file upload/download, search, folder management, sharing links, permissions management, and drive browsing through Composio's OneDrive toolkit.

## Prerequisites

- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
- Active OneDrive connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `one_drive`
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas

## Setup

**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.

1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `one_drive`
3. If connection is not ACTIVE, follow the returned auth link to complete Microsoft OAuth
4. Confirm connection status shows ACTIVE before running any workflows

## Core Workflows

### 1. Search and Browse Files

**When to use**: User wants to find files or browse folder contents in OneDrive

**Tool sequence**:
1. `ONE_DRIVE_GET_DRIVE` - Verify drive access and get drive details [Prerequisite]
2. `ONE_DRIVE_SEARCH_ITEMS` - Keyword search across filenames, metadata, and content [Required]
3. `ONE_DRIVE_ONEDRIVE_LIST_ITEMS` - List all items in the root of a drive [Optional]
4. `ONE_DRIVE_GET_ITEM` - Get detailed metadata for a specific item, expand children [Optional]
5. `ONE_DRIVE_ONEDRIVE_FIND_FILE` - Find a specific file by exact name in a folder [Optional]
6. `ONE_DRIVE_ONEDRIVE_FIND_FOLDER` - Find a specific folder by name [Optional]
7. `ONE_DRIVE_LIST_DRIVES` - List all accessible drives [Optional]

**Key parameters**:
- `q`: Search query (plain keywords only, NOT KQL syntax)
- `search_scope`: `"root"` (folder hierarchy) or `"drive"` (includes shared items)
- `top`: Max items per page (default 200)
- `skip_token`: Pagination token from `@odata.nextLink`
- `select`: Comma-separated fields to return (e.g., `"id,name,webUrl,size"`)
- `orderby`: Sort order (e.g., `"name asc"`, `"name desc"`)
- `item_id`: Item ID for `GET_ITEM`
- `expand_relations`: Array like `["children"]` or `["thumbnails"]` for `GET_ITEM`
- `user_id`: `"me"` (default) or specific user ID/email

**Pitfalls**:
- `ONE_DRIVE_SEARCH_ITEMS` does NOT support KQL operators (`folder:`, `file:`, `filetype:`, `path:`); these are treated as literal text
- Wildcard characters (`*`, `?`) are NOT supported and are auto-removed; use file extension keywords instead (e.g., `"pdf"` not `"*.pdf"`)
- `ONE_DRIVE_ONEDRIVE_LIST_ITEMS` returns only root-level contents; use recursive `ONE_DRIVE_GET_ITEM` with `expand_relations: ["children"]` for deeper levels
- Large folders paginate; always follow `skip_token` / `@odata.nextLink` until exhausted
- Some drive ID formats may return "ObjectHandle is Invalid" errors due to Microsoft Graph API limitations

### 2. Upload and Download Files

**When to use**: User wants to upload files to OneDrive or download files from it

**Tool sequence**:
1. `ONE_DRIVE_ONEDRIVE_FIND_FOLDER` - Locate the target folder [Prerequisite]
2. `ONE_DRIVE_ONEDRIVE_UPLOAD_FILE` - Upload a file to a specified folder [Required for upload]
3. `ONE_DRIVE_DOWNLOAD_FILE` - Download a file by item ID [Required for download]
4. `ONE_DRIVE_GET_ITEM` - Get file details before download [Optional]

**Key parameters**:
- `file`: FileUploadable object with `s3key`, `mimetype`, and `name` for uploads
- `folder`: Destination path (e.g., `"/Documents/Reports"`) or folder ID for uploads
- `item_id`: File's unique identifier for downloads
- `file_name`: Desired filename with extension for downloads
- `drive_id`: Specific drive ID (for SharePoint or OneDrive for Business)
- `user_id`: `"me"` (default) or specific user identifier

**Pitfalls**:
- Upload automatically renames on conflict (no overwrite option by default)
- Large files are automatically handled via chunking
- `drive_id` overrides `user_id` when both are provided
- Item IDs vary by platform: OneDrive for Business uses `01...` prefix, OneDrive Personal uses `HASH!NUMBER` format
- Item IDs are case-sensitive; use exactly as returned from API

### 3. Share Files and Manage Permissions

**When to use**: User wants to share files/folders or manage who has access

**Tool sequence**:
1. `ONE_DRIVE_ONEDRIVE_FIND_FILE` or `ONE_DRIVE_ONEDRIVE_FIND_FOLDER` - Locate the item [Prerequisite]
2. `ONE_DRIVE_GET_ITEM_PERMISSIONS` - Check current permissions [Prerequisite]
3. `ONE_DRIVE_INVITE_USER_TO_DRIVE_ITEM` - Grant access to specific users [Required]
4. `ONE_DRIVE_CREATE_LINK` - Create a shareable link [Optional]
5. `ONE_DRIVE_UPDATE_DRIVE_ITEM_METADATA` - Update item metadata [Optional]

**Key parameters**:
- `item_id`: The file or folder to share
- `recipients`: Array of objects with `email` or `object_id`
- `roles`: Array with `"read"` or `"write"`
- `send_invitation`: `true` to send notification email, `false` for silent permission grant
- `require_sign_in`: `true` to require authentication to access
- `message`: Custom message for invitation (max 2000 characters)
- `expiration_date_time`: ISO 8601 date for permission expiry
- `retain_inherited_permissions`: `true` (default) to keep existing inherited permissions

**Pitfalls**:
- Using wrong `item_id` with `INVITE_USER_TO_DRIVE_ITEM` changes permissions on unintended items; always verify first
- Write or higher roles are impactful; get explicit user confirmation before granting
- `GET_ITEM_PERMISSIONS` returns inherited and owner entries; do not assume response only reflects recent changes
- `permissions` cannot be expanded via `ONE_DRIVE_GET_ITEM`; use the separate permissions endpoint
- At least one of `require_sign_in` or `send_invitation` must be `true`

### 4. Manage Folders (Create, Move, Delete, Copy)

**When to use**: User wants to create, move, rename, delete, or copy files and folders

**Tool sequence**:
1. `ONE_DRIVE_ONEDRIVE_FIND_FOLDER` - Locate source and destination folders [Prerequisite]
2. `ONE_DRIVE_ONEDRIVE_CREATE_FOLDER` - Create a new folder [Required for create]
3. `ONE_DRIVE_MOVE_ITEM` - Move a file or folder to a new location [Required for move]
4. `ONE_DRIVE_COPY_ITEM` - Copy a file or folder (async operation) [Required for copy]
5. `ONE_DRIVE_DELETE_ITEM` - Move item to recycle bin [Required for delete]
6. `ONE_DRIVE_UPDATE_DRIVE_ITEM_METADATA` - Rename or update item properties [Optional]

**Key parameters**:
- `name`: Folder name for creation or new name for rename/copy
- `parent_folder`: Path (e.g., `"/Documents/Reports"`) or folder ID for creation
- `itemId`: Item to move
- `parentReference`: Object with `id` (destination folder ID) for moves: `{"id": "folder_id"}`
- `item_id`: Item to copy or delete
- `parent_reference`: Object with `id` and optional `driveId` for copy destination
- `@microsoft.graph.conflictBehavior`: `"fail"`, `"replace"`, or `"rename"` for copies
- `if_match`: ETag for optimistic concurrency on deletes

**Pitfalls**:
- `ONE_DRIVE_MOVE_ITEM` does NOT support cross-drive moves; use `ONE_DRIVE_COPY_ITEM` for cross-drive transfers
- `parentReference` for moves requires folder ID (not folder name); resolve with `ONEDRIVE_FIND_FOLDER` first
- `ONE_DRIVE_COPY_ITEM` is asynchronous; response provides a URL to monitor progress
- `ONE_DRIVE_DELETE_ITEM` moves to recycle bin, not permanent deletion
- Folder creation auto-renames on conflict (e.g., "New Folder" becomes "New Folder 1")
- Provide either `name` or `parent_reference` (or both) for `ONE_DRIVE_COPY_ITEM`

### 5. Track Changes and Drive Information

**When to use**: User wants to monitor changes or get drive/quota information

**Tool sequence**:
1. `ONE_DRIVE_GET_DRIVE` - Get drive properties and metadata [Required]
2. `ONE_DRIVE_GET_QUOTA` - Check storage quota (total, used, remaining) [Optional]
3. `ONE_DRIVE_LIST_SITE_DRIVE_ITEMS_DELTA` - Track changes in SharePoint site drives [Optional]
4. `ONE_DRIVE_GET_ITEM_VERSIONS` - Get version history of a file [Optional]

**Key parameters**:
- `drive_id`: Drive identifier (or `"me"` for personal drive)
- `site_id`: SharePoint site identifier for delta tracking
- `token`: Delta token (`"latest"` for current state, URL for next page, or timestamp)
- `item_id`: File ID for version history

**Pitfalls**:
- Delta queries are only available for SharePoint site drives via `ONE_DRIVE_LIST_SITE_DRIVE_ITEMS_DELTA`
- Token `"latest"` returns current delta token without items (useful as starting point)
- Deep or large drives can take several minutes to crawl; use batching and resume logic

## Common Patterns

### ID Resolution
- **User**: Use `"me"` for authenticated user or specific user email/GUID
- **Item ID from find**: Use `ONE_DRIVE_ONEDRIVE_FIND_FILE` or `ONE_DRIVE_ONEDRIVE_FIND_FOLDER` to get item IDs
- **Item ID from search**: Extract from `ONE_DRIVE_SEARCH_ITEMS` results
- **Drive ID**: Use `ONE_DRIVE_LIST_DRIVES` or `ONE_DRIVE_GET_DRIVE` to discover drives
- **Folder path to ID**: Use `ONE_DRIVE_ONEDRIVE_FIND_FOLDER` with path, then extract ID from response

ID formats vary by platform:
- OneDrive for Business/SharePoint: `01NKDM7HMOJTVYMDOSXFDK2QJDXCDI3WUK`
- OneDrive Personal: `D4648F06C91D9D3D!54927`

### Pagination
OneDrive uses token-based pagination:
- Follow `@odata.nextLink` or `skip_token` until no more pages
- Set `top` for page size (varies by endpoint)
- `ONE_DRIVE_ONEDRIVE_LIST_ITEMS` auto-handles pagination internally
- Aggressive parallel requests can trigger HTTP 429; honor `Retry-After` headers

### Path vs ID
Most OneDrive tools accept either paths or IDs:
- **Paths**: Start with `/` (e.g., `"/Documents/Reports"`)
- **IDs**: Use unique item identifiers from API responses
- **Item paths for permissions**: Use `:/path/to/item:/` format

## Known Pitfalls

### ID Formats
- Item IDs are case-sensitive and platform-specific
- Never use web URLs, sharing links, or manually constructed identifiers as item IDs
- Always use IDs exactly as returned from Microsoft Graph API

### Rate Limits
- Aggressive parallel `ONE_DRIVE_GET_ITEM` calls can trigger HTTP 429 Too Many Requests
- Honor `Retry-After` headers and implement throttling
- Deep drive crawls should use batching with delays

### Search Limitations
- No KQL support; use plain keywords only
- No wildcard characters; use extension keywords (e.g., `"pdf"` not `"*.pdf"`)
- No path-based filtering in search; use folder listing instead
- `q='*'` wildcard-only queries return HTTP 400 invalidRequest

### Parameter Quirks
- `drive_id` overrides `user_id` when both are provided
- `permissions` cannot be expanded via `GET_ITEM`; use dedicated permissions endpoint
- Move operations require folder IDs in `parentReference`, not folder names
- Copy operations are asynchronous; response provides monitoring URL

## Quick Reference

| Task | Tool Slug | Key Params |
|------|-----------|------------|
| Search files | `ONE_DRIVE_SEARCH_ITEMS` | `q`, `search_scope`, `top` |
| List root items | `ONE_DRIVE_ONEDRIVE_LIST_ITEMS` | `user_id`, `select`, `top` |
| Get item details | `ONE_DRIVE_GET_ITEM` | `item_id`, `expand_relations` |
| Find file by name | `ONE_DRIVE_ONEDRIVE_FIND_FILE` | `name`, `folder` |
| Find folder by name | `ONE_DRIVE_ONEDRIVE_FIND_FOLDER` | `name`, `folder` |
| Upload file | `ONE_DRIVE_ONEDRIVE_UPLOAD_FILE` | `file`, `folder` |
| Download file | `ONE_DRIVE_DOWNLOAD_FILE` | `item_id`, `file_name` |
| Create folder | `ONE_DRIVE_ONEDRIVE_CREATE_FOLDER` | `name`, `parent_folder` |
| Move item | `ONE_DRIVE_MOVE_ITEM` | `itemId`, `parentReference` |
| Copy item | `ONE_DRIVE_COPY_ITEM` | `item_id`, `parent_reference`, `name` |
| Delete item | `ONE_DRIVE_DELETE_ITEM` | `item_id` |
| Share with users | `ONE_DRIVE_INVITE_USER_TO_DRIVE_ITEM` | `item_id`, `recipients`, `roles` |
| Create share link | `ONE_DRIVE_CREATE_LINK` | `item_id`, link type |
| Get permissions | `ONE_DRIVE_GET_ITEM_PERMISSIONS` | `item_id` |
| Update metadata | `ONE_DRIVE_UPDATE_DRIVE_ITEM_METADATA` | `item_id`, fields |
| Get drive info | `ONE_DRIVE_GET_DRIVE` | `drive_id` |
| List drives | `ONE_DRIVE_LIST_DRIVES` | user/group/site scope |
| Get quota | `ONE_DRIVE_GET_QUOTA` | (none) |
| Track changes | `ONE_DRIVE_LIST_SITE_DRIVE_ITEMS_DELTA` | `site_id`, `token` |
| Version history | `ONE_DRIVE_GET_ITEM_VERSIONS` | `item_id` |

## When to Use
This skill is applicable to execute the workflow or actions described in the overview.

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: ontoly-software-graph
description: "Use Ontoly's deterministic Software Graph, MCP server, and agent skills for architecture review, request tracing, impact analysis, and dependency analysis."
category: development
risk: critical
source: community
source_repo: 0xsarwagya/ontoly
source_type: community
date_added: "2026-07-14"
author: 0xsarwagya
tags: [software-graph, codebase-analysis, mcp, typescript, architecture, impact-analysis]
tools: [claude, cursor, gemini, codex, antigravity]
license: MIT
license_source: "https://github.com/0xsarwagya/ontoly/blob/main/LICENSE"
---

# Ontoly Software Graph

## Overview

Ontoly builds a deterministic Software Graph from a TypeScript repository and exposes it through CLI queries, MCP capabilities, and agent skills. Use this skill when a coding agent needs evidence-backed codebase understanding before searching files directly.

This skill is an operating guide for the public Ontoly project. It does not contain compiler logic; all software understanding should come from Ontoly's generated graph, semantic model, query engine, and MCP server.

## When to Use This Skill

- Use when the user asks for repository architecture, module ownership, or onboarding help.
- Use when tracing a request, route, controller, service, provider, dependency, or call chain.
- Use when estimating impact for removing, renaming, or refactoring a symbol, module, package, route, or service.
- Use when reviewing dependency topology, circular imports, dead code, configuration usage, or environment variables.
- Use when the user explicitly wants Ontoly, Software Graph, MCP, graph validation, semantic coverage, or agent skills.

## How It Works

### Step 1: Verify Ontoly Is Available

Check whether the repository already has Ontoly outputs such as `.ontoly/`, `SoftwareGraph.json`, validation reports, or documented Ontoly scripts. If the `ontoly` command is unavailable, ask the user whether to install or use the repository's documented package manager command.

Recommended local checks:

```bash
ontoly --help
find . -maxdepth 3 \( -name "SoftwareGraph.json" -o -name ".ontoly" \) -print
```

### Step 2: Build or Refresh the Graph

Only run a graph build in the repository the user asked about. Tell the user that graph generation may create local Ontoly artifacts before running it.

```bash
ontoly build .
```

If the project documents a different command, prefer the documented command over guessing.

### Step 3: Check Trust, Diagnostics, and Coverage

Before answering architectural questions, inspect Ontoly diagnostics, graph statistics, trust, and semantic coverage. Treat unresolved imports, low trust, missing framework detection, or graph validation failures as answer constraints.

Use the CLI or MCP capabilities exposed by the installed Ontoly version. Prefer structured graph queries over text search.

### Step 4: Use Ontoly MCP Capabilities

Start or connect to the Ontoly MCP server when the host supports MCP:

```bash
ontoly mcp
```

Use capabilities such as architecture summaries, dependency analysis, request tracing, impact analysis, configuration lookup, framework reports, dead-code analysis, and graph validation when available.

### Step 5: Answer With Evidence

Every answer should include:

- The Ontoly capability or query used.
- The node, edge, route, package, or diagnostic evidence that supports the answer.
- A confidence statement derived from graph evidence.
- Any known limitations caused by missing graph regions or diagnostics.

### Step 6: Fall Back Gracefully

Only inspect repository files directly when Ontoly cannot answer, the graph is missing, diagnostics make the graph untrustworthy for the question, or the user asks for source-level verification. When falling back, explain which graph evidence was insufficient.

## Examples

### Architecture Review

User asks: "Explain this repository."

Workflow:

1. Verify or build the Ontoly graph.
2. Check graph trust, diagnostics, detected frameworks, packages, modules, services, routes, and largest dependency hubs.
3. Use Ontoly's architecture summary or equivalent query.
4. Report the architecture with graph evidence and confidence.

### Request Tracing

User asks: "Trace the login flow."

Workflow:

1. Search graph nodes for authentication routes and controllers.
2. Trace route-to-controller-to-service-to-repository relationships.
3. Include unresolved edges or missing relationships as limitations.
4. Avoid opening source files unless the graph cannot identify the flow.

### Impact Analysis

User asks: "What breaks if I remove UserRepository?"

Workflow:

1. Locate the graph node for `UserRepository`.
2. Query callers, consumers, dependency injection edges, modules, routes, and packages that reference it.
3. Separate direct dependents from transitive impact.
4. Include confidence based on explicit graph relationships.

## Best Practices

- Prefer Ontoly graph queries before grep, AST parsing, or broad file search.
- Keep graph evidence separate from inference.
- Treat diagnostics as part of the answer, not as noise.
- Use exact node IDs, route paths, package names, and relationship names when available.
- Rebuild the graph after large user changes before making claims about current architecture.
- Keep fallbacks narrow and explain why they were needed.

## Limitations

- Ontoly does not replace compiler, test, or runtime validation.
- Graph quality depends on the Ontoly version, supported language frontend, repository setup, and diagnostics.
- Missing or partial framework detection lowers confidence for framework-specific answers.
- Do not claim a relationship exists unless it is present in the graph or clearly labeled as an inference.
- Stop and ask for clarification if the repository path, target graph, or requested analysis scope is ambiguous.

## Security & Safety Notes

- Run Ontoly only on repositories the user is authorized to analyze.
- Do not send graph files, source code, environment variables, diagnostics, or repository metadata to external services unless the user explicitly requests it.
- Treat environment-variable nodes, configuration nodes, and diagnostics as potentially sensitive.
- Graph generation is local analysis but can create files such as graph output, diagnostics, indexes, or caches inside the repository.
- Do not execute project build scripts, package installation, or network commands unless they are documented by the repository or approved by the user.

## Common Pitfalls

- **Problem:** Answering from file search even though the graph already contains the relationship.
  **Solution:** Query Ontoly first and use file inspection only as a fallback.

- **Problem:** Reporting low-confidence inference as a graph fact.
  **Solution:** Label the claim as inferred and cite the supporting graph evidence separately.

- **Problem:** Ignoring diagnostics.
  **Solution:** Include graph validation and compiler diagnostics when they affect confidence.

## Related Skills

- `@developer-onboarding` - Use for broad onboarding when Ontoly is unavailable.
- `@sdk-dx` - Use for SDK design and developer experience reviews after Ontoly identifies public APIs.
- `@api-onboarding` - Use for API-specific onboarding when route and operation evidence is available.


---
name: open-dynamic-workflows
description: "Plan, orchestrate, and adversarially verify parallel AI coding agents with a dynamic multi-agent workflow engine."
category: ai-agents
risk: critical
source: community
source_repo: Suraj1235/open-dynamic-workflows
source_type: community
date_added: "2026-06-06"
author: Suraj1235
tags: [multi-agent, orchestration, workflow, adversarial-verification, coding-agents]
tools: [claude, cursor, codex, gemini, antigravity]
# Optional: declare the upstream license if source_repo is set
license: "MIT"
license_source: "https://github.com/Suraj1235/open-dynamic-workflows/blob/main/LICENSE"
---

# Open Dynamic Workflows

## Overview

Open Dynamic Workflows (ODW) is an open-source dynamic multi-agent workflow engine for AI coding agents such as OpenCode, Codex, Antigravity, and VS Code. It lets you plan a task, orchestrate multiple agents working in parallel, and adversarially verify their output before it lands. ODW ships a Codex/Antigravity skill folder (`SKILL.md` plus a daemon bridge) and an OpenCode plugin, and it is bring-your-own-model (Anthropic, OpenAI-compatible, or Ollama). This skill is adapted from the community project at `Suraj1235/open-dynamic-workflows`.

## When to Use This Skill

- Use when you need to decompose a coding task into independent subtasks and run multiple agents in parallel.
- Use when working across more than one AI coding tool (OpenCode, Codex, Antigravity, VS Code) and want a single orchestration layer.
- Use when the user asks for adversarial review or verification of agent-generated changes before merging.

## How It Works

### Step 1: Plan

ODW takes a high-level goal and produces a dynamic workflow graph of subtasks, identifying which can run in parallel and which have dependencies.

### Step 2: Orchestrate

The engine dispatches subtasks to parallel agents through the OpenCode plugin or the Codex/Antigravity daemon bridge, using your configured model provider (Anthropic, OpenAI-compatible, or Ollama).

### Step 3: Adversarially Verify

Completed work is routed through an adversarial verification pass that challenges the output before results are synthesized and returned.

## Examples

### Example 1: Run a parallel workflow

ODW is installed from source (clone the repo, then `npm install`). The CLI is
`odw-daemon` — run it as `npm run odw -- <args>` from inside the repo, or as
`npx odw-daemon <args>` / a global `odw-daemon` if you link the bin.

```bash
# Configure your model provider (bring-your-own-model)
export ANTHROPIC_API_KEY=...        # or an OpenAI-compatible / Ollama endpoint

# One-time setup: generate ~/.odw/config.json
npm run setup

# Start the local workflow daemon (once)
npm run odw -- start

# Plan, orchestrate, and verify a task across parallel agents
npm run odw -- run --prompt "refactor the auth module and add tests"
```

### Example 2: Use the Codex/Antigravity skill bridge

```bash
# ODW ships a SKILL.md + daemon bridge consumed by Codex / Antigravity.
# Start the daemon, then run a saved orchestration script through it:
npm run odw -- start
npm run odw -- run --script examples/workflows/studio-prime.workflow.js --cwd .
```

## Best Practices

- ✅ Scope each subtask so agents can run without shared state.
- ✅ Keep the adversarial verification pass enabled before merging agent output.
- ❌ Don't run interdependent subtasks in parallel without declaring their dependencies.
- ❌ Don't commit provider API keys; use environment variables or a secrets manager.

## Limitations

- This skill does not replace environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, or safety boundaries are missing.

## Security & Safety Notes

- ODW executes agent-generated code and shell commands; run it only in an authorized, local, or sandboxed environment.
- Model provider credentials (Anthropic / OpenAI-compatible / Ollama) must be supplied via environment variables, never committed to source.
- Review adversarial-verification output before applying changes to a production branch.

## Common Pitfalls

- **Problem:** Parallel agents collide on the same files.
  **Solution:** Give each subtask exclusive file/module ownership and run conflicting tasks sequentially.

## Related Skills

- `@multi-agent-orchestration` - When coordinating multiple agents on one goal.
- `@code-review` - How adversarial verification complements human review.


---
name: open-source-marketing
description: When the user wants to market an open source project authentically. Trigger phrases include "open source marketing," "OSS marketing," "GitHub marketing," "promote my library," "grow stars," "launch open source," "open source growth," or "contributor marketing."
risk: critical
source: https://github.com/jonathimer/devmarketing-skills/tree/main/skills/open-source-marketing
source_repo: jonathimer/devmarketing-skills
source_type: community
date_added: 2026-07-01
license: MIT
license_source: https://github.com/jonathimer/devmarketing-skills/blob/main/LICENSE
---

# Open Source Marketing
## When to Use

Use this skill when you need when the user wants to market an open source project authentically. Trigger phrases include "open source marketing," "OSS marketing," "GitHub marketing," "promote my library," "grow stars," "launch open source," "open source growth," or "contributor marketing.".

This skill helps you market open source projects without being cringe. Covers GitHub optimization, community building, contributor experience, launch strategies, and sustainable growth.

---

## Before You Start

**Load your audience context first.** Read `.agents/developer-audience-context.md` to understand:

- Who would use this project (role, tech stack, problem)
- Where they discover tools (communities, social, search)
- What alternatives exist (why would they switch?)
- How they evaluate OSS (stars, activity, docs, community)

If the context file doesn't exist, run the `developer-audience-context` skill first.

---

## The OSS Marketing Mindset

### What Works vs. What Doesn't

| Works | Doesn't Work |
|-------|--------------|
| Building in public | Spamming "check out my project" |
| Solving real problems | Building solutions seeking problems |
| Genuine community engagement | Transactional follows/unfollows |
| Great docs and DX | "The code is self-documenting" |
| Celebrating contributors | Taking sole credit |
| Consistent presence | Launch and disappear |

### The Growth Equation

```
Growth = (Real value) × (Discoverability) × (First-use experience)
```

If any factor is zero, growth is zero.

---

## GitHub Optimization

### README Excellence

Your README is your landing page. Optimize it.

**Structure:**

```markdown
# Project Name

[One-line description that explains what it does]

[Badges: build status, version, license, downloads]

[Screenshot or GIF showing it in action]

## Why [Project Name]?

- ✅ [Benefit 1 - specific, not fluffy]
- ✅ [Benefit 2]
- ✅ [Benefit 3]

## Quick Start

\`\`\`bash
npm install project-name
\`\`\`

\`\`\`javascript
// 5 lines that show immediate value
\`\`\`

## Installation

[Detailed installation for all platforms]

## Usage

[Core usage patterns with examples]

## Documentation

[Link to full docs]

## Contributing

We love contributions! See [CONTRIBUTING.md](https://github.com/jonathimer/devmarketing-skills/tree/main/skills/open-source-marketing/CONTRIBUTING.md).

## License

[License type] - see [LICENSE](https://github.com/jonathimer/devmarketing-skills/tree/main/skills/open-source-marketing/LICENSE)
```

### README Checklist

| Element | Why It Matters |
|---------|---------------|
| **Clear name** | Memorable, searchable, spellable |
| **One-liner** | "A [type] for [audience] that [does what]" |
| **Badges** | Social proof, health signals |
| **Visual** | GIF > Screenshot > Nothing |
| **Quick start** | <5 lines to first value |
| **Why this?** | Differentiation from alternatives |
| **Installation** | All platforms, copy-paste |
| **Examples** | Real use cases, not contrived |
| **Docs link** | More detail available |
| **Contributing** | Community welcome |

### Repository Optimization

| Element | Best Practice |
|---------|--------------|
| **Description** | 100 chars max, keyword-rich |
| **Topics** | 5-10 relevant tags for discoverability |
| **Website** | Link to docs or landing page |
| **Releases** | Semantic versioning, changelogs |
| **Issues** | Templates for bugs/features |
| **Discussions** | Enable for community Q&A |
| **Sponsors** | Enable if you want funding |

### Issue & PR Templates

**Bug report template:**

```markdown
---
name: Bug Report
about: Report a bug to help us improve
---

## Bug Description
[Clear description]

## Steps to Reproduce
1.
2.
3.

## Expected Behavior
[What should happen]

## Actual Behavior
[What actually happens]

## Environment
- OS:
- Node version:
- Package version:

## Additional Context
[Screenshots, logs, etc.]
```

**Feature request template:**

```markdown
---
name: Feature Request
about: Suggest an idea for this project
---

## Problem
[What problem does this solve?]

## Proposed Solution
[How would you like it to work?]

## Alternatives Considered
[Other approaches you've thought about]

## Additional Context
[Examples, mockups, etc.]
```

---

## Community Building

### Community Spaces

| Platform | Best For | Setup Effort |
|----------|----------|--------------|
| **GitHub Discussions** | Q&A, announcements | Low |
| **Discord** | Real-time chat, community feel | Medium |
| **Slack** | Enterprise communities | Medium |
| **Forum (Discourse)** | Async, searchable discussions | High |

Start with GitHub Discussions. Add Discord when you have 50+ active users.

### Community Principles

| Principle | Implementation |
|-----------|----------------|
| **Be responsive** | Respond to issues within 48 hours (even if just "looking into it") |
| **Celebrate contributions** | Thank every contributor publicly |
| **Be transparent** | Share roadmap, explain decisions |
| **Set expectations** | Clear SLA for maintainer response |
| **Welcome newcomers** | "good first issue" labels, mentorship |

### Contributor Funnel

```
User → Star → Issue → PR → Regular Contributor → Maintainer
```

Optimize each transition:

| Transition | How to Improve |
|------------|----------------|
| User → Star | Great README, visible value |
| Star → Issue | Clear issue templates, welcoming tone |
| Issue → PR | "good first issue" labels, CONTRIBUTING.md |
| PR → Regular | Quick review, encouraging feedback |
| Regular → Maintainer | Trust, shared ownership |

---

## Contributor Experience

### CONTRIBUTING.md Essentials

```markdown
# Contributing to [Project]

First off, thanks for considering contributing! ❤

## Quick Start

1. Fork the repo
2. Clone your fork
3. Install dependencies: `npm install`
4. Create a branch: `git checkout -b my-feature`
5. Make your changes
6. Run tests: `npm test`
7. Commit: `git commit -m "Add my feature"`
8. Push: `git push origin my-feature`
9. Open a Pull Request

## Development Setup

[Detailed setup instructions]

## Code Style

- We use [Prettier/ESLint config]
- Run `npm run lint` before committing
- [Other conventions]

## Commit Messages

We follow [Conventional Commits](https://conventionalcommits.org/):
- `feat: add new feature`
- `fix: resolve bug`
- `docs: update readme`
- `chore: update dependencies`

## Pull Request Process

1. Update docs if needed
2. Add tests for new features
3. Ensure CI passes
4. Get one approval

## Good First Issues

Look for issues labeled `good first issue` — these are great starting points!

## Questions?

Open a Discussion or reach out on Discord.
```

### "Good First Issue" Strategy

Create genuinely approachable issues:

| Good | Not Good |
|------|----------|
| "Add TypeScript types for X function" | "Refactor the entire codebase" |
| "Fix typo in README" | "Performance optimization" |
| "Add test for Y method" | "Debug intermittent CI failure" |
| "Update dependency Z" | "Implement feature from RFC" |

For each good first issue:
- Explain context and why it matters
- Link to relevant code files
- Describe expected outcome
- Offer to help in comments

---

## Launch Strategies

### Pre-Launch Checklist

| Task | Done? |
|------|-------|
| README polished | ☐ |
| Quick start works | ☐ |
| Docs exist | ☐ |
| 3+ examples/demos | ☐ |
| Tests passing | ☐ |
| License chosen | ☐ |
| CONTRIBUTING.md | ☐ |
| Issue templates | ☐ |
| Social preview image | ☐ |
| 5-10 GitHub topics | ☐ |

### Launch Day Playbook

**Timeline:**

| Time | Action |
|------|--------|
| **Day before** | Final README review, prep all posts |
| **Launch morning** | HN post (best: 6-8am PT, Tuesday-Thursday) |
| **+1 hour** | Twitter thread |
| **+2 hours** | Reddit post to relevant subreddits |
| **Throughout day** | Respond to all comments/questions |
| **End of day** | Thank everyone, share metrics |

### Platform-Specific Tactics

**Hacker News:**
- Title: Descriptive, no hype ("Show HN: X — a Y for Z")
- First comment: Explain motivation, tech decisions
- Be available to respond for hours
- Don't ask for upvotes (instant death)

**Reddit:**
- Find 2-3 relevant subreddits (not just r/programming)
- Read the rules first
- Be a community member, not a marketer
- Share genuinely useful context

**Twitter/X:**
- Thread format: Problem → Solution → Demo → Link
- Include GIF/video
- Tag relevant accounts (framework authors, etc.)
- Share builds-in-public journey

**Dev.to / Hashnode:**
- Write a "Why I Built This" article
- Technical depth, personal story
- Cross-post from your blog

### Post-Launch

| Week | Focus |
|------|-------|
| **Week 1** | Respond to all feedback, fix bugs |
| **Week 2** | Blog post: "What I learned from launch" |
| **Week 3** | Start regular updates, ship new feature |
| **Month 1** | Community building, contributor docs |
| **Ongoing** | Consistent presence, regular releases |

---

## Sustainable Growth

### Growth Tactics

| Tactic | Effort | Impact | Timeline |
|--------|--------|--------|----------|
| **SEO-optimized docs** | Medium | High | 3-6 months |
| **Integration tutorials** | Medium | High | 1-2 months |
| **Conference talks** | High | Medium | 3-6 months |
| **Comparison content** | Low | Medium | 1-2 months |
| **Guest blog posts** | Medium | Medium | 1-2 months |
| **Newsletter features** | Low | Low-Medium | 2-4 weeks |
| **Twitter presence** | Medium | Medium | Ongoing |

### Content Strategy for OSS

| Content Type | Purpose |
|--------------|---------|
| **"Why we built X"** | Launch story, motivation |
| **"X vs Y vs Z"** | Capture comparison searches |
| **"Migrating from Y to X"** | Convert competitor users |
| **"X + [Popular Tool]"** | Capture integration searches |
| **"How We Use X at [Company]"** | Social proof, real use case |
| **"X Performance Benchmarks"** | Technical credibility |

### Avoiding Burnout

| Risk | Mitigation |
|------|------------|
| **Overwhelming issues** | Set response SLA expectations |
| **Feature demands** | Public roadmap, RFC process |
| **Solo maintenance** | Actively recruit co-maintainers |
| **Always-on pressure** | Scheduled "office hours" vs. 24/7 |
| **Negative feedback** | Code of conduct, moderation |

---

## Metrics That Matter

### Vanity vs. Value

| Vanity Metric | Value Metric |
|---------------|--------------|
| Stars | Active issues + PRs |
| Forks | Returned contributors |
| Downloads | Weekly active users |
| Twitter followers | Community engagement |

### What to Track

| Metric | Where to Find It |
|--------|------------------|
| **Stars over time** | GitHub Insights, Star History |
| **Clones** | GitHub Traffic |
| **Referrers** | GitHub Traffic |
| **npm downloads** | npm-stat.com |
| **Community size** | Discord/Slack member count |
| **Contributor count** | GitHub Insights |
| **Issue response time** | Manual tracking |

---

## Tools

| Tool | Use Case |
|------|----------|
| **[Octolens](https://octolens.com)** | Monitor mentions of your project across GitHub, HN, Reddit, Twitter, and Stack Overflow. Track competitor projects. Find contributors asking questions. |
| **Star History** | Track star growth over time |
| **npm-stat** | Download statistics |
| **GitHub Traffic** | Views, clones, referrers |
| **Shield.io** | Dynamic badges |
| **All Contributors** | Recognize all contributors |
| **Probot** | Automate GitHub workflows |

---

## Related Skills

- `developer-audience-context` — Know who your users are
- `community-building` — Build Discord/Slack community
- `devrel-content` — Create supporting content
- `developer-advocacy` — Conference talks, podcasts
- `hacker-news-strategy` — Launch and engage on HN

## Limitations

- Use this skill only when the task clearly matches its upstream source and local project context.
- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.


---
name: openapi-spec-generation
description: "Generate and maintain OpenAPI 3.1 specifications from code, design-first specs, and validation patterns. Use when creating API documentation, generating SDKs, or ensuring API contract compliance."
risk: safe
source: community
date_added: "2026-02-27"
---

# OpenAPI Spec Generation

Comprehensive patterns for creating, maintaining, and validating OpenAPI 3.1 specifications for RESTful APIs.

## Use this skill when

- Creating API documentation from scratch
- Generating OpenAPI specs from existing code
- Designing API contracts (design-first approach)
- Validating API implementations against specs
- Generating client SDKs from specs
- Setting up API documentation portals

## Do not use this skill when

- The task is unrelated to openapi spec generation
- You need a different domain or tool outside this scope

## Instructions

- Clarify goals, constraints, and required inputs.
- Apply relevant best practices and validate outcomes.
- Provide actionable steps and verification.
- If detailed examples are required, open `resources/implementation-playbook.md`.

## Resources

- `resources/implementation-playbook.md` for detailed patterns and examples.

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: openapi-spec-generator
description: Generate complete, production-ready OpenAPI 3.x and Swagger 2.0 specifications from natural language descriptions, code, or partial specs. Use this skill whenever the user mentions OpenAPI, Swagger, API spec, REST API documentation, YAML/JSON API schema, endpoint documentation, API...
risk: critical
source: https://github.com/LambdaTest/agent-skills/tree/main/api-skill/openapi-spec-generator
source_repo: LambdaTest/agent-skills
source_type: community
date_added: 2026-07-01
license: MIT
license_source: https://github.com/LambdaTest/agent-skills/blob/main/LICENSE
---

# OpenAPI / Swagger Specification Generator
## When to Use

Use this skill when you need generate complete, production-ready OpenAPI 3.x and Swagger 2.0 specifications from natural language descriptions, code, or partial specs. Use this skill whenever the user mentions OpenAPI, Swagger, API spec, REST API documentation, YAML/JSON API schema, endpoint documentation, API...

Generate complete, valid OpenAPI 3.x or Swagger 2.0 specifications from descriptions, code, or partial specs.

## Workflow

### Step 1 — Gather Context

Before writing any YAML/JSON, ask (or infer from context) the following:

| Question | Why it matters |
|---|---|
| OpenAPI 3.x or Swagger 2.0? | Different `info`, `servers`/`host`, `components`/`definitions` structure |
| Output format: YAML or JSON? | YAML default unless user specifies JSON |
| What does this API do? | Sets `info.title`, `info.description`, tags |
| List of endpoints (or code to extract from)? | Core paths object |
| Authentication type(s)? | `securitySchemes` — see reference |
| Common data models or entities? | `components/schemas` / `definitions` |
| Any existing partial spec to extend? | Merge rather than overwrite |

If the user provides code (Express routes, FastAPI, Django URLs, Spring controllers, etc.), **extract endpoints automatically** — do not ask what the user already told you.

### Step 2 — Build the Spec

Follow the structure guide for the chosen version. Always produce a **complete, valid spec** — never leave placeholder comments like `# TODO: add schema`.

#### OpenAPI 3.x Skeleton

```yaml
openapi: "3.1.0"
info:
  title: <API Title>
  version: "1.0.0"
  description: <Short description>
  contact:
    name: <Team or Author>
    email: <contact@example.com>
servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging-api.example.com/v1
    description: Staging
tags:
  - name: <Tag>
    description: <Tag description>
paths:
  /resource:
    get:
      summary: List resources
      operationId: listResources
      tags: [<Tag>]
      parameters: []
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceList"
              example:
                items: []
                total: 0
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      security:
        - BearerAuth: []
components:
  schemas: {}
  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  securitySchemes: {}
```

#### Swagger 2.0 Skeleton

```yaml
swagger: "2.0"
info:
  title: <API Title>
  version: "1.0.0"
  description: <Short description>
host: api.example.com
basePath: /v1
schemes: [https]
consumes: [application/json]
produces: [application/json]
tags: []
paths: {}
definitions: {}
securityDefinitions: {}
```

### Step 3 — Schemas and Models

- **Always use `$ref`** for any schema used in more than one place.
- Include `example` or `examples` on every schema and response body.
- Mark required fields with the `required` array.
- Use `nullable: true` (OAS 3.0) or `x-nullable: true` (Swagger 2.0) for optional nullable fields.
- Prefer `format` keywords: `int32`, `int64`, `float`, `date`, `date-time`, `uuid`, `email`, `uri`, `byte`, `binary`.

**Common schema patterns:**

```yaml
# Pagination wrapper
PagedResult:
  type: object
  required: [items, total, page, pageSize]
  properties:
    items:
      type: array
      items:
        $ref: "#/components/schemas/Resource"
    total:
      type: integer
      format: int64
      example: 100
    page:
      type: integer
      format: int32
      example: 1
    pageSize:
      type: integer
      format: int32
      example: 20

# Standard error
Error:
  type: object
  required: [code, message]
  properties:
    code:
      type: string
      example: RESOURCE_NOT_FOUND
    message:
      type: string
      example: The requested resource was not found.
    details:
      type: object
      additionalProperties: true

# Timestamps mixin (use allOf)
Timestamps:
  type: object
  properties:
    createdAt:
      type: string
      format: date-time
    updatedAt:
      type: string
      format: date-time
```

### Step 4 — Security Schemes

Read `reference/security-schemes.md` for detailed patterns. Quick reference:

| Scheme | OAS 3.x type | Notes |
|---|---|---|
| Bearer JWT | `http`, scheme `bearer` | Most common for REST APIs |
| API Key (header) | `apiKey`, in `header` | e.g. `X-API-Key` |
| API Key (query) | `apiKey`, in `query` | Avoid — leaks in logs |
| OAuth 2 | `oauth2` | Use `flows` to define grant types |
| Basic Auth | `http`, scheme `basic` | Only over HTTPS |
| OpenID Connect | `openIdConnect` | Provide `openIdConnectUrl` |

Apply security **globally** at the root and **override per-operation** only where it differs (e.g., public endpoints use `security: []`).

### Step 5 — Parameters

**Path parameters** — always `required: true`:
```yaml
parameters:
  - name: userId
    in: path
    required: true
    schema:
      type: string
      format: uuid
    example: 123e4567-e89b-12d3-a456-426614174000
```

**Query parameters** — document defaults and enums:
```yaml
  - name: status
    in: query
    schema:
      type: string
      enum: [active, inactive, pending]
      default: active
```

**Headers** — include `X-Request-ID`, correlation IDs, etc. as common parameters defined under `components/parameters`.

### Step 6 — Response Codes

Always include at minimum:

| Code | When |
|---|---|
| `200` | Successful GET, PUT, PATCH |
| `201` | Successful POST that creates a resource |
| `204` | Successful DELETE (no body) |
| `400` | Validation / bad request |
| `401` | Missing or invalid auth |
| `403` | Authenticated but not authorized |
| `404` | Resource not found |
| `409` | Conflict (duplicate, state mismatch) |
| `422` | Unprocessable entity (semantic errors) |
| `429` | Rate limited |
| `500` | Internal server error |

Use `$ref` to `components/responses` for `401`, `403`, `404`, `429`, `500` to avoid repetition.

### Step 7 — Quality Checklist

Before delivering the spec, verify:

- [ ] `openapi` or `swagger` version field present
- [ ] Every path has at least one operation
- [ ] Every operation has `operationId` (camelCase, unique)
- [ ] Every operation has at least one `200`/`201`/`204` response
- [ ] `4xx` and `5xx` responses defined for all operations
- [ ] All `$ref` targets exist in `components/` or `definitions/`
- [ ] Required fields listed in `required` array for all request/response bodies
- [ ] Security schemes defined AND applied
- [ ] At least one `example` per schema or response body
- [ ] Tags defined at root level to match operation tags
- [ ] No orphaned schemas (everything in `components/schemas` is referenced)

### Step 8 — Output

1. Emit the complete YAML (or JSON) spec in a code block labeled `yaml` or `json`.
2. After the spec, provide a brief **summary table** of endpoints generated.
3. Offer to:
   - Export as `.yaml` / `.json` file
   - Validate against Spectral or swagger-parser
   - Generate mock server config (Prism)
   - Generate client SDK stubs (language of choice)

---

## Extracting from Code

When the user provides source code, extract:

**Express / Koa / Fastify (Node.js)**
- Look for `.get()`, `.post()`, `.put()`, `.patch()`, `.delete()` calls
- Route params `:param` → path parameter `{param}`
- Middleware like `authenticate` → note security requirement
- `req.body`, `req.query`, `req.params` usage → infer request schema

**FastAPI / Flask (Python)**
- Decorators: `@app.get()`, `@router.post()`, etc.
- Pydantic models → translate directly to JSON Schema
- `Query()`, `Path()`, `Body()` → map to parameter location

**Spring Boot (Java)**
- `@GetMapping`, `@PostMapping`, etc.
- `@PathVariable`, `@RequestParam`, `@RequestBody`
- DTO classes → schemas

**Django REST Framework**
- `ViewSet` and `Router` → CRUD endpoints
- `Serializer` fields → schema properties

**Rails**
- `routes.rb` resource routes → standard REST endpoints
- Strong params → request body schema

---

## Reference Files

- `reference/security-schemes.md` — Detailed security scheme examples for all auth types
- `reference/common-patterns.md` — Pagination, HATEOAS, problem+json, webhooks, file upload patterns

Read these when the user asks about a specific pattern or when generating complex auth/pagination setups.

---

## After Completing the OpenAPI/Swagger Specification design

Once the OpenAPI/Swagger Specification output is delivered, ask the user:

"Would you like me to generate API test cases for this design? (yes/no)"

If the user says **yes**:
- Check if the API Test Case Generator skill is available in the installed skills list
- If the skill **is available**:
  - Read and follow the instructions in the API Test Case Generator skill
  - Use the specification output above as the input
- If the skill **is NOT available**:
  - Inform the user: "It looks like the API Documentation skill isn't installed.
    You can install it and re-run.

If the user says **no**:
- End the task here

---

## Limitations

- Use this skill only when the task clearly matches its upstream source and local project context.
- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.


---
name: openclaw-github-repo-commander
description: "7-stage super workflow for GitHub repo audit, cleanup, PR review, and competitor analysis"
category: development-and-testing
risk: safe
source: community
date_added: "2026-03-18"
author: wd041216-bit
tags: [github, git, repository, audit, cleanup, workflow, devtools, automation, code-review, security]
tools: [claude, cursor]
---
# OpenClaw GitHub Repo Commander

## Overview

A structured 7-stage super workflow for comprehensive GitHub repository management. This skill automates repository auditing, cleanup, competitor benchmarking, and optimization — turning a messy repo into a clean, well-documented, production-ready project.

## When to Use This Skill

- Use when you need to audit a repository for secrets, junk files, or low-quality content
- Use when the user says "clean up my repo", "optimize my GitHub project", or "audit this library"
- Use when reviewing or creating pull requests with structured analysis
- Use when comparing your project against competitors on GitHub
- Use when running `/super-workflow` or `/openclaw-github-repo-commander` on a repo URL

## How It Works

### Stage 1: Intake
Clone the target repository, define success criteria, and establish baseline metrics.

### Stage 2: Execution
Run `scripts/repo-audit.sh <repo-path>` from this skill directory — automated read-only checks for:
- Hardcoded secrets (`ghp_`, `sk-`, `AKIA`, etc.)
- Tracked `node_modules/` or build artifacts
- Empty directories
- Large files (>1MB)
- Missing `.gitignore` coverage
- Broken internal README links

### Stage 3: Reflection
Deep manual review beyond automation: content quality, documentation consistency, structural issues, version mismatches.

### Stage 4: Competitor Analysis
Search GitHub for similar repositories. Compare documentation standards, feature coverage, star counts, and community adoption.

### Stage 5: Synthesis
Consolidate all findings into a prioritized action plan (P0 critical / P1 important / P2 nice-to-have).

### Stage 6: Iteration
Execute the plan: delete low-value files, fix security issues, upgrade documentation, add CI workflows, update changelogs.

### Stage 7: Validation
Re-run the audit script (target: 7/7 PASS), verify all changes, push to GitHub, and deliver a full report.

## Examples

### Example 1: Full Repo Audit

```
/openclaw-github-repo-commander https://github.com/owner/my-repo
```

Runs all 7 stages and produces a detailed before/after report.

### Example 2: Quick Cleanup

```
Clean up my GitHub repo — remove junk files, fix secrets, add .gitignore
```

### Example 3: Competitor Benchmarking

```
Compare my skill repo with the top 5 similar repos on GitHub
```

## Best Practices

- ✅ Always run Stage 7 validation before pushing
- ✅ Use semantic commit messages: `chore:`, `fix:`, `docs:`
- ✅ Check the `pr_todo.json` file for pending reviewer requests
- ❌ Don't skip Stage 4 — competitor analysis reveals blind spots
- ❌ Don't commit `node_modules/` or `.env` files

## Security & Safety Notes

- The audit script scans for common secret patterns but excludes `.github/workflows/` to avoid false positives
- The bundled script is read-only: it reports findings and never deletes, rewrites, stages, commits, or pushes files
- All `gh` CLI operations use the user's existing authentication — no credentials are stored by this skill
- The skill never modifies files without explicit user confirmation in Stage 6

## Source Attribution

Originally contributed by [@wd041216-bit](https://github.com/wd041216-bit) in [PR #340](https://github.com/sickn33/agentic-awesome-skills/pull/340). No standalone upstream repository is currently available for this skill.

**License**: MIT | **Version**: 4.0.0

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: opencode-delegate
description: Delegate coding tasks to the OpenCode CLI only when the user explicitly
  requests it, while the orchestrator retains review and landing responsibility.
risk: safe
category: agent-orchestration
source: https://github.com/amElnagdy/delegate-skills
source_repo: amElnagdy/delegate-skills
source_type: community
date_added: '2026-08-26'
license: MIT
license_source: https://github.com/amElnagdy/delegate-skills/blob/master/LICENSE
compatibility: Requires the `opencode` CLI installed and authenticated, Node 18+,
  and git. The orchestrating agent must be able to run shell commands and read files.
  Shell examples assume bash/zsh (macOS/Linux, or Git Bash/WSL on Windows).
metadata:
  version: 0.5.0
---
# OpenCode Delegate

## When to Use

- You want to delegate a bounded coding task to a separate `opencode` implementer (`OpenCode`) and then review its diff yourself.
- The user explicitly asked for delegation to this implementer.

You are the **orchestrator**. This skill lets you hand a bounded coding task to a separate
**implementer** — the OpenCode CLI — then review what it produced and land it yourself. You write
the brief and own the judgment; OpenCode does the typing in its own session; you verify and commit.

Nothing here is specific to one orchestrating agent. The loop needs only the ability to run a shell
command and read a file, so any agent with those two capabilities — Claude Code, OpenCode driving a
sibling session, or a comparable one — can drive it. (It is designed for and run on Claude Code; treat
other orchestrators as designed-for, not yet proven.)

## When NOT to use this

- The task is small enough to just do inline — delegation overhead is not worth it.
- The `opencode` CLI is not installed or not authenticated (run `opencode auth login`).
- You want to write the code yourself, or you only need a review (use the `plan` agent via `--read-only`).

## Prerequisites (check once)

1. `opencode --version` succeeds. If not, install (`npm i -g opencode-ai`, or the native installer from
   opencode.ai) and `opencode auth login`.
2. **Confirm which `opencode` is on PATH.** `command -v opencode` shows the active binary and
   `opencode --version` its version. The relay records the version it ran into `result.json`, so a stale
   binary is visible after the fact.
3. A model provider is authenticated — `opencode auth list` shows at least one credential.
4. You are in (or will point `--cd` at) the target git repository.

## Choose the implementer model

OpenCode has **no safe default** — a bare `opencode run` errors — so a fresh run needs a model via
`--model` or a fleet `--lane` that sets one (a resumed run inherits its session's model). Naming the
model is the one decision a single-model backend like codex-delegate never had, and it has two owners:

- **The human owns which models are allowed.** `opencode models` lists hundreds of entries, most billed
  per token (OpenRouter and the like); only the human knows which are their flat-rate subscriptions, and
  the CLI can't tell them apart. So the usable set is theirs — ideally stated once in the repo's
  `AGENTS.md` or their `CLAUDE.md` (e.g. "delegate mechanical work to `opencode-go/…`, hard logic to
  `…`").
- **You, the orchestrator, pick per task — from that set.** Match the model to the brief: a cheap, fast
  model for a mechanical sweep (rename, migration, removal); a strong one for a subtle bug or a
  money/security path.
- **If no usable set is stated, ask — don't guess.** Guessing from the catalog risks a metered model and
  a surprise bill. Name the constraint to the human and let them choose.

More depth: [references/writing-the-brief.md](references/writing-the-brief.md).

## The loop

Run these five steps per task. Steps 1, 4, and 5 are your judgment; 2 and 3 are mechanical.

### 1. Write the brief

OpenCode sees **only** the text you send plus what it can read from the working tree — no chat history,
no shared context. Everything the task needs goes in the brief: the goal, the current state, what to
change, what to leave untouched, the project's **actual** gate commands (discover them from the repo's
AGENTS.md/CLAUDE.md/Makefile — do not assume), and a report contract. Tell OpenCode it will **not**
commit (you will). Keep one task per brief. Full guidance and a template:
[references/writing-the-brief.md](references/writing-the-brief.md).

### 2. Dispatch

Send the brief to OpenCode with the bundled helper. It wraps `opencode run`, captures the run, and
writes a structured `result.json` — so your only job is "run a command, read a file." (`<skill-dir>`
below is this skill's installed directory — the folder containing this `SKILL.md`. Claude Code prints
it as "Base directory for this skill" when the skill loads; on other orchestrators use that same
directory — if unsure where it landed, run `find ~ -name relay.mjs -path '*opencode-delegate*'` and
substitute the directory above it.)

```bash
node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --model <provider/model> --cd /path/to/repo
# --model (or a --lane that sets model) is required on a fresh run
# fleet lane from delegate-setup:           add --lane <name>  (dials apply; flags still win)
# read-only (review/diagnosis, no edits):   add --read-only   (uses the plan agent)
# continue the previous OpenCode session:   add --resume-last  (delta brief only; keeps the model)
# hard time limit (watchdog):               add --timeout 2h  (default: off; implementation runs routinely need 1-2h)
# see all options:                          node .../relay.mjs --help
```

The helper defaults to the write-capable `build` agent and writes its artifacts to a temp dir, so the
repo under review stays clean. It **never commits** — see step 5. Mechanics, flags, and the
`result.json` shape: [references/dispatch-and-poll.md](references/dispatch-and-poll.md).

### 3. Wait for completion

The helper blocks until OpenCode finishes, so back it with whatever your orchestrator offers and resume
when it returns:

- **Claude Code:** run the Bash call with `run_in_background: true`; you are notified on completion.
- **Plain shell / other agents:** run it in the foreground for short tasks, or background it and poll
  the result file — `… &` in bash/zsh (including Git Bash/WSL), or your shell's equivalent (`Start-Job`
  in PowerShell, `start /b` in cmd). The run is done when `result.json` exists with a `status`. (A
  pre-run usage error — bad args or an empty brief — instead exits with code 2 and writes no result
  file, so check the exit code too. A missing `opencode` binary exits 127 but *does* write a
  `result.json` with status `opencode_unavailable`.)

Do not trust progress trackers over reality: a run is finished when `result.json` is written and the
process has exited. Read the working tree, not a status line. The implementer's full report is
the `finalMessage` field in `result.json` (also printed in full on stdout between the report markers).

### 4. Review — do not trust the self-report

OpenCode's `result.json` includes its own final message and any gate claims. **Re-verify, don't accept:**

- **Re-run the project's gates yourself** (the test/lint/build commands from step 1). Never take
  "gates passed" on faith.
- **Read the diff** against the brief: did OpenCode do what was asked, nothing more (scope creep) and
  nothing less? `touchedFiles` in the result is your starting point.
- **Run the relevant guard skills** on the diff if you have them installed (clean-code-guard,
  test-guard, etc. from `guard-skills`) — this skill produces the work; those skills judge it.
- For schema/migration changes, round-trip them; for removals, grep for dangling references.

Full checklist: [references/review-and-land.md](references/review-and-land.md).

### 5. Land it

The implementer edits the working tree; **the orchestrator commits.** Committing should be the act of
the party that verified the work. Only after the gates pass and the diff holds:

- Commit the verified work yourself, with a clear message.
- If it needs changes, send a delta brief with `--resume-last` (don't restate the whole task) and
  review again.

## Autonomy model

OpenCode's autonomy is governed by the **agent**, not a sandbox enum:

- **`build`** (the relay default) — write-capable; edits files in the working dir headlessly. The
  equivalent of "let it implement."
- **`plan`** (via `--read-only`) — read-only; reviews and diagnoses without touching the tree. The
  equivalent of "let it look but not edit."

Permissions **auto-approve by default**: the relay passes `--auto` so a headless run never blocks on a
prompt no one can answer. That is the point of unattended delegation — the orchestrator's diff review
and the implementer sweep (step 4) are the safety net, not a per-action prompt. Pass `--no-auto` to
honor the agent's own permission config instead (allow/ask/deny per action); pair it with an agent whose
in-workspace permissions are set to *allow*, or a headless run can hang waiting on an `ask`.
**Read-only (`plan`) runs never get `--auto`** — auto-approving would let the plan agent's ask-gated
edit/bash permissions through and defeat "read-only," so a review can't be tricked into touching the tree.

## Authorization model

Delegation is something the human opts into. Once they have ("run this queue", "proceed"), committing
verified, gate-passing work is the agreed contract — that is the whole point. Two limits on that
mandate: **surface, don't absorb** (report OpenCode's design decisions, defensible-but-unasked turns,
and non-blocking nitpicks rather than silently keeping them) and **stop for scope changes** (if correct
completion needs going beyond the brief, ask — don't expand the mandate yourself). The full treatment
is in [references/review-and-land.md](references/review-and-land.md).

## References

- [references/writing-the-brief.md](references/writing-the-brief.md) — how to write a brief OpenCode can
  execute blind: structure, XML blocks, the report contract, embedding the real gate commands.
- [references/dispatch-and-poll.md](references/dispatch-and-poll.md) — `relay.mjs` flags, the
  `result.json` contract, backgrounding per orchestrator, and recovery when a run misbehaves.
- [references/review-and-land.md](references/review-and-land.md) — the review checklist, the commit
  boundary, and the rework cycle via `--resume-last`.
- [references/multi-task-queues.md](references/multi-task-queues.md) — running a sequential queue:
  carrying constraints forward, progress tracking, and the end-of-run coherence check.

## Limitations

- Docs-only import — executable `scripts/relay.mjs` not included; see upstream for full runtime. Requires `opencode` CLI, Node 18+, git.
- Relay never commits — it only returns structured result JSON; you review and land the commit.

> Adapted from [amElnagdy/delegate-skills](https://github.com/amElnagdy/delegate-skills) (MIT) — docs-only, runtime not bundled.


---
name: optim-agent
description: "Guide agent-driven parameter optimization for configurable systems with measurable objectives. Use for HPO, inference tuning, simulations, or RL/control experiments."
category: data
risk: safe
source: community
source_repo: Optim-Agent/optim-agent
source_type: community
date_added: "2026-07-15"
author: Optim-Agent
tags: [optimization, hyperparameter-optimization, experiments, tuning]
tools: [claude, cursor, gemini, codex]
license: MIT
license_source: "https://github.com/Optim-Agent/optim-agent/blob/main/LICENSE"
---

# Optim Agent

## Overview

Use this skill to optimize configurable systems against a measurable scalar objective. It helps an agent turn vague tuning requests into bounded experiments with a defined search space, budget, baseline, and evidence-backed recommendation.

## When to Use This Skill

- Use when tuning hyperparameters, prompts, inference settings, simulation parameters, quantitative strategies, or RL/control policies.
- Use when the objective can be measured as a scalar score, loss, accuracy, cost, latency, reward, or risk-adjusted metric.
- Use when the user needs a small-budget optimization loop with trial history, comparisons, and stop criteria.

## Do not use this skill when

- The objective is purely subjective and cannot be scored consistently.
- The user has not provided permission to run experiments or consume compute/API budget.
- The task is a one-shot implementation, debugging, or code review request with no configurable search space.

## Instructions

1. Define the optimization target in one sentence: maximize or minimize one scalar metric.
2. List the tunable parameters, valid ranges, types, defaults, and any forbidden combinations.
3. Establish at least one baseline before proposing agent-guided trials.
4. Set the budget up front: number of trials, time, compute, money, or dataset subsample.
5. Run or request trials one at a time unless the user explicitly approves parallel execution.
6. Record every trial with parameters, metric value, notes, and failure status.
7. Compare the best result against the baseline and a simple search strategy when possible.
8. Stop when the budget is exhausted, the improvement plateaus, or the next trial cannot be justified from evidence.
9. Report the recommended configuration, measured gain, tradeoffs, and any validation still needed before production use.

## Examples

### Example 1: Hyperparameter optimization

Tune learning rate, regularization, and tree depth for a credit-default model. Track validation AUC for each trial, compare against the default configuration, and recommend the best setting only if it improves the baseline under the agreed trial budget.

### Example 2: Inference tuning

Tune retrieval depth, temperature, and reranker threshold for a RAG workflow. Optimize answer quality under a latency or cost ceiling, then report the best configuration with quality, latency, and cost tradeoffs.

### Example 3: Simulation or control

Tune controller gains or environment parameters for a simulator. Optimize reward or error while logging failed trials separately so unstable configurations do not bias the recommendation.

## Best Practices

- Keep the first run small; expand only after the loop produces useful signal.
- Prefer parameters with clear operational meaning over arbitrary knobs.
- Treat failed trials as data and record why they failed.
- Validate the final configuration on held-out data, a fresh seed, or a separate scenario before calling it robust.
- Ask before running expensive, long, or externally billed experiments.

## Limitations

- This skill does not guarantee a global optimum.
- Results depend on objective quality, noise, search-space design, and experiment reproducibility.
- Use domain review before applying tuned configurations to production, financial, safety-critical, or user-impacting systems.

## Additional Resources

- [Optim-Agent repository](https://github.com/Optim-Agent/optim-agent)
- [Optim-Agent documentation](https://optim-agent.github.io/optim-agent/)


---
name: options-flow-analyzer
description: Real vs lottery call separation for options P/C ratio analysis — prevents signal inversion from deep OTM noise
category: finance
risk: safe
source: community
source_type: community
date_added: "2026-05-13"
author: tellmefrankie
tags: [options, sentiment-analysis, trading, polygon, market-analysis]
tools: [websearch]
---
# Options Flow Analyzer

Analyze options chain data with real vs lottery call separation — the key insight that prevents P/C ratio misinterpretation. Uses Polygon.io API.

## When to Use

- Use when raw put/call ratios appear bullish or bearish but may be distorted by cheap deep OTM contracts.
- Use when comparing options flow across watchlists, holdings, sectors, or event-driven names.
- Use when you need to separate institutional hedging from speculative lottery-ticket activity.
- Use when tracking options anomalies against a recent baseline.

## What it does

Standard P/C ratio analysis is misleading. A P/C of 0.35 looks "extremely bullish" but may be 84% lottery calls ($0.01-$0.09 OTM options).

This skill separates:
- **Real calls**: Strike price within 5% of stock price, meaningful premium
- **Lottery calls**: Deep OTM, cheap premium, speculative bets
- **Real puts**: Actual hedging activity
- **Lottery puts**: Cheap downside bets

## Analysis Output

For each ticker:
- Real P/C ratio (excludes lottery noise)
- Lottery percentage (what % of volume is speculation)
- Per-expiry breakdown (weekly vs monthly vs LEAPS)
- Anomaly detection: P/C shifts >0.3, Call OI surges >30%, IV spikes >20%
- Sentiment classification: Bullish/Bearish/Neutral with confidence

## Example Output

```
Options Flow Summary — 2026-05-13

HOLDINGS:
CEG  $299.69 | Raw P/C: 1.06 | Lottery: 61% | Adj P/C: 2.72  BEARISH (was neutral raw)
IREN $55.15  | Raw P/C: 0.83 | Lottery: 34% | Adj P/C: 0.55  BULLISH
KTOS $56.99  | Raw P/C: 0.53 | Lottery: 28% | Adj P/C: 0.38  EXTREME BULLISH
RXRX $3.26   | Raw P/C: 0.38 | Lottery: 84% | Adj P/C: 2.37  BEARISH (was extreme bullish raw)

SECTORS:
XLI  | Raw P/C: 5.32 | Lottery:  8% | Adj P/C: 4.89  INSTITUTIONAL HEDGE

ANOMALIES:
XLI: P/C 5.32 vs 30-day baseline 0.87 — 4.5 std deviations above normal
RXRX: 84% lottery calls — raw P/C signal completely inverted after filtering
```

## Configuration

```
Analyze options flow for my watchlist:
Holdings: CEG, IREN, KTOS, RXRX, TEM
Sectors: SPY, QQQ, XLI, XLK
Separate real vs lottery calls (threshold: premium < $0.10, delta < 0.05).
Flag anomalies vs 30-day baseline.
```

## Requirements

- Polygon.io API key (free tier covers basic data; paid tier for full chain)
- WebSearch for cross-verification

## Limitations

- Options data can be delayed, incomplete, or unavailable depending on the Polygon.io plan.
- Heuristics such as premium and delta thresholds need adjustment for ticker price, volatility, and expiry.
- Sentiment classifications are analytical signals, not financial advice or trade recommendations.
- Always cross-check unusual flow against price action, news catalysts, liquidity, and risk controls.

## Key Discovery

This real/lottery separation was discovered during live portfolio management when RXRX showed P/C 0.35 (looks extremely bullish) but was actually 84% lottery calls at $0.01-$0.09. The "bullish signal" was noise. This skill prevents that mistake.

## Pricing

Free: Basic P/C ratio for 3 tickers
**Full bundle — $29 one-time**: Real/lottery separation + anomaly detection + per-expiry + unlimited tickers
→ https://jaehyunpark.gumroad.com/l/tcyahy

## Author

Built from a real trading mistake that cost money. The real/lottery discovery is documented and battle-tested across 17 tickers over 2+ months.


---
name: oral-health-analyzer
description: 分析口腔健康数据、识别口腔问题模式、评估口腔健康状况、提供个性化口腔健康建议。支持与营养、慢性病、用药等其他健康数据的关联分析。
risk: safe
source: community
---
name: oral-health-analyzer

# 口腔健康分析技能

## When to Use
- 需要分析口腔健康趋势、龋齿风险、牙周问题或卫生习惯时使用。
- 任务涉及口腔健康评分、问题模式识别或个性化口腔护理建议。
- 用户请求口腔健康报告或长期口腔记录分析时使用。

## 技能概述

本技能提供全面的口腔健康数据分析功能，包括趋势识别、风险评估、问题诊断和个性化建议生成。

## 医学免责声明

⚠ **重要提示**：本技能提供的数据分析和建议仅供参考，不构成医学诊断或治疗建议。

- 所有口腔问题应由专业牙科医生诊断和治疗
- 分析结果不能替代专业口腔检查
- 紧急情况应立即就医
- 请遵循牙科医生的专业建议

## 核心功能

### 1. 趋势分析

#### 龋齿发展趋势
- 识别龋齿发生的模式和频率
- 分析龋齿在不同牙位的分布
- 评估龋齿发展速度
- 预测未来龋齿风险

**输出内容**：
- 龋齿数量变化曲线
- 高风险牙位识别
- 发展趋势预测
- 预防建议

#### 牙周健康变化
- 牙周出血频率统计
- 牙周袋深度变化
- 附着丧失监测
- 牙龈退缩进展

**输出内容**：
- 牙周健康评分趋势
- 疾病进展预警
- 治疗效果评估
- 维护建议

#### 卫生习惯改善
- 刷牙频率变化
- 牙线使用频率变化
- 洁牙记录追踪
- 卫生习惯评分

**输出内容**：
- 习惯改善曲线
- 评分变化趋势
- 目标达成情况
- 激励建议

### 2. 风险评估

#### 龋齿风险评估
基于以下因素进行综合评估：
- 饮食习惯（糖分摄入）
- 口腔卫生习惯
- 氟化物使用
- 唾液分泌情况
- 既往龋齿史
- 家族史

**风险等级**：
- **低风险**：良好的卫生习惯+低糖饮食+定期检查
- **中风险**：中等糖摄入+一般卫生习惯
- **高风险**：高糖饮食+差卫生习惯+不定期检查+龋齿史

**输出内容**：
- 风险等级（低/中/高）
- 主要风险因素
- 量化风险评分
- 降低风险建议

#### 牙周病风险评估
基于以下因素进行综合评估：
- 牙龈出血频率
- 牙周袋深度
- 附着丧失程度
- 吸烟状况
- 糖尿病控制情况
- 压力水平
- 家族史

**风险等级**：
- **健康**：无出血，探诊深度1-3mm
- **牙龈炎**：探诊出血，探诊深度3-4mm
- **轻度牙周炎**：探诊深度4-5mm，轻度附着丧失
- **中度牙周炎**：探诊深度5-6mm，中度附着丧失
- **重度牙周炎**：探诊深度>6mm，重度附着丧失

**输出内容**：
- 疾病分期
- 风险因素列表
- 进展风险预测
- 管理建议

#### 口腔癌风险评估
基于以下因素进行综合评估：
- 吸烟史
- 饮酒习惯
- 槟榔咀嚼
- HPV感染
- 日晒暴露（唇癌）
- 营养状况
- 口腔卫生

**风险等级**：
- **低风险**：无危险因素
- **中风险**：1-2个危险因素
- **高风险**：3个以上危险因素或既往病变

**输出内容**：
- 风险等级
- 主要危险因素
- 筛查建议
- 预防策略

### 3. 关联分析

#### 与营养模块的关联
**糖分摄入与龋齿风险**：
- 分析每日糖分摄入量
- 评估进食频率对龋齿的影响
- 识别高糖食物类型
- 推荐低糖替代食物

**钙和维生素D与牙齿健康**：
- 评估钙摄入量是否充足
- 分析维生素D水平
- 评估对牙齿强度的影响
- 推荐补充剂（如需要）

**营养缺乏的口腔表现**：
- 维生素C缺乏：牙龈出血
- 维生素B缺乏：口腔溃疡
- 铁缺乏：舌头炎症
- 蛋白质缺乏：黏膜萎缩

#### 与慢性病模块的关联
**糖尿病与牙周病**：
- 分析血糖控制与牙周健康的关系
- 评估糖尿病并发症风险
- 提供牙周病对血糖影响的说明
- 联合管理建议

**心血管疾病与牙周病**：
- 分析牙周炎对心血管疾病的影响
- 评估炎症指标关联
- 提供预防性治疗建议
- 联合监测建议

**妊娠期口腔健康**：
- 妊娠期牙龈炎风险评估
- 牙齿治疗时机建议
- 药物使用安全性评估
- 孕期口腔护理指导

**骨质疏松与牙齿健康**：
- 评估骨密度对牙齿的影响
- 分析抗骨吸收药物的副作用
- 提供牙齿保护建议

#### 与用药模块的关联
**药物引起的口干**：
- 识别导致口干的药物
- 评估口干严重程度
- 提供缓解建议
- 与医生沟通用药调整

**药物引起的牙龈增生**：
- 识别导致牙龈增生的药物
- 评估增生程度
- 提供管理建议
- 与医生沟通替代用药

**药物对牙齿颜色的影响**：
- 识别导致牙齿变色的药物
- 提供美容解决方案
- 预防措施建议

#### 与眼健康模块的关联
**干燥综合征**：
- 口干与眼干的联合分析
- 评估全身性自身免疫病
- 多系统症状追踪
- 专科转诊建议

**自身免疫病的口腔表现**：
- 狼疮的口腔病变
- 类风湿关节炎的颞下颌关节影响
- 其他免疫病的口腔表现

### 4. 个性化建议

#### 预防建议
**龋齿预防**：
- 刷牙技巧指导（巴氏刷牙法）
- 牙线使用方法
- 含氟产品推荐
- 饮食调整建议
- 定期检查提醒

**牙周病预防**：
- 改善口腔卫生习惯
- 戒烟支持
- 压力管理
- 血糖控制（糖尿病患者）
- 定期洁牙建议

**口腔癌预防**：
- 戒烟限酒
- 避免槟榔
- 防晒（唇部）
- 营养均衡
- 定期自查方法

#### 治疗建议
**根据问题类型提供**：
- 常规检查建议（每6个月）
- 紧急情况处理指导
- 专科转诊建议（如需要）
- 治疗时机建议
- 费用预估参考

#### 生活方式建议
**饮食调整**：
- 减少游离糖摄入
- 增加钙和维生素D摄入
- 多喝水（预防口干）
- 避免过硬食物（保护牙冠）

**习惯改善**：
- 制定个性化刷牙计划
- 逐步增加牙线使用频率
- 建立口腔卫生常规
- 设置提醒系统

**风险因素管理**：
- 戒烟策略
- 限酒建议
- 压力管理技巧
- 夜磨牙管理

### 5. 目标管理

#### 目标设定
- 与用户协商设定现实目标
- 分解为可实现的步骤
- 设定时间节点
- 建立评估标准

**常见目标类型**：
- 提高牙线使用频率
- 改善刷牙技巧
- 减少糖分摄入
- 定期口腔检查
- 戒烟

#### 进度追踪
- 定期评估目标达成情况
- 提供激励和反馈
- 调整目标（如需要）
- 庆祝里程碑达成

#### 障碍识别
- 识别阻碍目标达成的因素
- 提供克服障碍的策略
- 调整计划以适应实际情况
- 提供持续支持

### 6. 统计分析

#### 综合健康评分
基于以下因素计算：
- 口腔卫生习惯（40%）
- 检查频率（20%）
- 治疗完成情况（20%）
- 问题控制情况（10%）
- 目标达成情况（10%）

**评分范围**：0-100分
- **优秀**：90-100分
- **良好**：75-89分
- **一般**：60-74分
- **较差**：<60分

#### 口腔健康年龄
- 基于牙齿状态、牙周健康、卫生习惯计算
- 与实际年龄对比
- 提供改善建议

#### 治疗统计
- 治疗类型分布
- 治疗费用统计
- 治疗频率分析
- 牙医就诊记录

#### 问题统计
- 问题类型分布
- 问题发生频率
- 问题持续时间
- 解决率统计

### 7. 预警系统

#### 定期检查提醒
- 距离下次检查30天：温馨提醒
- 距离下次检查7天：紧急提醒
- 超过检查时间：逾期提醒

#### 问题预警
- 牙痛超过3天：建议就医
- 牙龈出血持续1周：建议检查
- 口腔溃疡超过2周：建议活检
- 新增肿块/白斑：立即就医

#### 趋势预警
- 龋齿数量快速增加：风险升级
- 牙周指标恶化：转诊牙周专科
- 卫生习惯下降：干预建议
- 治疗频率增加：深度评估

## 使用场景

### 场景1：定期健康评估
**用户请求**：分析最近6个月的口腔健康状况

**分析流程**：
1. 读取最近6个月的所有口腔健康记录
2. 分析检查记录、治疗记录、问题记录
3. 评估卫生习惯变化
4. 计算健康评分变化
5. 识别改善或恶化的趋势
6. 生成综合评估报告

**输出内容**：
- 健康评分变化趋势
- 主要改善点
- 需要关注的问题
- 下一步行动建议

### 场景2：问题诊断辅助
**用户请求**：我最近刷牙时牙龈出血，持续1周了

**分析流程**：
1. 检索最近的口腔检查记录
2. 分析牙周状况历史
3. 评估当前卫生习惯
4. 检查是否有相关用药记录
5. 分析营养数据（如维生素C摄入）
6. 生成诊断辅助报告

**输出内容**：
- 可能的原因分析
- 严重程度评估
- 就医建议
- 家庭护理方法
- 预防措施

### 场景3：治疗规划
**用户请求**：我想改善口腔卫生，降低龋齿风险

**分析流程**：
1. 评估当前龋齿风险
2. 分析主要风险因素
3. 评估当前卫生习惯
4. 识别需要改善的领域
5. 设定阶段性目标
6. 制定个性化计划

**输出内容**：
- 当前风险评估
- 改善目标
- 行动计划
- 时间表
- 进度追踪方法

### 场景4：多学科联合分析
**用户请求**：我有糖尿病，这对我的口腔健康有什么影响？

**分析流程**：
1. 读取糖尿病管理数据
2. 分析血糖控制情况
3. 评估牙周健康状况
4. 分析两者关联性
5. 评估并发症风险
6. 生成联合管理建议

**输出内容**：
- 糖尿病对口腔的影响
- 口腔健康对血糖的影响
- 并发症风险评估
- 联合管理策略
- 监测指标建议

### 场景5：预防性指导
**用户请求**：我准备怀孕，应该注意哪些口腔问题？

**分析流程**：
1. 评估当前口腔健康状况
2. 识别潜在风险
3. 分析当前用药安全性
4. 评估治疗紧迫性
5. 生成孕期口腔管理计划

**输出内容**：
- 孕前口腔检查建议
- 孕期常见口腔问题
- 药物使用安全性
- 治疗时机建议
- 孕期护理指导

## 数据分析方法

### 定量分析
- 统计描述（均值、中位数、标准差）
- 趋势分析（线性回归、移动平均）
- 相关性分析（Pearson/Spearman相关）
- 风险评分计算（多因素加权）

### 定性分析
- 文本描述分析
- 症状模式识别
- 主诉内容分类
- 满意度评估

### 可视化输出
- 时间序列图表
- 牙位分布图
- 风险评估雷达图
- 进度追踪仪表板
- 对比分析柱状图

## 质量保证

### 数据验证
- 检查数据完整性
- 验证数据一致性
- 识别异常值
- 处理缺失数据

### 结果验证
- 医学逻辑检查
- 与临床指南对照
- 专家审查（如有）
- 用户反馈收集

### 持续改进
- 定期更新分析算法
- 引入新的科学证据
- 优化用户体验
- 扩展功能范围

## 参考资源

### 临床指南
- 美国牙科协会（ADA）指南
- 世界卫生组织（WHO）口腔健康指南
- 中华口腔医学会临床指南
- Cochrane口腔健康组系统评价

### 评估工具
- DMFT指数（龋失补指数）
- CPI指数（社区牙周指数）
- 口腔健康影响.profile（OHIP-14）
- 龋齿风险评估工具（CAT）

### 数据源
- 用户记录数据
- 营养模块数据
- 慢性病模块数据
- 用药模块数据
- 眼健康模块数据

## 局限性

### 系统局限
- 不能替代专业口腔检查
- 不能进行影像学检查
- 不能进行实验室检测
- 分析结果受数据质量影响

### 数据局限
- 依赖用户记录准确性
- 可能存在遗漏记录
- 主观评估存在偏差
- 时间跨度可能不足

### 建议局限
- 不能考虑所有个体因素
- 不能预测所有并发症
- 需要结合临床判断
- 不能保证100%准确性

## 未来扩展

### 计划功能
- AI影像识别（牙片分析）
- 语音记录录入
- 智能提醒系统
- 社区支持功能
- 与牙医系统对接

### 研究方向
- 机器学习预测模型
- 个性化预防策略
- 基因风险分析
- 微生物组分析

---
name: oral-health-analyzer

**版本**: v1.0.0
**最后更新**: 2025-01-06
**维护者**: WellAlly Tech

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: orchestrate
description: "Coordinate focused subagents on substantial work, keep their ownership non-overlapping, and integrate verified results. Use for large-scope Codex tasks; keep trivial work with the coordinator."
category: agent-orchestration
risk: safe
source: https://github.com/provencher/codex-skills/tree/8aa6c42b73781c905c55f8a1253a18127079ac21/orchestrate
source_repo: provencher/codex-skills
source_type: community
date_added: "2026-07-26"
author: provencher
tags: [codex, orchestration, multi-agent, delegation, subagents]
tools: [codex]
license: MIT
license_source: https://github.com/provencher/codex-skills/blob/8aa6c42b73781c905c55f8a1253a18127079ac21/LICENSE
---

# Orchestrate

Coordinate substantial work across focused subagents while remaining available
to the user and retaining responsibility for the integrated result.

## When to Use

- Use when a task has multiple independent research, review, or implementation lanes.
- Use when parallel work will materially reduce elapsed time or improve coverage.
- Use when a coordinator must synthesize several bounded outputs into one verified result.

Keep trivial tasks with the coordinator.

## Workflow

1. Decompose the task into distinct, bounded assignments with explicit outputs.
2. Run narrow, read-only scouts in parallel with low reasoning effort and no
   inherited conversation when the runtime supports those controls. Give each
   scout all scoped context and evidence required to complete its assignment.
3. Use medium reasoning effort for routine implementation and high reasoning
   effort for difficult work.
4. Give each subagent distinct ownership. Prevent overlapping assignments, and
   instruct leaf workers not to delegate.
5. Integrate the outputs, resolve conflicts, and verify the combined result.
6. Keep approvals and externally consequential decisions with the user.

## Examples

- For a repository-wide feature, assign non-overlapping agents to architecture
  inspection, implementation, and test review, then integrate their findings
  and run the final verification from the coordinator.
- For a research brief, assign independent sources or questions to read-only
  scouts, reconcile disagreements, and keep the final judgment with the
  coordinator.

## Limitations

- Requires a runtime that exposes subagent or delegation tools; otherwise keep
  the work with the coordinator.
- Delegation does not authorize file mutations, public actions, purchases, or
  other consequential operations beyond the user's original scope.
- Parallel agents can add cost and coordination overhead, so use them only when
  the task is substantial enough to benefit.
- The coordinator remains responsible for checking claims, changes, tests, and
  the final answer.