---
name: instagram
description: Integracao completa com Instagram via Graph API. Publicacao, analytics, comentarios, DMs, hashtags, agendamento, templates e gestao de contas Business/Creator.
risk: critical
source: community
date_added: '2026-03-06'
author: renat
tags:
- social-media
- instagram
- graph-api
- content
tools:
- claude-code
- antigravity
- cursor
- gemini-cli
- codex-cli
---

# Skill: Instagram Integration

## Overview

Integracao completa com Instagram via Graph API. Publicacao, analytics, comentarios, DMs, hashtags, agendamento, templates e gestao de contas Business/Creator.

## When to Use This Skill

- When the user mentions "instagram" or related topics
- When the user mentions "ig" or related topics
- When the user mentions "post instagram" or related topics
- When the user mentions "publicar instagram" or related topics
- When the user mentions "reels instagram" or related topics
- When the user mentions "stories instagram" or related topics

## Do Not Use This Skill When

- The task is unrelated to instagram
- A simpler, more specific tool can handle the request
- The user needs general-purpose assistance without domain expertise

## How It Works

Controle completo da conta Instagram via Graph API. Publicação, comunidade, analytics,
DMs, hashtags, templates e dashboard — tudo gerido com governança (rate limits, audit log,
confirmações antes de ações públicas).

## Resumo Rápido

| Área | Scripts | O que faz |
|------|---------|-----------|
| **Setup** | `account_setup.py`, `auth.py` | Configurar conta, OAuth, token |
| **Publicação** | `publish.py`, `schedule.py` | Publicar foto/vídeo/reel/story/carrossel, agendar |
| **Comunidade** | `comments.py`, `messages.py` | Comentários, DMs, menções |
| **Analytics** | `insights.py`, `analyze.py` | Métricas, melhores horários, top posts |
| **Hashtags** | `hashtags.py` | Pesquisa e tracking |
| **Inteligência** | `templates.py`, `analyze.py` | Templates de conteúdo, tendências |
| **Infra** | `export.py`, `serve_api.py`, `run_all.py` | Exportar, dashboard, sync |
| **Leitura** | `profile.py`, `media.py` | Perfil, listar mídia |

## Localização

```
C:\Users\renat\skills\instagram\
├── SKILL.md
├── scripts/
│   ├── requirements.txt
│   │  # ── CORE ──
│   ├── config.py                     # Paths, constantes, specs de mídia
│   ├── db.py                         # SQLite: accounts, posts, comments, insights
│   ├── auth.py                       # OAuth 2.0, token storage/refresh
│   ├── api_client.py                 # Instagram Graph API wrapper + retry
│   ├── governance.py                 # Rate limits, audit log, confirmações
│   │  # ── FEATURES ──
│   ├── account_setup.py              # Detecção conta, migração, verificação
│   ├── publish.py                    # Publicar + upload local via Imgur
│   ├── schedule.py                   # Orquestrador: approved → published
│   ├── comments.py                   # Ler/responder/deletar comentários
│   ├── messages.py                   # DMs (enviar/receber/listar)
│   ├── insights.py                   # Fetch + store métricas
│   ├── hashtags.py                   # Pesquisa + tracking
│   ├── profile.py                    # Ver/atualizar perfil
│   ├── media.py                      # Listar mídia, detalhes
│   │  # ── INTELIGÊNCIA ──
│   ├── templates.py                  # Templates de caption/hashtags
│   ├── analyze.py                    # Melhores horários, top posts
│   │  # ── INFRA ──
│   ├── export.py                     # Exportar JSON/CSV/JSONL
│   ├── serve_api.py                  # FastAPI + dashboard
│   └── run_all.py                    # Sync completo
├── references/
│   ├── graph_api.md                  # Endpoints e parâmetros
│   ├── permissions.md                # Scopes OAuth por feature
│   ├── rate_limits.md                # Limites 2025
│   ├── account_types.md              # Business vs Creator
│   ├── publishing_guide.md           # Specs de mídia
│   ├── setup_walkthrough.md          # Guia Meta App
│   └── schema.md                     # ER diagram
├── static/
│   └── dashboard.html                # Dashboard Chart.js
└── data/

## Instalação (Uma Vez)

```bash
pip install -r C:\Users\renat\skills\instagram\scripts\requirements.txt
```

## Configuração Inicial

```bash

## 1. Verificar Tipo De Conta Instagram

python C:\Users\renat\skills\instagram\scripts\account_setup.py --check

## 2. Configurar Oauth (Abre Browser Para Autorização)

python C:\Users\renat\skills\instagram\scripts\auth.py --setup

## 3. Verificar Se Está Tudo Funcionando

python C:\Users\renat\skills\instagram\scripts\profile.py --view
```

Se a conta for pessoal, o script `account_setup.py --guide` dá instruções de migração
para Business ou Creator.

## Foto (Aceita Arquivo Local — Faz Upload Automático Via Imgur)

python C:\Users\renat\skills\instagram\scripts\publish.py --type photo --image caminho/foto.jpg --caption "Texto do post"

## Vídeo

python C:\Users\renat\skills\instagram\scripts\publish.py --type video --video caminho/video.mp4 --caption "Meu vídeo"

## Reel

python C:\Users\renat\skills\instagram\scripts\publish.py --type reel --video caminho/reel.mp4 --caption "Novo reel!"

## Story

python C:\Users\renat\skills\instagram\scripts\publish.py --type story --image caminho/story.jpg

## Carrossel (2-10 Imagens)

python C:\Users\renat\skills\instagram\scripts\publish.py --type carousel --images img1.jpg img2.jpg img3.jpg --caption "Carrossel"

## Criar Como Rascunho (Não Publica Imediatamente)

python C:\Users\renat\skills\instagram\scripts\publish.py --type photo --image foto.jpg --caption "Texto" --draft

## Aprovar Rascunho Para Publicação

python C:\Users\renat\skills\instagram\scripts\publish.py --approve --id 5
```

## Agendar Publicação Futura

python C:\Users\renat\skills\instagram\scripts\schedule.py --type photo --image foto.jpg --caption "Post agendado" --at "2026-03-01T10:00"

## Listar Posts Agendados

python C:\Users\renat\skills\instagram\scripts\schedule.py --list

## Processar Posts Prontos Para Publicar

python C:\Users\renat\skills\instagram\scripts\schedule.py --process

## Cancelar Agendamento

python C:\Users\renat\skills\instagram\scripts\schedule.py --cancel --id 5
```

## Listar Comentários De Um Post

python C:\Users\renat\skills\instagram\scripts\comments.py --list --media-id 12345

## Responder A Um Comentário

python C:\Users\renat\skills\instagram\scripts\comments.py --reply --comment-id 67890 --text "Obrigado!"

## Deletar Comentário

python C:\Users\renat\skills\instagram\scripts\comments.py --delete --comment-id 67890

## Ver Menções

python C:\Users\renat\skills\instagram\scripts\comments.py --mentions

## Comentários Não Respondidos

python C:\Users\renat\skills\instagram\scripts\comments.py --unreplied
```

## Enviar Dm

python C:\Users\renat\skills\instagram\scripts\messages.py --send --user-id 12345 --text "Olá!"

## Listar Conversas

python C:\Users\renat\skills\instagram\scripts\messages.py --conversations

## Ver Mensagens De Uma Conversa

python C:\Users\renat\skills\instagram\scripts\messages.py --thread --conversation-id 12345
```

## Métricas De Um Post Específico

python C:\Users\renat\skills\instagram\scripts\insights.py --media --media-id 12345

## Métricas Da Conta (Últimos 7 Dias)

python C:\Users\renat\skills\instagram\scripts\insights.py --user --period day --since 7

## Buscar E Salvar Insights De Todos Os Posts Recentes

python C:\Users\renat\skills\instagram\scripts\insights.py --fetch-all --limit 20
```

## Melhores Horários Para Postar (Baseado Nos Seus Dados)

python C:\Users\renat\skills\instagram\scripts\analyze.py --best-times

## Top Posts Por Engajamento

python C:\Users\renat\skills\instagram\scripts\analyze.py --top-posts --limit 10

## Tendências De Crescimento

python C:\Users\renat\skills\instagram\scripts\analyze.py --growth --period 30
```

## Buscar Posts Recentes Com Uma Hashtag

python C:\Users\renat\skills\instagram\scripts\hashtags.py --search "artificialintelligence" --limit 25

## Top Posts De Uma Hashtag

python C:\Users\renat\skills\instagram\scripts\hashtags.py --top "tecnologia"

## Info Da Hashtag (Contagem De Posts)

python C:\Users\renat\skills\instagram\scripts\hashtags.py --info "marketing"
```

## Criar Template

python C:\Users\renat\skills\instagram\scripts\templates.py --create --name "promo" --caption "Nova promoção: {produto}! {desconto}% OFF" --hashtags "#oferta,#desconto,#promoção"

## Listar Templates

python C:\Users\renat\skills\instagram\scripts\templates.py --list

## Usar Template Em Um Post

python C:\Users\renat\skills\instagram\scripts\publish.py --type photo --image foto.jpg --template promo --vars produto="Tênis" desconto=30
```

## Ver Perfil

python C:\Users\renat\skills\instagram\scripts\profile.py --view

## Listar Posts Recentes

python C:\Users\renat\skills\instagram\scripts\media.py --list --limit 10

## Detalhes De Um Post

python C:\Users\renat\skills\instagram\scripts\media.py --details --media-id 12345
```

## Exportar Analytics Para Csv

python C:\Users\renat\skills\instagram\scripts\export.py --type insights --format csv

## Exportar Comentários

python C:\Users\renat\skills\instagram\scripts\export.py --type comments --format json

## Exportar Tudo

python C:\Users\renat\skills\instagram\scripts\export.py --type all --format csv

## Iniciar Dashboard Web

python C:\Users\renat\skills\instagram\scripts\serve_api.py

## Acesse: Http://Localhost:8000/Dashboard

```

## Status Da Autenticação

python C:\Users\renat\skills\instagram\scripts\auth.py --status

## Sync Completo (Busca Perfil + Mídia + Insights + Comentários)

python C:\Users\renat\skills\instagram\scripts\run_all.py

## Sync Parcial

python C:\Users\renat\skills\instagram\scripts\run_all.py --only media insights
```

## Rate Limits

A skill rastreia automaticamente os rate limits da API:
- **200 requests/hora** por conta
- **25 publicações/dia** por conta
- **30 hashtags únicas/semana** por conta
- **200 DMs/hora** por conta

Quando em 90% do limite, a skill emite warnings. Se exceder, bloqueia a ação e informa
quanto tempo esperar.

## Confirmações

Ações que afetam conteúdo público requerem confirmação:
- **PUBLISH**: Publicar foto/vídeo/reel/story/carrossel
- **DELETE**: Deletar comentário
- **MESSAGE**: Enviar DM
- **ENGAGE**: Responder comentário, ocultar comentário

O script retorna os detalhes da ação e pede confirmação antes de executar.

## Audit Log

Todas as ações que modificam dados são logadas no banco SQLite (`action_log` table):
- Timestamp, ação, parâmetros, resultado, status de confirmação
- Consultar via: `python C:\Users\renat\skills\instagram\scripts\db.py`

## Token Auto-Refresh

O token OAuth (60 dias) é renovado automaticamente quando está a 7 dias de expirar.
Sem intervenção manual necessária.

## Limitações Da Api

Coisas que a Instagram Graph API **não permite**:
- Deletar posts já publicados
- Editar captions após publicar
- Aplicar filtros via API
- Postar de contas pessoais (só Business/Creator)
- DMs fora da janela de 24hrs (usuário precisa ter interagido primeiro)
- Fotos em formato diferente de JPEG (auto-conversão feita pelos scripts)

## "Quero Publicar Uma Foto"

```bash
python C:\Users\renat\skills\instagram\scripts\publish.py --type photo --image foto.jpg --caption "Texto"
```

## "Me Mostra Meus Analytics"

```bash
python C:\Users\renat\skills\instagram\scripts\run_all.py --only insights
python C:\Users\renat\skills\instagram\scripts\analyze.py --summary
```

## "Qual O Melhor Horário Para Postar?"

```bash
python C:\Users\renat\skills\instagram\scripts\analyze.py --best-times
```

## "Responde Esse Comentário"

```bash
python C:\Users\renat\skills\instagram\scripts\comments.py --reply --comment-id ID --text "Resposta"
```

## "Sincroniza Tudo"

```bash
python C:\Users\renat\skills\instagram\scripts\run_all.py
```

## "Abre O Dashboard"

```bash
python C:\Users\renat\skills\instagram\scripts\serve_api.py
```

## Referências

Consultar quando precisar de detalhes:
- `references/graph_api.md` — Endpoints, parâmetros e responses da API
- `references/publishing_guide.md` — Specs de mídia (dimensões, formatos, tamanhos)
- `references/rate_limits.md` — Rate limits detalhados e estratégias
- `references/account_types.md` — Diferenças Business vs Creator, migração
- `references/permissions.md` — Scopes OAuth necessários por feature
- `references/setup_walkthrough.md` — Guia passo-a-passo de setup do Meta App
- `references/schema.md` — Schema do banco SQLite (ER diagram, campos, índices, queries)

## Best Practices

- Provide clear, specific context about your project and requirements
- Review all suggestions before applying them to production code
- Combine with other complementary skills for comprehensive analysis

## Common Pitfalls

- Using this skill for tasks outside its domain expertise
- Applying recommendations without understanding your specific context
- Not providing enough project context for accurate analysis

## Related Skills

- `social-orchestrator` - Complementary skill for enhanced analysis
- `telegram` - Complementary skill for enhanced analysis
- `whatsapp-cloud-api` - Complementary skill for enhanced analysis

## 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: instagram-automation
description: "Automate Instagram tasks via Rube MCP (Composio): create posts, carousels, manage media, get insights, and publishing limits. Always search tools first for current schemas."
risk: critical
source: community
date_added: "2026-02-27"
---

# Instagram Automation via Rube MCP

Automate Instagram operations through Composio's Instagram toolkit via Rube MCP.

## Prerequisites

- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
- Active Instagram connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `instagram`
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
- Instagram Business or Creator account required (personal accounts not supported)

## 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 `instagram`
3. If connection is not ACTIVE, follow the returned auth link to complete Instagram/Facebook OAuth
4. Confirm connection status shows ACTIVE before running any workflows

## Core Workflows

### 1. Create a Single Image/Video Post

**When to use**: User wants to publish a single photo or video to Instagram

**Tool sequence**:
1. `INSTAGRAM_GET_USER_INFO` - Get Instagram user ID [Prerequisite]
2. `INSTAGRAM_CREATE_MEDIA_CONTAINER` - Create a media container with the image/video URL [Required]
3. `INSTAGRAM_GET_POST_STATUS` - Check if the media container is ready [Optional]
4. `INSTAGRAM_CREATE_POST` or `INSTAGRAM_POST_IG_USER_MEDIA_PUBLISH` - Publish the container [Required]

**Key parameters**:
- `image_url`: Public URL of the image to post
- `video_url`: Public URL of the video to post
- `caption`: Post caption text
- `ig_user_id`: Instagram Business account user ID

**Pitfalls**:
- Media URLs must be publicly accessible; private/authenticated URLs will fail
- Video containers may take time to process; poll GET_POST_STATUS before publishing
- Caption supports hashtags and mentions but has a 2200 character limit
- Publishing a container that is not yet finished processing returns an error

### 2. Create a Carousel Post

**When to use**: User wants to publish multiple images/videos in a single carousel post

**Tool sequence**:
1. `INSTAGRAM_CREATE_MEDIA_CONTAINER` - Create individual containers for each media item [Required, repeat per item]
2. `INSTAGRAM_CREATE_CAROUSEL_CONTAINER` - Create the carousel container referencing all media containers [Required]
3. `INSTAGRAM_GET_POST_STATUS` - Check carousel container readiness [Optional]
4. `INSTAGRAM_POST_IG_USER_MEDIA_PUBLISH` - Publish the carousel [Required]

**Key parameters**:
- `children`: Array of media container IDs for the carousel
- `caption`: Carousel post caption
- `ig_user_id`: Instagram Business account user ID

**Pitfalls**:
- Carousels require 2-10 media items; fewer or more will fail
- Each child container must be created individually before the carousel container
- All child containers must be fully processed before creating the carousel
- Mixed media (images + videos) is supported in carousels

### 3. Get Media and Insights

**When to use**: User wants to view their posts or analyze post performance

**Tool sequence**:
1. `INSTAGRAM_GET_IG_USER_MEDIA` or `INSTAGRAM_GET_USER_MEDIA` - List user's media [Required]
2. `INSTAGRAM_GET_IG_MEDIA` - Get details for a specific post [Optional]
3. `INSTAGRAM_GET_POST_INSIGHTS` or `INSTAGRAM_GET_IG_MEDIA_INSIGHTS` - Get metrics for a post [Optional]
4. `INSTAGRAM_GET_USER_INSIGHTS` - Get account-level insights [Optional]

**Key parameters**:
- `ig_user_id`: Instagram Business account user ID
- `media_id`: ID of the specific media post
- `metric`: Metrics to retrieve (e.g., impressions, reach, engagement)
- `period`: Time period for insights (e.g., day, week, lifetime)

**Pitfalls**:
- Insights are only available for Business/Creator accounts
- Some metrics require minimum follower counts
- Insight data may have a delay of up to 48 hours
- The `period` parameter must match the metric type

### 4. Check Publishing Limits

**When to use**: User wants to verify they can publish before attempting a post

**Tool sequence**:
1. `INSTAGRAM_GET_IG_USER_CONTENT_PUBLISHING_LIMIT` - Check remaining publishing quota [Required]

**Key parameters**:
- `ig_user_id`: Instagram Business account user ID

**Pitfalls**:
- Instagram enforces a 25 posts per 24-hour rolling window limit
- Publishing limit resets on a rolling basis, not at midnight
- Check limits before bulk posting operations to avoid failures

### 5. Get Media Comments and Children

**When to use**: User wants to view comments on a post or children of a carousel

**Tool sequence**:
1. `INSTAGRAM_GET_IG_MEDIA_COMMENTS` - List comments on a media post [Required]
2. `INSTAGRAM_GET_IG_MEDIA_CHILDREN` - List children of a carousel post [Optional]

**Key parameters**:
- `media_id`: ID of the media post
- `ig_media_id`: Alternative media ID parameter

**Pitfalls**:
- Comments may be paginated; follow pagination cursors for complete results
- Carousel children are returned as individual media objects
- Comment moderation settings on the account affect what is returned

## Common Patterns

### ID Resolution

**Instagram User ID**:
```
1. Call INSTAGRAM_GET_USER_INFO
2. Extract ig_user_id from response
3. Use in all subsequent API calls
```

**Media Container Status Check**:
```
1. Call INSTAGRAM_CREATE_MEDIA_CONTAINER
2. Extract container_id from response
3. Poll INSTAGRAM_GET_POST_STATUS with container_id
4. Wait until status is 'FINISHED' before publishing
```

### Two-Phase Publishing

- Phase 1: Create media container(s) with content URLs
- Phase 2: Publish the container after it finishes processing
- Always check container status between phases for video content
- For carousels, all children must complete Phase 1 before creating the carousel container

## Known Pitfalls

**Media URLs**:
- All image/video URLs must be publicly accessible HTTPS URLs
- URLs behind authentication, CDN restrictions, or that require cookies will fail
- Temporary URLs (pre-signed S3, etc.) may expire before processing completes

**Rate Limits**:
- 25 posts per 24-hour rolling window
- API rate limits apply separately from publishing limits
- Implement exponential backoff for 429 responses

**Account Requirements**:
- Only Business or Creator Instagram accounts are supported
- Personal accounts cannot use the Instagram Graph API
- The account must be connected to a Facebook Page

**Response Parsing**:
- Media IDs are numeric strings
- Insights data may be nested under different response keys
- Pagination uses cursor-based tokens

## Quick Reference

| Task | Tool Slug | Key Params |
|------|-----------|------------|
| Get user info | INSTAGRAM_GET_USER_INFO | (none) |
| Create media container | INSTAGRAM_CREATE_MEDIA_CONTAINER | image_url/video_url, caption |
| Create carousel | INSTAGRAM_CREATE_CAROUSEL_CONTAINER | children, caption |
| Publish post | INSTAGRAM_CREATE_POST | ig_user_id, creation_id |
| Publish media | INSTAGRAM_POST_IG_USER_MEDIA_PUBLISH | ig_user_id, creation_id |
| Check post status | INSTAGRAM_GET_POST_STATUS | ig_container_id |
| List user media | INSTAGRAM_GET_IG_USER_MEDIA | ig_user_id |
| Get media details | INSTAGRAM_GET_IG_MEDIA | ig_media_id |
| Get post insights | INSTAGRAM_GET_POST_INSIGHTS | media_id, metric |
| Get user insights | INSTAGRAM_GET_USER_INSIGHTS | ig_user_id, metric, period |
| Get publishing limit | INSTAGRAM_GET_IG_USER_CONTENT_PUBLISHING_LIMIT | ig_user_id |
| Get media comments | INSTAGRAM_GET_IG_MEDIA_COMMENTS | ig_media_id |
| Get carousel children | INSTAGRAM_GET_IG_MEDIA_CHILDREN | ig_media_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: instructree
description: "Map, explain, and lint repository-scoped coding-agent instructions before changing code."
category: development
risk: safe
source: community
source_repo: kotobuki09/instructree
source_type: community
date_added: "2026-08-26"
author: kotobuki09
tags: [agent-instructions, agents-md, codex, static-analysis]
tools: [claude, codex, cursor, gemini]
license: MIT
license_source: "https://github.com/kotobuki09/instructree/blob/v0.7.0/LICENSE"
---

# Instructree

## Overview

Use Instructree to establish which instruction files exist, which may apply to a target, and whether their metadata, links, or recursive imports are malformed. It audits common coding-agent instruction formats locally without calling a model or uploading repository content.

## When to Use This Skill

- Use before changing code in a repository with `AGENTS.md`, `CLAUDE.md`, Copilot instructions, agent skills, custom agents, Cursor rules, or Windsurf rules.
- Use when the user asks which instructions may apply to one target file.
- Use when auditing recursive Copilot CLI `@path` imports or exporting instruction diagnostics to CI.

## How It Works

### Step 1: Choose the local command

Work from the repository root. Prefer an already installed `instructree` command or the checked-out package's local binary.

If neither is available, explain that the next command downloads executable package code and ask for approval before running the pinned release:

```bash
npx github:kotobuki09/instructree#364dddc66badac13a284b79f0dc71f2b4362f6de scan .
```

Do not add `--yes` unless the user authorized non-interactive package downloads.

### Step 2: Run the narrowest audit

- `instructree scan . --json` inventories supported files and emits stable diagnostics.
- `instructree explain <file> --root .` shows instructions that may apply to one target.
- `instructree explain <file> --root . --effective` includes recursive Copilot CLI imports.
- `instructree imports . --json` audits the recursive `@path` graph.
- `instructree scan . --sarif` emits SARIF 2.1.0 for code-scanning integrations.
- Add `--strict` only when warnings should fail the check.

### Step 3: Interpret the result

Report file paths, line numbers, diagnostic codes, and the command's exit status. Separate schema or path errors from warnings. Describe `always`/`never` conflicts as possible conflicts requiring human review, not proof of agent behavior.

## Examples

### Audit a repository

```bash
instructree scan . --json
```

### Explain one target with recursive imports

```bash
instructree explain src/api/client.ts --root . --effective
```

### Generate a code-scanning report

```bash
instructree scan . --sarif > instructree.sarif
```

## Best Practices

- Prefer a local, already reviewed command over downloading package code.
- Use `explain` for a single target instead of scanning more scope than needed.
- Rerun the same command after an authorized instruction fix and report before-and-after diagnostics.
- Keep warnings separate from errors and state clearly when a finding is heuristic.

## Limitations

- Instructree is static analysis; it does not establish the exact precedence rules or runtime behavior of every agent client.
- Client discovery and import behavior can change, so `explain` reports what may apply rather than predicting what a model will follow.
- The audit does not prove that instruction content is correct, safe, or effective.
- Do not edit instruction files unless the user asked for changes.

## Security & Safety Notes

- Scans are read-only and local; they do not call a model or upload repository content.
- Treat any `npx` fallback as executable third-party code: keep it pinned, review the source, and obtain approval before download.
- Do not run imported instruction content. Instructree follows supported references as data only.


---
name: interactive-portfolio
description: Expert in building portfolios that actually land jobs and clients -
  not just showing work, but creating memorable experiences. Covers developer
  portfolios, designer portfolios, creative portfolios, and portfolios that
  convert visitors into opportunities.
risk: critical
source: vibeship-spawner-skills (Apache 2.0)
date_added: 2026-02-27
---

# Interactive Portfolio

Expert in building portfolios that actually land jobs and clients - not just
showing work, but creating memorable experiences. Covers developer portfolios,
designer portfolios, creative portfolios, and portfolios that convert visitors
into opportunities.

**Role**: Portfolio Experience Designer

You know a portfolio isn't a resume - it's a first impression that needs
to convert. You balance creativity with usability. You understand that
hiring managers spend 30 seconds on each portfolio. You make those 30
seconds count. You help people stand out without being gimmicky.

### Expertise

- Portfolio UX
- Project presentation
- Personal branding
- Conversion optimization
- Creative coding
- Memorable experiences

## Capabilities

- Portfolio architecture
- Project showcase design
- Interactive case studies
- Personal branding for devs/designers
- Contact conversion
- Portfolio performance
- Work presentation
- Testimonial integration

## Patterns

### Portfolio Architecture

Structure that works for portfolios

**When to use**: When planning portfolio structure

## Portfolio Architecture

### The 30-Second Test
In 30 seconds, visitors should know:
1. Who you are
2. What you do
3. Your best work
4. How to contact you

### Essential Sections
| Section | Purpose | Priority |
|---------|---------|----------|
| Hero | Hook + identity | Critical |
| Work/Projects | Prove skills | Critical |
| About | Personality + story | Important |
| Contact | Convert interest | Critical |
| Testimonials | Social proof | Nice to have |
| Blog/Writing | Thought leadership | Optional |

### Navigation Patterns
```
Option 1: Single page scroll
- Best for: Designers, creatives
- Works well with animations
- Mobile friendly

Option 2: Multi-page
- Best for: Lots of projects
- Individual case study pages
- Better for SEO

Option 3: Hybrid
- Main sections on one page
- Detailed case studies separate
- Best of both worlds
```

### Hero Section Formula
```
[Your name]
[What you do in one line]
[One line that differentiates you]
[CTA: View Work / Contact]
```

### Project Showcase

How to present work effectively

**When to use**: When building project sections

## Project Showcase

### Project Card Elements
| Element | Purpose |
|---------|---------|
| Thumbnail | Visual hook |
| Title | What it is |
| One-liner | What you did |
| Tech/tags | Quick scan |
| Results | Proof of impact |

### Case Study Structure
```
1. Hero image/video
2. Project overview (2-3 sentences)
3. The challenge
4. Your role
5. Process highlights
6. Key decisions
7. Results/impact
8. Learnings (optional)
9. Links (live, GitHub, etc.)
```

### Showing Impact
| Instead of | Write |
|------------|-------|
| "Built a website" | "Increased conversions 40%" |
| "Designed UI" | "Reduced user drop-off 25%" |
| "Developed features" | "Shipped to 50K users" |

### Visual Presentation
- Device mockups for web/mobile
- Before/after comparisons
- Process artifacts (wireframes, etc.)
- Video walkthroughs for complex work
- Hover effects for engagement

### Developer Portfolio Specifics

What works for dev portfolios

**When to use**: When building developer portfolio

## Developer Portfolio

### What Hiring Managers Look For
1. Code quality (GitHub link)
2. Real projects (not just tutorials)
3. Problem-solving ability
4. Communication skills
5. Technical depth

### Must-Haves
- GitHub profile link (cleaned up)
- Live project links
- Tech stack for each project
- Your specific contribution (for team projects)

### Project Selection
| Include | Avoid |
|---------|-------|
| Real problems solved | Tutorial clones |
| Side projects with users | Incomplete projects |
| Open source contributions | "Coming soon" |
| Technical challenges | Basic CRUD apps |

### Technical Showcase
```javascript
// Show code snippets that demonstrate:
- Clean architecture decisions
- Performance optimizations
- Clever solutions
- Testing approach
```

### Blog/Writing
- Technical deep dives
- Problem-solving stories
- Learning journeys
- Shows communication skills

### Portfolio Interactivity

Adding memorable interactive elements

**When to use**: When wanting to stand out

## Portfolio Interactivity

### Levels of Interactivity
| Level | Example | Risk |
|-------|---------|------|
| Subtle | Hover effects, smooth scroll | Low |
| Medium | Scroll animations, transitions | Medium |
| High | 3D, games, custom cursors | High |

### High-Impact, Low-Risk
- Custom cursor on desktop
- Smooth page transitions
- Project card hover effects
- Scroll-triggered reveals
- Dark/light mode toggle

### Creative Ideas
```
- Terminal-style interface (for devs)
- OS desktop metaphor
- Game-like navigation
- Interactive timeline
- 3D workspace scene
- Generative art background
```

### The Balance
- Creativity shows skill
- But usability wins jobs
- Mobile must work perfectly
- Don't hide content behind interactions
- Have a "skip" option for complex intros

## Sharp Edges

### Portfolio more complex than your actual work

Severity: MEDIUM

Situation: Spent 6 months on portfolio, have 2 projects to show

Symptoms:
- Been "working on portfolio" for months
- More excited about portfolio than projects
- Portfolio tech more impressive than work
- Afraid to launch

Why this breaks:
Procrastination disguised as work.
Portfolio IS a project, but not THE project.
Diminishing returns on polish.
Ship it and iterate.

Recommended fix:

## Right-Sizing Your Portfolio

### The MVP Portfolio
| Element | MVP Version |
|---------|-------------|
| Hero | Name + title + one line |
| Projects | 3-4 best pieces |
| About | 2-3 paragraphs |
| Contact | Email + LinkedIn |

### Time Budget
```
Week 1: Design and structure
Week 2: Build core pages
Week 3: Add 3-4 projects
Week 4: Polish and launch
```

### The Truth
- Your portfolio is not your best project
- Shipping beats perfecting
- You can always iterate
- Better projects > better portfolio

### When to Stop
- Core pages work on mobile
- 3-4 solid projects showcased
- Contact form works
- Loads in < 3 seconds
- Ship it.

### Portfolio looks great on desktop, broken on mobile

Severity: HIGH

Situation: Recruiters check on phone, everything breaks

Symptoms:
- Looks great in browser DevTools
- Broken on actual phone
- Text too small
- Buttons hard to tap
- Navigation hidden

Why this breaks:
Built desktop-first.
Didn't test on real devices.
Complex interactions don't translate.
Forgot about thumb zones.

Recommended fix:

## Mobile-First Portfolio

### Mobile Reality
- 60%+ traffic is mobile
- Recruiters browse on phones
- First impression = mobile impression

### Mobile Must-Haves
- Readable without zooming
- Tappable links (min 44px)
- Navigation works
- Projects load fast
- Contact easy to find

### Testing Checklist
```
[ ] iPhone Safari
[ ] Android Chrome
[ ] Tablet sizes
[ ] Slow 3G simulation
[ ] Real device (not just DevTools)
```

### Graceful Degradation
```css
/* Complex hover → simple tap */
@media (hover: none) {
  .hover-effect {
    /* Show content directly */
  }
}
```

### Visitors don't know what to do next

Severity: MEDIUM

Situation: Great portfolio, zero contacts

Symptoms:
- Lots of views, no contacts
- People don't know you're available
- Contact page is afterthought
- No clear ask

Why this breaks:
No clear CTA.
Contact buried at bottom.
Multiple competing actions.
Assuming visitors will figure it out.

Recommended fix:

## Portfolio CTAs

### Primary CTAs
| Goal | CTA |
|------|-----|
| Get hired | "Let's work together" |
| Freelance | "Start a project" |
| Network | "Say hello" |
| Specific role | "Hire me for [X]" |

### CTA Placement
```
Hero section: Main CTA
After projects: Secondary CTA
Footer: Final CTA
Floating: Optional persistent CTA
```

### Making Contact Easy
- Email link (mailto:)
- LinkedIn (opens new tab)
- Calendar link (Calendly)
- Simple contact form
- Copy email button

### What to Avoid
- Contact form only (people hate forms)
- Hidden contact info
- Too many options
- Vague CTAs ("Learn more")

### Portfolio shows old or irrelevant work

Severity: MEDIUM

Situation: Best work is 3 years old, newer work not shown

Symptoms:
- jQuery projects in 2024
- I did this in college
- Tech stack doesn't match target jobs
- Haven't touched portfolio in 2+ years

Why this breaks:
Haven't updated in years.
Newer work is "not ready."
Scared to remove old favorites.
Portfolio drift.

Recommended fix:

## Portfolio Freshness

### Update Cadence
| Action | Frequency |
|--------|-----------|
| Add new project | When completed |
| Remove old project | Yearly review |
| Update copy | Every 6 months |
| Tech refresh | Every 1-2 years |

### Project Pruning
Keep if:
- Still proud of it
- Relevant to target jobs
- Shows important skills
- Has good results/story

Remove if:
- Embarrassed by code/design
- Tech is obsolete
- Not relevant to goals
- Better work exists

### Showing Growth
- Latest work first
- Date projects (or don't)
- Show evolution if relevant
- Archive instead of delete

## Validation Checks

### No Clear Contact CTA

Severity: HIGH

Message: No clear way for visitors to contact you.

Fix action: Add prominent contact CTA in hero and after projects section

### Missing Mobile Viewport

Severity: HIGH

Message: Portfolio may not be mobile-responsive.

Fix action: Add <meta name='viewport' content='width=device-width, initial-scale=1'>

### Unoptimized Portfolio Images

Severity: MEDIUM

Message: Portfolio images may be slowing down load time.

Fix action: Use WebP, implement lazy loading, add srcset for responsive images

### Projects Missing Live Links

Severity: MEDIUM

Message: Projects should have live links or source code.

Fix action: Add live demo URLs and GitHub links where possible

### Projects Missing Impact/Results

Severity: LOW

Message: Projects don't show impact or results.

Fix action: Add metrics, outcomes, or testimonials to project descriptions

## Collaboration

### Delegation Triggers

- scroll animation|parallax|GSAP -> scroll-experience (Scroll experience for portfolio)
- 3D|WebGL|three.js|spline -> 3d-web-experience (3D portfolio elements)
- brand|logo|colors|identity -> branding (Personal branding)
- copy|writing|about me|bio -> copywriting (Portfolio copy)
- SEO|search|google -> seo (Portfolio SEO)

### Developer Portfolio

Skills: interactive-portfolio, frontend, scroll-experience

Workflow:

```
1. Plan portfolio structure
2. Select 3-5 best projects
3. Design hero and project sections
4. Add subtle scroll animations
5. Implement and optimize
6. Launch and share
```

### Creative Portfolio

Skills: interactive-portfolio, 3d-web-experience, scroll-experience, branding

Workflow:

```
1. Define personal brand
2. Design unique experience
3. Build interactive elements
4. Showcase work creatively
5. Ensure mobile works
6. Launch
```

## Related Skills

Works well with: `scroll-experience`, `3d-web-experience`, `landing-page-design`, `personal-branding`

## When to Use
- User mentions or implies: portfolio
- User mentions or implies: personal website
- User mentions or implies: showcase work
- User mentions or implies: developer portfolio
- User mentions or implies: designer portfolio
- User mentions or implies: creative portfolio

## 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: intercom-automation
description: "Automate Intercom tasks via Rube MCP (Composio): conversations, contacts, companies, segments, admins. Always search tools first for current schemas."
risk: critical
source: community
date_added: "2026-02-27"
---

# Intercom Automation via Rube MCP

Automate Intercom operations through Composio's Intercom toolkit via Rube MCP.

## Prerequisites

- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
- Active Intercom connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `intercom`
- 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 `intercom`
3. If connection is not ACTIVE, follow the returned auth link to complete Intercom OAuth
4. Confirm connection status shows ACTIVE before running any workflows

## Core Workflows

### 1. Manage Conversations

**When to use**: User wants to create, list, search, or manage support conversations

**Tool sequence**:
1. `INTERCOM_LIST_ALL_ADMINS` - Get admin IDs for assignment [Prerequisite]
2. `INTERCOM_LIST_CONVERSATIONS` - List all conversations [Optional]
3. `INTERCOM_SEARCH_CONVERSATIONS` - Search with filters [Optional]
4. `INTERCOM_GET_CONVERSATION` - Get conversation details [Optional]
5. `INTERCOM_CREATE_CONVERSATION` - Create a new conversation [Optional]

**Key parameters**:
- `from`: Object with `type` ('user'/'lead') and `id` for conversation creator
- `body`: Message body (HTML supported)
- `id`: Conversation ID for retrieval
- `query`: Search query object with `field`, `operator`, `value`

**Pitfalls**:
- CREATE_CONVERSATION requires a contact (user/lead) as the `from` field, not an admin
- Conversation bodies support HTML; plain text is auto-wrapped in `<p>` tags
- Search query uses structured filter objects, not free-text search
- Conversation IDs are numeric strings

### 2. Reply and Manage Conversation State

**When to use**: User wants to reply to, close, reopen, or assign conversations

**Tool sequence**:
1. `INTERCOM_GET_CONVERSATION` - Get current state [Prerequisite]
2. `INTERCOM_REPLY_TO_CONVERSATION` - Add a reply [Optional]
3. `INTERCOM_ASSIGN_CONVERSATION` - Assign to admin/team [Optional]
4. `INTERCOM_CLOSE_CONVERSATION` - Close conversation [Optional]
5. `INTERCOM_REOPEN_CONVERSATION` - Reopen closed conversation [Optional]

**Key parameters**:
- `conversation_id` / `id`: Conversation ID
- `body`: Reply message body (HTML supported)
- `type`: Reply type ('admin' or 'user')
- `admin_id`: Admin ID for replies from admin, assignment, and close/reopen
- `assignee_id`: Admin or team ID for assignment
- `message_type`: 'comment' (default) or 'note' (internal)

**Pitfalls**:
- `admin_id` is REQUIRED for admin replies, close, reopen, and assignment operations
- Always fetch admin IDs first with LIST_ALL_ADMINS or IDENTIFY_AN_ADMIN
- Duplicate sends can occur on retry; implement idempotency checks
- Internal notes use `message_type: 'note'`; visible only to workspace members
- Closing requires an admin_id and optional body message

### 3. Manage Contacts

**When to use**: User wants to search, view, or manage contacts (users and leads)

**Tool sequence**:
1. `INTERCOM_SEARCH_CONTACTS` - Search contacts with filters [Required]
2. `INTERCOM_GET_A_CONTACT` - Get specific contact [Optional]
3. `INTERCOM_SHOW_CONTACT_BY_EXTERNAL_ID` - Look up by external ID [Optional]
4. `INTERCOM_LIST_CONTACTS` - List all contacts [Optional]
5. `INTERCOM_LIST_TAGS_ATTACHED_TO_A_CONTACT` - Get contact tags [Optional]
6. `INTERCOM_LIST_ATTACHED_SEGMENTS_FOR_CONTACT` - Get contact segments [Optional]
7. `INTERCOM_DETACH_A_CONTACT` - Remove contact from company [Optional]

**Key parameters**:
- `contact_id`: Contact ID for retrieval
- `external_id`: External system ID for lookup
- `query`: Search filter object with `field`, `operator`, `value`
- `pagination`: Object with `per_page` and `starting_after` cursor

**Pitfalls**:
- SEARCH_CONTACTS uses structured query filters, not free-text; format: `{field, operator, value}`
- Supported operators: `=`, `!=`, `>`, `<`, `~` (contains), `!~` (not contains), `IN`, `NIN`
- Contact types are 'user' (identified) or 'lead' (anonymous)
- LIST_CONTACTS returns paginated results; use `starting_after` cursor for pagination
- External IDs are case-sensitive

### 4. Manage Admins and Teams

**When to use**: User wants to list workspace admins or identify specific admins

**Tool sequence**:
1. `INTERCOM_LIST_ALL_ADMINS` - List all admins and teams [Required]
2. `INTERCOM_IDENTIFY_AN_ADMIN` - Get specific admin details [Optional]

**Key parameters**:
- `admin_id`: Admin ID for identification

**Pitfalls**:
- LIST_ALL_ADMINS returns both admins and teams
- Admin IDs are required for conversation replies, assignment, close, and reopen
- Teams appear in the admins list with `type: 'team'`

### 5. View Segments and Counts

**When to use**: User wants to view segments or get aggregate counts

**Tool sequence**:
1. `INTERCOM_LIST_SEGMENTS` - List all segments [Optional]
2. `INTERCOM_LIST_ATTACHED_SEGMENTS_FOR_CONTACT` - Segments for a contact [Optional]
3. `INTERCOM_LIST_ATTACHED_SEGMENTS_FOR_COMPANIES` - Segments for a company [Optional]
4. `INTERCOM_GET_COUNTS` - Get aggregate counts [Optional]

**Key parameters**:
- `contact_id`: Contact ID for segment lookup
- `company_id`: Company ID for segment lookup
- `type`: Count type ('conversation', 'company', 'user', 'tag', 'segment')
- `count`: Sub-count type

**Pitfalls**:
- GET_COUNTS returns approximate counts, not exact numbers
- Segment membership is computed; changes may not reflect immediately

### 6. Manage Companies

**When to use**: User wants to list companies or manage company-contact relationships

**Tool sequence**:
1. `INTERCOM_LIST_ALL_COMPANIES` - List all companies [Required]
2. `INTERCOM_LIST_ATTACHED_SEGMENTS_FOR_COMPANIES` - Get company segments [Optional]
3. `INTERCOM_DETACH_A_CONTACT` - Remove contact from company [Optional]

**Key parameters**:
- `company_id`: Company ID
- `contact_id`: Contact ID for detachment
- `page`: Page number for pagination
- `per_page`: Results per page

**Pitfalls**:
- Company-contact relationships are managed through contact endpoints
- DETACH_A_CONTACT removes the contact-company association, not the contact itself

## Common Patterns

### Search Query Filters

**Single filter**:
```json
{
  "field": "email",
  "operator": "=",
  "value": "user@example.com"
}
```

**Multiple filters (AND)**:
```json
{
  "operator": "AND",
  "value": [
    {"field": "role", "operator": "=", "value": "user"},
    {"field": "created_at", "operator": ">", "value": 1672531200}
  ]
}
```

**Supported fields for contacts**: email, name, role, created_at, updated_at, signed_up_at, last_seen_at, external_id

**Supported fields for conversations**: created_at, updated_at, source.type, state, open, read

### Pagination

- Most list endpoints use cursor-based pagination
- Check response for `pages.next` with `starting_after` cursor
- Pass cursor in `pagination.starting_after` for next page
- Continue until `pages.next` is null

### Admin ID Resolution

```
1. Call INTERCOM_LIST_ALL_ADMINS to get all admins
2. Find the desired admin by name or email
3. Use admin.id for replies, assignments, and state changes
```

## Known Pitfalls

**Admin ID Requirement**:
- Admin ID is required for: reply (as admin), assign, close, reopen
- Always resolve admin IDs first with LIST_ALL_ADMINS

**HTML Content**:
- Conversation bodies are HTML
- Plain text is auto-wrapped in paragraph tags
- Sanitize HTML input to prevent rendering issues

**Idempotency**:
- Replies and conversation creation are not idempotent
- Duplicate sends can occur on retry or timeout
- Track message IDs to prevent duplicates

**Rate Limits**:
- Default: ~1000 requests per minute (varies by plan)
- 429 responses include rate limit headers
- Implement exponential backoff for retries

## Quick Reference

| Task | Tool Slug | Key Params |
|------|-----------|------------|
| List conversations | INTERCOM_LIST_CONVERSATIONS | (pagination) |
| Search conversations | INTERCOM_SEARCH_CONVERSATIONS | query |
| Get conversation | INTERCOM_GET_CONVERSATION | id |
| Create conversation | INTERCOM_CREATE_CONVERSATION | from, body |
| Reply to conversation | INTERCOM_REPLY_TO_CONVERSATION | conversation_id, body, admin_id |
| Assign conversation | INTERCOM_ASSIGN_CONVERSATION | conversation_id, admin_id, assignee_id |
| Close conversation | INTERCOM_CLOSE_CONVERSATION | id, admin_id |
| Reopen conversation | INTERCOM_REOPEN_CONVERSATION | id, admin_id |
| Search contacts | INTERCOM_SEARCH_CONTACTS | query |
| Get contact | INTERCOM_GET_A_CONTACT | contact_id |
| Contact by external ID | INTERCOM_SHOW_CONTACT_BY_EXTERNAL_ID | external_id |
| List contacts | INTERCOM_LIST_CONTACTS | (pagination) |
| Contact tags | INTERCOM_LIST_TAGS_ATTACHED_TO_A_CONTACT | contact_id |
| Contact segments | INTERCOM_LIST_ATTACHED_SEGMENTS_FOR_CONTACT | contact_id |
| Detach contact | INTERCOM_DETACH_A_CONTACT | contact_id, company_id |
| List admins | INTERCOM_LIST_ALL_ADMINS | (none) |
| Identify admin | INTERCOM_IDENTIFY_AN_ADMIN | admin_id |
| List segments | INTERCOM_LIST_SEGMENTS | (none) |
| Company segments | INTERCOM_LIST_ATTACHED_SEGMENTS_FOR_COMPANIES | company_id |
| Get counts | INTERCOM_GET_COUNTS | type, count |
| List companies | INTERCOM_LIST_ALL_COMPANIES | page, per_page |

## 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: internal-comms
description: "Write internal communications such as status reports, leadership updates, 3P updates, newsletters, FAQs, incident reports, and project updates using repeatable internal formats."
risk: safe
source: "https://github.com/anthropics/skills"
date_added: "2026-03-21"
license: Complete terms in LICENSE.txt
---

## When to use this skill
To write internal communications, use this skill for:
- 3P updates (Progress, Plans, Problems)
- Company newsletters
- FAQ responses
- Status reports
- Leadership updates
- Project updates
- Incident reports

## How to use this skill

To write any internal communication:

1. **Identify the communication type** from the request
2. **Load the appropriate guideline file** from the `examples/` directory:
    - `examples/3p-updates.md` - For Progress/Plans/Problems team updates
    - `examples/company-newsletter.md` - For company-wide newsletters
    - `examples/faq-answers.md` - For answering frequently asked questions
    - `examples/general-comms.md` - For anything else that doesn't explicitly match one of the above
3. **Follow the specific instructions** in that file for formatting, tone, and content gathering

If the communication type doesn't match any existing guideline, ask for clarification or more context about the desired format.

## Keywords
3P updates, company newsletter, company comms, weekly update, faqs, common questions, updates, internal comms

## 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: internal-comms-anthropic
description: "To write internal communications, use this skill for:"
risk: safe
source: community
date_added: "2026-02-27"
---

## When to use this skill
To write internal communications, use this skill for:
- 3P updates (Progress, Plans, Problems)
- Company newsletters
- FAQ responses
- Status reports
- Leadership updates
- Project updates
- Incident reports

## How to use this skill

To write any internal communication:

1. **Identify the communication type** from the request
2. **Load the appropriate guideline file** from the `examples/` directory:
    - `examples/3p-updates.md` - For Progress/Plans/Problems team updates
    - `examples/company-newsletter.md` - For company-wide newsletters
    - `examples/faq-answers.md` - For answering frequently asked questions
    - `examples/general-comms.md` - For anything else that doesn't explicitly match one of the above
3. **Follow the specific instructions** in that file for formatting, tone, and content gathering

If the communication type doesn't match any existing guideline, ask for clarification or more context about the desired format.

## Keywords
3P updates, company newsletter, company comms, weekly update, faqs, common questions, updates, internal comms

## 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: internal-comms-community
description: "To write internal communications, use this skill for:"
risk: safe
source: community
date_added: "2026-02-27"
---

## When to use this skill
To write internal communications, use this skill for:
- 3P updates (Progress, Plans, Problems)
- Company newsletters
- FAQ responses
- Status reports
- Leadership updates
- Project updates
- Incident reports

## How to use this skill

To write any internal communication:

1. **Identify the communication type** from the request
2. **Load the appropriate guideline file** from the `examples/` directory:
    - `examples/3p-updates.md` - For Progress/Plans/Problems team updates
    - `examples/company-newsletter.md` - For company-wide newsletters
    - `examples/faq-answers.md` - For answering frequently asked questions
    - `examples/general-comms.md` - For anything else that doesn't explicitly match one of the above
3. **Follow the specific instructions** in that file for formatting, tone, and content gathering

If the communication type doesn't match any existing guideline, ask for clarification or more context about the desired format.

## Keywords
3P updates, company newsletter, company comms, weekly update, faqs, common questions, updates, internal comms

## 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: interview-coach
description: "Full job search coaching system — JD decoding, resume, storybank, mock interviews, transcript analysis, comp negotiation. 23 commands, persistent state."
category: productivity
risk: safe
source: community
date_added: "2026-03-11"
author: dbhat93
tags: [interview, job-search, coaching, career, storybank, negotiation]
tools: [claude]
---

# Interview Coach

## Overview

A persistent, adaptive coaching system for the full job search lifecycle.
Not a question bank — an opinionated system that tracks your patterns,
scores your answers, and gets sharper the more you use it. State persists
in `coaching_state.md` across sessions so you always pick up where you left off.

## Install

```bash
npx skills add dbhat93/job-search-os
```

Then type `/coach` → `kickoff`.

## When to Use This Skill

- Use when starting a job search and need a structured system
- Use when preparing for a specific interview (company research, mock, hype)
- Use when you want to analyze a past interview transcript
- Use when negotiating an offer or handling comp questions on recruiter screens
- Use when building or maintaining a storybank of interview-ready stories

## What It Covers

- **JD decoding** — six lenses, fit verdict, recruiter questions to ask
- **Resume + LinkedIn** — ATS audit, bullet rewrites, platform-native optimization
- **Mock interviews** — behavioral, system design, case, panel, technical formats
- **Transcript analysis** — paste from Otter/Zoom/Grain, auto-detected format
- **Storybank** — STAR stories with earned secrets, retrieval drills, portfolio optimization
- **Comp + negotiation** — pre-offer scripting, offer analysis, exact negotiation scripts
- **23 total commands** across the full search lifecycle

## Examples

### Example 1: Start your job search

```
/coach
kickoff
```

The coach asks for your resume, target role, and timeline — then builds
your profile and gives you a prioritized action plan.

### Example 2: Prep for a specific company

```
/coach
prep Stripe Senior PM
```

Runs company research, generates a role-specific prep brief, and queues
up mock interview questions tailored to Stripe's process.

### Example 3: Analyze an interview transcript

```
/coach
analyze
```

Paste a raw transcript from Otter, Zoom, or any tool. The coach
auto-detects the format, scores each answer across five dimensions,
and gives you a drill plan targeting your specific gaps.

### Example 4: Handle a comp question

```
/coach
salary
```

Coaches you through the recruiter screen "what are your salary
expectations?" moment with a defensible range and exact scripts.

## Source

https://github.com/dbhat93/job-search-os

## 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: interview-style-doc-building
description: "Build structured strategy documents by asking one question at a time and patching the file."
category: productivity
risk: critical
source: community
source_repo: davidondrej/skills
source_type: community
date_added: "2026-07-07"
author: davidondrej
tags: [documentation, interview, planning]
tools: [claude, codex]
license: "MIT"
license_source: "https://github.com/davidondrej/skills/blob/main/LICENSE"
---

# Interview-Style Doc Building

The user's preferred mode for creating durable strategic docs. AI does NOT propose content — AI asks one question, the user answers, AI patches the file, AI asks the next question. The file IS the conversation's output, updated incrementally.

## When to Use

- Building a new SSOT file (life priorities, life vision, principles, frameworks, ranked lists).
- Filling out a structured doc the user explicitly wants to author themselves.
- Quarterly/annual reviews where the user's words go into the file.

**NOT for:** day planning (use `day-plan`), task triage (`organize-tasks`), or anything where AI proposes content first.

## The Loop

1. **Create the file** with a skeleton (header, sections, "to be filled in" placeholders). Single `write_file` for the new file. After this, NEVER overwrite — only `patch`.
2. **Ask ONE question.** Concise. Specific. Single-faceted. Open-ended where possible.
3. **Wait for the answer.** Don't ask the next question yet.
4. **Patch the file** with the user's answer in the correct section.
5. **Re-ask** — next question, or follow-up if the answer was incomplete.
6. Repeat until the file is complete.

## Hard Rules

- **One question at a time.** Never dump multiple questions in a single message. The user has flagged this.
- **Patch, don't overwrite.** After the initial skeleton, use `patch` for every update. Never `write_file` to an existing doc.
- **Update the file BEFORE asking the next question.** Order: receive answer → patch file → ask next question. Not the reverse.
- **Lists from the user are UNORDERED SETS.** When the user lists items in response to "which X should we cover?" or "what are the Ys?", that is a SET, not a ranking. Never infer rank, priority, or sequence from the order they typed them. If you need ordering, ask explicitly: "Which of these is #1?"
- **Ask dynamics, not names.** When the user references a person, don't ask "who is X?" — ask about the role/dynamic.
- **No snark, no attitude, no filler.** Concise questions, concise acknowledgments.
- **No speculative additions.** Don't invent sections, edge cases, or "anything else?" prompts unless the user asks.

## Question Design

- **Domain-discovery, not confirmation.** "What wins against everything else?" — not "Is Business #1?"
- **Surface new reality.** Each question should pull out info AI doesn't already have.
- **Engine-move framing where applicable.** "What's the thing that, if true, makes the rest obvious?"
- **Concrete over abstract.** "What's #2 — the domain that wins against everything except #1?" beats "Tell me about your second priority."

## File Patching Pattern

After each answer:
1. Read the relevant section (if not already in context).
2. `patch` with `old_string` = placeholder or previous entry, `new_string` = updated content with the user's words preserved.
3. Confirm the diff. Move on.

For ranked lists, append one rank at a time:
```
1. **Business** — Q2 #1 goal: ...
2. **Health** — get below 81.0 kg, sleep 9h/day, ...
```
Each rank gets patched in as the user confirms it.

## Common Pitfalls

- **Assuming order from a set.** The user lists "A, B, C, D" → AI writes "1. A, 2. B, 3. C, 4. D" → the user flags it. ALWAYS confirm rank explicitly.
- **Asking too many questions at once.** Even bundling 2 violates the rule.
- **Overwriting the file** instead of patching specific sections — destroys prior content.
- **Adding AI-generated content** to fill out sections. Sections stay empty until the user provides the content.
- **Skipping the file update** between Q&A pairs — the doc falls out of sync.

## Pairing with Other Skills

- `day-plan` — different pattern (task triage), not interview-style.
- `organize-tasks` — Todoist-specific.
- `memory-management` — separate from this; persona/preferences go to memory.

## Limitations

- Adapted from `davidondrej/skills`; verify local paths, tools, credentials, and agent features before acting.
- For commands, remote access, scheduling, browser automation, or file-changing workflows, get explicit user approval and confirm the target environment first.


---
name: invariant-guard
description: "Correctness-first: forces writing the function contract, loop invariant, termination argument, and edge cases BEFORE code. Catches Boyer-Moore, leftmost binary search, QuickSelect traps."
risk: safe
source: community
source_repo: morsechimwai/lemmaly
source_type: community
date_added: "2026-05-26"
author: morsechimwai
tags: [algorithms, correctness, loop-invariants, contracts, edge-cases, verification]
tools: [claude-code, antigravity, cursor, gemini-cli, codex-cli]
license: "Apache-2.0"
license_source: "https://github.com/morsechimwai/lemmaly/blob/main/LICENSE"
---

# invariant-guard — Correctness-First Coding

The model knows what a loop invariant is. It knows recursion needs a base case. It knows about empty lists, integer overflow, and the difference between `<` and `≤`. It just does not write these down before producing code, so it ships subtle correctness bugs that tests do not catch.

invariant-guard fixes the behavior. State the invariants. State the base case. State the termination argument. State the edge cases. Then write the code — and verify that the code maintains what you stated.

**Violating the letter of these rules is violating the spirit of the skill.** "I know this algorithm" is the exact rationalization that ships off-by-one and missing-postcondition bugs.

## When to Use This Skill

Use **invariant-guard** when writing or reviewing algorithms where the obvious implementation is subtly wrong:

- Postcondition stronger than the loop's natural invariant: Boyer–Moore majority, Floyd's cycle detection, leftmost vs any binary search, QuickSelect partition.
- In-place mutation with read+write pointers: dedup-in-place, partition, rotate.
- Recursion with multiple parameters or accumulator state.
- Off-by-one suspects with duplicates, empty inputs, boundary values.
- Iterative refinements that must terminate: fixed-point, Newton, EM.
- Any function where you catch yourself thinking "I know this algorithm" — the trap is usually in the contract, not the loop body.

Pairs with `lemmaly` (picks the algorithm) and `mathguard` (picks the math). Load `invariant-guard` *after* the algorithm has been chosen and *before* the loop body is written.

## The Iron Law

```text
NO LOOP OR RECURSION WITHOUT A WRITTEN INVARIANT AND TERMINATION ARGUMENT
```

If you cannot write the invariant in one sentence, you have not designed the loop. Write code anyway and you are coding by guess — and the bug will be in the case you did not enumerate.

## Non-negotiable rules

1. **Every loop gets a one-line invariant.** Before writing any loop, state in one sentence what is true at the top of every iteration. Examples:
   - "At loop top: `result` contains the sum of `a[0..i)`."
   - "At loop top: `lo ≤ target_position ≤ hi`."
   - "At loop top: `seen` contains every element processed so far; `dups` contains every element that appeared at least twice."

   If you cannot write the invariant in one sentence, you have not designed the loop yet.

2. **Every loop gets a one-line termination argument.** Name the quantity that strictly decreases (or strictly increases toward a bound) on every iteration. Examples:
   - "`hi − lo` strictly decreases each iteration."
   - "`i` increases by 1 and is bounded above by `n`."
   - "`stack.length` strictly decreases each pop; nothing pushes inside this branch."

   No termination argument, no loop.

3. **Every recursion gets an explicit base case and a measure.** Before writing a recursive function, state:
   - The base case(s) — the smallest inputs that return without recursing.
   - The measure — a non-negative integer that strictly decreases on every recursive call (e.g. `len(xs)`, `hi − lo`, `depth`, `n`).
   - The combination — how the recursive results combine into the answer.

   No base case + measure, no recursion. (Mutual recursion: state the measure across the cycle.)

4. **List edge cases before writing, not after.** For every function operating on a collection or number, list which of these apply and how they behave:
   - Empty input (`[]`, `""`, `null`, `undefined`, `None`).
   - Singleton (`[x]`).
   - All-equal elements.
   - Already-sorted / reverse-sorted input.
   - Duplicates (when uniqueness is assumed).
   - Negative numbers, zero, exactly the boundary value.
   - Integer overflow / underflow at the type max/min.
   - NaN, ±Infinity, `-0`, denormals (for floats).
   - Off-by-one boundaries: index 0, index n−1, index n, length 0, length 1.
   - Concurrent modification while iterating.

   The cases that apply must each have a one-phrase expected behavior written down.

5. **Make illegal states unreachable, not just unhandled.** Prefer encoding constraints in types and structure so the wrong state cannot be constructed:
   - Sum type over boolean flag soup (`Loading | Loaded(data) | Error(msg)` not `{loading, data, error}`).
   - Newtype for IDs that must not be swapped (`UserId` vs `OrderId`).
   - Non-empty list type when the function requires at least one element.
   - Parsed value at the boundary, not validated repeatedly downstream (parse-don't-validate).

   If the language cannot encode it, write the invariant as a comment and assert it at the boundary.

## The pre-write protocol

Before producing non-trivial code that has loops, recursion, or non-trivial state, your message must contain — in this order:

1. **Function contract** — preconditions, postconditions, and what the function returns. One line each.
2. **Loop invariants** — one per loop. (Rule 1.)
3. **Termination arguments** — one per loop or recursion. (Rules 2, 3.)
4. **Base cases and measure** — for recursion. (Rule 3.)
5. **Edge case table** — bullets, one per applicable case, with expected behavior. (Rule 4.)
6. **Illegal states made unrepresentable** — name the types or asserts that enforce invariants. (Rule 5.)
7. **The code.**
8. **Self-check** — one line per loop confirming the invariant holds at top, body preserves it, and exit implies postcondition.

If any of 1–6 is missing, do not emit code.

## Worked trap — Boyer–Moore majority vote

This is the canonical "the trap is in the contract, not the loop body" case.

**Naive baseline (what gets shipped without the skill):**

```typescript
function findMajority(arr: number[]): number | null {
  if (arr.length === 0) return null;
  let candidate = arr[0], count = 0;
  for (const x of arr) {
    if (count === 0) candidate = x;
    if (x === candidate) count++; else count--;
  }
  return candidate;   // BUG: returns the candidate even when no majority exists
}
```

This implementation fails on `[1,2,3]` (returns `3`, expected `null`) and `[2,2,1,1]` (returns `1`, expected `null`). The voting loop is correct; the postcondition is wrong.

**Why the protocol catches it.** Writing **step 1 (function contract)** forces the postcondition in plain language:

> Returns `x` iff `count(x, arr) > arr.length / 2`; else `null`.

Then writing **step 2 (loop invariant)** forces the invariant of the voting pass:

> If a strict majority element exists in `arr`, it equals `candidate` when the loop exits.

These two statements are not equivalent. The loop invariant guarantees "if a majority exists, it is the candidate" — not "the candidate is a majority." Once you write both down, the gap is visible: you need a second pass to verify, or the postcondition is unmet.

**Correct implementation that survives the protocol:**

```typescript
function findMajority(arr: number[]): number | null {
  if (arr.length === 0) return null;
  // Pass 1: vote.
  let candidate = arr[0], count = 0;
  // inv: if a strict majority exists in arr, it equals candidate at every count===0 reset.
  for (const x of arr) {
    if (count === 0) candidate = x;
    if (x === candidate) count++; else count--;
  }
  // Pass 2: verify — the voting invariant is strictly weaker than the postcondition.
  let tally = 0;
  // inv: tally = count of candidate in arr[0..i).
  for (const x of arr) if (x === candidate) tally++;
  return tally * 2 > arr.length ? candidate : null;
}
```

**Pattern to generalize.** The same trap appears in:

- **Floyd's cycle detection** — finding the meeting point tells you a cycle exists, *not* where it starts. You need a second walk.
- **Two-pointer "find any"** vs **"find leftmost"** — the loop invariant for one does not satisfy the postcondition of the other.
- **QuickSelect partition** — the loop returns a position; the postcondition is that the element at that position is the k-th smallest. Off by one in the partition invariant silently breaks it.
- **DP with reconstruction** — the table tells you the optimum value; reconstructing the optimum path needs separate invariants on the choice array.

In every case: **write the postcondition first; write the loop invariant second; check that the second implies the first. If not, you are missing a pass, a check, or an auxiliary state.**

## Canonical example — binary search for the leftmost match

Most "I know binary search" implementations are written for "find any match." The trap is the postcondition.

**Problem.** Given a sorted array with duplicates, return the index of the **leftmost** occurrence of `target`, or `-1`.

### Without the protocol — returns any match

```ts
function leftmost(a: number[], target: number): number {
  let lo = 0, hi = a.length - 1;
  while (lo <= hi) {
    const mid = (lo + hi) >> 1;
    if (a[mid] === target) return mid;       // returns ANY occurrence
    if (a[mid] < target) lo = mid + 1; else hi = mid - 1;
  }
  return -1;
}
// leftmost([1,2,2,2,3], 2) → may return 2, not 1
```

The loop invariant ("target lies in `a[lo..hi]` if anywhere") is satisfied. But the postcondition ("returned index is the *smallest* `i` with `a[i] === target`") is strictly stronger. The loop body's early return abandons the search before reaching the leftmost.

### With the protocol — contract-driven leftmost

```ts
function leftmost(a: number[], target: number): number {
  // contract:
  //   pre:  a is sorted ascending
  //   post: returns smallest i with a[i] === target, or -1 if absent
  let lo = 0, hi = a.length;                 // half-open [lo, hi)
  // inv: every index < lo has a[i] < target; every index ≥ hi has a[i] > target OR is past leftmost match
  // term: hi - lo strictly halves each iteration
  while (lo < hi) {
    const mid = (lo + hi) >> 1;
    if (a[mid] < target) lo = mid + 1; else hi = mid;
  }
  // exit: lo === hi, and by invariant lo is the leftmost index where a[lo] >= target
  return lo < a.length && a[lo] === target ? lo : -1;
}
```

Same loop shape. The difference is the contract was written first — and the loop body was chosen to maintain an invariant that *implies* the postcondition.

## Common invariant patterns to reach for

| Loop / algorithm shape | Canonical invariant | Termination |
|---|---|---|
| Linear scan accumulating | `acc = f(a[0..i))` at top | `i` increases by 1, bounded by `n` |
| Two-pointer (sorted) | `target (if any) lies in a[lo..hi]` | `hi − lo` strictly decreases |
| Binary search | `target (if present) ∈ a[lo..hi]` and `a[lo..hi]` non-empty | `hi − lo` strictly halves |
| Sliding window | window `[l..r)` satisfies the constraint; answer ≥ best so far | `r` advances at least once per outer iter |
| BFS | every node at distance < d has been popped; queue contains some at distance d | strict node count decrease per pop |
| DFS / recursion on tree | result for subtree rooted at v = combine(children results) | depth (or remaining nodes) strictly decreases |
| Divide and conquer | result on `a[lo..hi]` = combine(results on the two halves) | `hi − lo` strictly halves |
| Greedy with priority queue | extracted item is globally optimal for the remaining problem | heap size strictly decreases per extract |
| Union-Find op | `find(x)` always returns the canonical root of x's component | tree height bounded by O(log n) (with rank) |
| In-place partition | `a[0..i)` < pivot; `a[i..j)` ≥ pivot; `a[j..n)` unseen | `n − j` strictly decreases |

## Edge case table — defaults to consider

| Input shape | Cases to check |
|---|---|
| Array / list | empty, singleton, all-equal, sorted, reversed, with duplicates |
| String | empty, single char, all whitespace, unicode (surrogates, combining), bytes vs code points |
| Integer | 0, 1, −1, MIN, MAX, MAX − 1, near overflow in arithmetic, division by 0 |
| Float | 0.0, −0.0, NaN, ±Inf, denormal, exact comparison should be ε-based |
| Map / dict | empty, missing key (default vs error), key collision semantics |
| Tree / graph | empty, single node, cycle (if undirected), self-loop, multigraph, disconnected |
| Stream / iterator | empty, infinite, single yield, exception mid-iteration |
| Time / date | DST transition, leap second/day, timezone offset, epoch boundary |
| Concurrent | empty contention, single thread, max contention, cancellation mid-op |

## Output discipline

Code you emit must:

- Have one comment per loop stating the invariant (use `// inv:` or `# inv:`).
- Have one comment per recursion stating the base case and measure.
- Handle every edge case you listed in step 5, or explicitly delegate ("throws on empty — caller responsibility").
- Assert preconditions at function entry when the language supports it cheaply.
- Use types (sum types, newtypes, non-empty, non-null) over runtime checks where the language allows.

## When to escalate or redirect

- The function is performance-critical and you have not picked the algorithm — go back to **`lemmaly`** first; pick the algorithm, then state its invariants here.
- The technique is mathematical (probabilistic, FFT, geometry) — load **`mathguard`**; invariants for approximate algorithms include ε-bounds, not equality.
- The code is concurrent — invariants must account for interleaving; explicitly state "single-threaded only" if that is the assumption.

## Rationalizations to watch for

| Excuse | Reality |
| --- | --- |
| "I know this algorithm — single pass, done." | Knowing the loop ≠ knowing the contract. The trap usually lives in the postcondition the loop does not enforce. |
| "I traced it in my head, it works." | Mental tracing skips edge cases. Write the invariant; check it implies the postcondition. |
| "Edge cases are obvious." | Then write them down in 30 seconds. If they are obvious, the table is cheap. If they are not, the table just saved you. |
| "Tests will catch it." | Tests catch the examples you thought of. The trap is the example you did not. Postconditions catch all examples. |
| "The postcondition is implied." | If it were, the natural loop invariant would equal it. When they differ (Boyer–Moore, leftmost search, QuickSelect), you need a second pass, an extra check, or auxiliary state. |
| "Adding a verification pass feels redundant." | Boyer–Moore voting + verification is still O(n). "Feels redundant" is the rationalization that ships the bug. |

## Red flags — STOP and write the invariant first

- About to write `while (...)` without having stated what is true on entry.
- About to write `if (i === n − 1)` or `if (i === n)` — boundary suspicious, restate the invariant.
- About to recurse without naming the base case in this message.
- About to write `// TODO: handle empty` — handle it now or change the type so empty is impossible.
- About to use `==` on floats.
- About to compare across signed/unsigned or across types where overflow rolls.
- About to silently swallow an error in the middle of a loop ("just continue").
- Tests pass but you did not actually state what the function guarantees.
- "It works on the examples I tried."

## Verification checklist

Before claiming the function is correct:

- [ ] Every loop has a one-line `// inv:` comment in code.
- [ ] Every loop has a termination argument written down (in comment or PR description).
- [ ] Every recursion names its base case and measure in code.
- [ ] The function's postcondition is written and is implied by the exit state of the last loop.
- [ ] Every applicable edge case from the table has a test or an explicit "delegated to caller" note.
- [ ] At least one test exercises each non-trivial boundary (empty, singleton, max, off-by-one).
- [ ] Illegal states the function rejects are either unrepresentable in the type, or asserted at entry.
- [ ] For approximate/randomized algorithms (escalated to mathguard): ε-bounds are part of the postcondition, not equality.

Cannot check every box? The code is example-correct, not behavior-correct. Either fill the gap or downgrade the function's claimed contract.

## Limitations

- **Not an automated prover.** invariant-guard requires the author to *write* invariants; it does not mechanically check them. Pair with property-based tests for stronger evidence.
- **Concurrency is out of scope by default.** Stated invariants assume single-threaded execution unless explicitly extended; multi-threaded reasoning needs additional happens-before / linearizability arguments.
- **Float and overflow edge cases are language-specific.** The edge-case table is a checklist, not a substitute for understanding your language's numeric semantics.
- **Will slow down trivial code.** For one-liners that obviously cannot fail, the protocol is overhead; reserve it for non-trivial loops, recursion, and in-place mutation.
- **Documentation is the only enforcement.** If the author skips writing the invariants, this skill cannot detect that — pair with code review or a PR template that asks for the contract.

## The thesis, in one line

> **Tests verify examples. Invariants verify behavior. AI assistants ship example-correct, behavior-wrong code by default. invariant-guard makes them reason about behavior first.**

## Related Skills

- `lemmaly` — algorithm choice must be settled before invariants; load lemmaly first if the algorithm family is unclear.
- `mathguard` — ε-bounded postconditions for approximate / randomized algorithms.
- `complexity-cuts` — if 3+ optimization transformations have failed tests, the bug is a missing contract, not a missing optimization — escalate here.