mirror of
https://github.com/affaan-m/everything-claude-code.git
synced 2026-04-12 04:33:29 +08:00
Merge branch 'main' into main
This commit is contained in:
Affaan Mustafa
337
skills/claude-api/SKILL.md
Normal file
337
skills/claude-api/SKILL.md
Normal file
@@ -0,0 +1,337 @@
|
||||
---
|
||||
name: claude-api
|
||||
description: Anthropic Claude API patterns for Python and TypeScript. Covers Messages API, streaming, tool use, vision, extended thinking, batches, prompt caching, and Claude Agent SDK. Use when building applications with the Claude API or Anthropic SDKs.
|
||||
origin: ECC
|
||||
---
|
||||
|
||||
# Claude API
|
||||
|
||||
Build applications with the Anthropic Claude API and SDKs.
|
||||
|
||||
## When to Activate
|
||||
|
||||
- Building applications that call the Claude API
|
||||
- Code imports `anthropic` (Python) or `@anthropic-ai/sdk` (TypeScript)
|
||||
- User asks about Claude API patterns, tool use, streaming, or vision
|
||||
- Implementing agent workflows with Claude Agent SDK
|
||||
- Optimizing API costs, token usage, or latency
|
||||
|
||||
## Model Selection
|
||||
|
||||
| Model | ID | Best For |
|
||||
|-------|-----|----------|
|
||||
| Opus 4.1 | `claude-opus-4-1` | Complex reasoning, architecture, research |
|
||||
| Sonnet 4 | `claude-sonnet-4-0` | Balanced coding, most development tasks |
|
||||
| Haiku 3.5 | `claude-3-5-haiku-latest` | Fast responses, high-volume, cost-sensitive |
|
||||
|
||||
Default to Sonnet 4 unless the task requires deep reasoning (Opus) or speed/cost optimization (Haiku). For production, prefer pinned snapshot IDs over aliases.
|
||||
|
||||
## Python SDK
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
pip install anthropic
|
||||
```
|
||||
|
||||
### Basic Message
|
||||
|
||||
```python
|
||||
import anthropic
|
||||
|
||||
client = anthropic.Anthropic() # reads ANTHROPIC_API_KEY from env
|
||||
|
||||
message = client.messages.create(
|
||||
model="claude-sonnet-4-0",
|
||||
max_tokens=1024,
|
||||
messages=[
|
||||
{"role": "user", "content": "Explain async/await in Python"}
|
||||
]
|
||||
)
|
||||
print(message.content[0].text)
|
||||
```
|
||||
|
||||
### Streaming
|
||||
|
||||
```python
|
||||
with client.messages.stream(
|
||||
model="claude-sonnet-4-0",
|
||||
max_tokens=1024,
|
||||
messages=[{"role": "user", "content": "Write a haiku about coding"}]
|
||||
) as stream:
|
||||
for text in stream.text_stream:
|
||||
print(text, end="", flush=True)
|
||||
```
|
||||
|
||||
### System Prompt
|
||||
|
||||
```python
|
||||
message = client.messages.create(
|
||||
model="claude-sonnet-4-0",
|
||||
max_tokens=1024,
|
||||
system="You are a senior Python developer. Be concise.",
|
||||
messages=[{"role": "user", "content": "Review this function"}]
|
||||
)
|
||||
```
|
||||
|
||||
## TypeScript SDK
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
npm install @anthropic-ai/sdk
|
||||
```
|
||||
|
||||
### Basic Message
|
||||
|
||||
```typescript
|
||||
import Anthropic from "@anthropic-ai/sdk";
|
||||
|
||||
const client = new Anthropic(); // reads ANTHROPIC_API_KEY from env
|
||||
|
||||
const message = await client.messages.create({
|
||||
model: "claude-sonnet-4-0",
|
||||
max_tokens: 1024,
|
||||
messages: [
|
||||
{ role: "user", content: "Explain async/await in TypeScript" }
|
||||
],
|
||||
});
|
||||
console.log(message.content[0].text);
|
||||
```
|
||||
|
||||
### Streaming
|
||||
|
||||
```typescript
|
||||
const stream = client.messages.stream({
|
||||
model: "claude-sonnet-4-0",
|
||||
max_tokens: 1024,
|
||||
messages: [{ role: "user", content: "Write a haiku" }],
|
||||
});
|
||||
|
||||
for await (const event of stream) {
|
||||
if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
|
||||
process.stdout.write(event.delta.text);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Tool Use
|
||||
|
||||
Define tools and let Claude call them:
|
||||
|
||||
```python
|
||||
tools = [
|
||||
{
|
||||
"name": "get_weather",
|
||||
"description": "Get current weather for a location",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"location": {"type": "string", "description": "City name"},
|
||||
"unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
|
||||
},
|
||||
"required": ["location"]
|
||||
}
|
||||
}
|
||||
]
|
||||
|
||||
message = client.messages.create(
|
||||
model="claude-sonnet-4-0",
|
||||
max_tokens=1024,
|
||||
tools=tools,
|
||||
messages=[{"role": "user", "content": "What's the weather in SF?"}]
|
||||
)
|
||||
|
||||
# Handle tool use response
|
||||
for block in message.content:
|
||||
if block.type == "tool_use":
|
||||
# Execute the tool with block.input
|
||||
result = get_weather(**block.input)
|
||||
# Send result back
|
||||
follow_up = client.messages.create(
|
||||
model="claude-sonnet-4-0",
|
||||
max_tokens=1024,
|
||||
tools=tools,
|
||||
messages=[
|
||||
{"role": "user", "content": "What's the weather in SF?"},
|
||||
{"role": "assistant", "content": message.content},
|
||||
{"role": "user", "content": [
|
||||
{"type": "tool_result", "tool_use_id": block.id, "content": str(result)}
|
||||
]}
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
## Vision
|
||||
|
||||
Send images for analysis:
|
||||
|
||||
```python
|
||||
import base64
|
||||
|
||||
with open("diagram.png", "rb") as f:
|
||||
image_data = base64.standard_b64encode(f.read()).decode("utf-8")
|
||||
|
||||
message = client.messages.create(
|
||||
model="claude-sonnet-4-0",
|
||||
max_tokens=1024,
|
||||
messages=[{
|
||||
"role": "user",
|
||||
"content": [
|
||||
{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": image_data}},
|
||||
{"type": "text", "text": "Describe this diagram"}
|
||||
]
|
||||
}]
|
||||
)
|
||||
```
|
||||
|
||||
## Extended Thinking
|
||||
|
||||
For complex reasoning tasks:
|
||||
|
||||
```python
|
||||
message = client.messages.create(
|
||||
model="claude-sonnet-4-0",
|
||||
max_tokens=16000,
|
||||
thinking={
|
||||
"type": "enabled",
|
||||
"budget_tokens": 10000
|
||||
},
|
||||
messages=[{"role": "user", "content": "Solve this math problem step by step..."}]
|
||||
)
|
||||
|
||||
for block in message.content:
|
||||
if block.type == "thinking":
|
||||
print(f"Thinking: {block.thinking}")
|
||||
elif block.type == "text":
|
||||
print(f"Answer: {block.text}")
|
||||
```
|
||||
|
||||
## Prompt Caching
|
||||
|
||||
Cache large system prompts or context to reduce costs:
|
||||
|
||||
```python
|
||||
message = client.messages.create(
|
||||
model="claude-sonnet-4-0",
|
||||
max_tokens=1024,
|
||||
system=[
|
||||
{"type": "text", "text": large_system_prompt, "cache_control": {"type": "ephemeral"}}
|
||||
],
|
||||
messages=[{"role": "user", "content": "Question about the cached context"}]
|
||||
)
|
||||
# Check cache usage
|
||||
print(f"Cache read: {message.usage.cache_read_input_tokens}")
|
||||
print(f"Cache creation: {message.usage.cache_creation_input_tokens}")
|
||||
```
|
||||
|
||||
## Batches API
|
||||
|
||||
Process large volumes asynchronously at 50% cost reduction:
|
||||
|
||||
```python
|
||||
import time
|
||||
|
||||
batch = client.messages.batches.create(
|
||||
requests=[
|
||||
{
|
||||
"custom_id": f"request-{i}",
|
||||
"params": {
|
||||
"model": "claude-sonnet-4-0",
|
||||
"max_tokens": 1024,
|
||||
"messages": [{"role": "user", "content": prompt}]
|
||||
}
|
||||
}
|
||||
for i, prompt in enumerate(prompts)
|
||||
]
|
||||
)
|
||||
|
||||
# Poll for completion
|
||||
while True:
|
||||
status = client.messages.batches.retrieve(batch.id)
|
||||
if status.processing_status == "ended":
|
||||
break
|
||||
time.sleep(30)
|
||||
|
||||
# Get results
|
||||
for result in client.messages.batches.results(batch.id):
|
||||
print(result.result.message.content[0].text)
|
||||
```
|
||||
|
||||
## Claude Agent SDK
|
||||
|
||||
Build multi-step agents:
|
||||
|
||||
```python
|
||||
# Note: Agent SDK API surface may change — check official docs
|
||||
import anthropic
|
||||
|
||||
# Define tools as functions
|
||||
tools = [{
|
||||
"name": "search_codebase",
|
||||
"description": "Search the codebase for relevant code",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {"query": {"type": "string"}},
|
||||
"required": ["query"]
|
||||
}
|
||||
}]
|
||||
|
||||
# Run an agentic loop with tool use
|
||||
client = anthropic.Anthropic()
|
||||
messages = [{"role": "user", "content": "Review the auth module for security issues"}]
|
||||
|
||||
while True:
|
||||
response = client.messages.create(
|
||||
model="claude-sonnet-4-0",
|
||||
max_tokens=4096,
|
||||
tools=tools,
|
||||
messages=messages,
|
||||
)
|
||||
if response.stop_reason == "end_turn":
|
||||
break
|
||||
# Handle tool calls and continue the loop
|
||||
messages.append({"role": "assistant", "content": response.content})
|
||||
# ... execute tools and append tool_result messages
|
||||
```
|
||||
|
||||
## Cost Optimization
|
||||
|
||||
| Strategy | Savings | When to Use |
|
||||
|----------|---------|-------------|
|
||||
| Prompt caching | Up to 90% on cached tokens | Repeated system prompts or context |
|
||||
| Batches API | 50% | Non-time-sensitive bulk processing |
|
||||
| Haiku instead of Sonnet | ~75% | Simple tasks, classification, extraction |
|
||||
| Shorter max_tokens | Variable | When you know output will be short |
|
||||
| Streaming | None (same cost) | Better UX, same price |
|
||||
|
||||
## Error Handling
|
||||
|
||||
```python
|
||||
import time
|
||||
|
||||
from anthropic import APIError, RateLimitError, APIConnectionError
|
||||
|
||||
try:
|
||||
message = client.messages.create(...)
|
||||
except RateLimitError:
|
||||
# Back off and retry
|
||||
time.sleep(60)
|
||||
except APIConnectionError:
|
||||
# Network issue, retry with backoff
|
||||
pass
|
||||
except APIError as e:
|
||||
print(f"API error {e.status_code}: {e.message}")
|
||||
```
|
||||
|
||||
## Environment Setup
|
||||
|
||||
```bash
|
||||
# Required
|
||||
export ANTHROPIC_API_KEY="your-api-key-here"
|
||||
|
||||
# Optional: set default model
|
||||
export ANTHROPIC_MODEL="claude-sonnet-4-0"
|
||||
```
|
||||
|
||||
Never hardcode API keys. Always use environment variables.
|
||||
@@ -82,7 +82,7 @@ If the user chooses niche or core + niche, continue to category selection below
|
||||
|
||||
### 2b: Choose Skill Categories
|
||||
|
||||
There are 27 skills organized into 4 categories. Use `AskUserQuestion` with `multiSelect: true`:
|
||||
There are 41 skills organized into 8 categories. Use `AskUserQuestion` with `multiSelect: true`:
|
||||
|
||||
```
|
||||
Question: "Which skill categories do you want to install?"
|
||||
@@ -90,6 +90,11 @@ Options:
|
||||
- "Framework & Language" — "Django, Spring Boot, Go, Python, Java, Frontend, Backend patterns"
|
||||
- "Database" — "PostgreSQL, ClickHouse, JPA/Hibernate patterns"
|
||||
- "Workflow & Quality" — "TDD, verification, learning, security review, compaction"
|
||||
- "Business & Content" — "Article writing, content engine, market research, investor materials, outreach"
|
||||
- "Research & APIs" — "Deep research, Exa search, Claude API patterns"
|
||||
- "Social & Content Distribution" — "X/Twitter API, crossposting alongside content-engine"
|
||||
- "Media Generation" — "fal.ai image/video/audio alongside VideoDB"
|
||||
- "Orchestration" — "dmux multi-agent workflows"
|
||||
- "All skills" — "Install every available skill"
|
||||
```
|
||||
|
||||
@@ -150,6 +155,34 @@ For each selected category, print the full list of skills below and ask the user
|
||||
| `investor-materials` | Pitch decks, one-pagers, investor memos, and financial models |
|
||||
| `investor-outreach` | Personalized investor cold emails, warm intros, and follow-ups |
|
||||
|
||||
**Category: Research & APIs (3 skills)**
|
||||
|
||||
| Skill | Description |
|
||||
|-------|-------------|
|
||||
| `deep-research` | Multi-source deep research using firecrawl and exa MCPs with cited reports |
|
||||
| `exa-search` | Neural search via Exa MCP for web, code, company, and people research |
|
||||
| `claude-api` | Anthropic Claude API patterns: Messages, streaming, tool use, vision, batches, Agent SDK |
|
||||
|
||||
**Category: Social & Content Distribution (2 skills)**
|
||||
|
||||
| Skill | Description |
|
||||
|-------|-------------|
|
||||
| `x-api` | X/Twitter API integration for posting, threads, search, and analytics |
|
||||
| `crosspost` | Multi-platform content distribution with platform-native adaptation |
|
||||
|
||||
**Category: Media Generation (2 skills)**
|
||||
|
||||
| Skill | Description |
|
||||
|-------|-------------|
|
||||
| `fal-ai-media` | Unified AI media generation (image, video, audio) via fal.ai MCP |
|
||||
| `video-editing` | AI-assisted video editing for cutting, structuring, and augmenting real footage |
|
||||
|
||||
**Category: Orchestration (1 skill)**
|
||||
|
||||
| Skill | Description |
|
||||
|-------|-------------|
|
||||
| `dmux-workflows` | Multi-agent orchestration using dmux for parallel agent sessions |
|
||||
|
||||
**Standalone**
|
||||
|
||||
| Skill | Description |
|
||||
@@ -230,6 +263,10 @@ Some skills reference others. Verify these dependencies:
|
||||
- `continuous-learning-v2` references `~/.claude/homunculus/` directory
|
||||
- `python-testing` may reference `python-patterns`
|
||||
- `golang-testing` may reference `golang-patterns`
|
||||
- `crosspost` references `content-engine` and `x-api`
|
||||
- `deep-research` references `exa-search` (complementary MCP tools)
|
||||
- `fal-ai-media` references `videodb` (complementary media skill)
|
||||
- `x-api` references `content-engine` and `crosspost`
|
||||
- Language-specific rules reference `common/` counterparts
|
||||
|
||||
### 4d: Report Issues
|
||||
|
||||
@@ -38,6 +38,12 @@ analyze_observations() {
|
||||
return
|
||||
fi
|
||||
|
||||
# session-guardian: gate observer cycle (active hours, cooldown, idle detection)
|
||||
if ! bash "$(dirname "$0")/session-guardian.sh"; then
|
||||
echo "[$(date)] Observer cycle skipped by session-guardian" >> "$LOG_FILE"
|
||||
return
|
||||
fi
|
||||
|
||||
prompt_file="$(mktemp "${TMPDIR:-/tmp}/ecc-observer-prompt.XXXXXX")"
|
||||
cat > "$prompt_file" <<PROMPT
|
||||
Read ${OBSERVATIONS_FILE} and identify patterns for the project ${PROJECT_NAME} (user corrections, error resolutions, repeated workflows, tool preferences).
|
||||
@@ -91,7 +97,8 @@ PROMPT
|
||||
max_turns=10
|
||||
fi
|
||||
|
||||
claude --model haiku --max-turns "$max_turns" --print < "$prompt_file" >> "$LOG_FILE" 2>&1 &
|
||||
# Prevent observe.sh from recording this automated Haiku session as observations
|
||||
ECC_SKIP_OBSERVE=1 ECC_HOOK_PROFILE=minimal claude --model haiku --max-turns "$max_turns" --print < "$prompt_file" >> "$LOG_FILE" 2>&1 &
|
||||
claude_pid=$!
|
||||
|
||||
(
|
||||
|
||||
150
skills/continuous-learning-v2/agents/session-guardian.sh
Executable file
150
skills/continuous-learning-v2/agents/session-guardian.sh
Executable file
@@ -0,0 +1,150 @@
|
||||
#!/usr/bin/env bash
|
||||
# session-guardian.sh — Observer session guard
|
||||
# Exit 0 = proceed. Exit 1 = skip this observer cycle.
|
||||
# Called by observer-loop.sh before spawning any Claude session.
|
||||
#
|
||||
# Config (env vars, all optional):
|
||||
# OBSERVER_INTERVAL_SECONDS default: 300 (per-project cooldown)
|
||||
# OBSERVER_LAST_RUN_LOG default: ~/.claude/observer-last-run.log
|
||||
# OBSERVER_ACTIVE_HOURS_START default: 800 (8:00 AM local, set to 0 to disable)
|
||||
# OBSERVER_ACTIVE_HOURS_END default: 2300 (11:00 PM local, set to 0 to disable)
|
||||
# OBSERVER_MAX_IDLE_SECONDS default: 1800 (30 min; set to 0 to disable)
|
||||
#
|
||||
# Gate execution order (cheapest first):
|
||||
# Gate 1: Time window check (~0ms, string comparison)
|
||||
# Gate 2: Project cooldown log (~1ms, file read + mkdir lock)
|
||||
# Gate 3: Idle detection (~5-50ms, OS syscall; fail open)
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
INTERVAL="${OBSERVER_INTERVAL_SECONDS:-300}"
|
||||
LOG_PATH="${OBSERVER_LAST_RUN_LOG:-$HOME/.claude/observer-last-run.log}"
|
||||
ACTIVE_START="${OBSERVER_ACTIVE_HOURS_START:-800}"
|
||||
ACTIVE_END="${OBSERVER_ACTIVE_HOURS_END:-2300}"
|
||||
MAX_IDLE="${OBSERVER_MAX_IDLE_SECONDS:-1800}"
|
||||
|
||||
# ── Gate 1: Time Window ───────────────────────────────────────────────────────
|
||||
# Skip observer cycles outside configured active hours (local system time).
|
||||
# Uses HHMM integer comparison. Works on BSD date (macOS) and GNU date (Linux).
|
||||
# Supports overnight windows such as 2200-0600.
|
||||
# Set both ACTIVE_START and ACTIVE_END to 0 to disable this gate.
|
||||
if [ "$ACTIVE_START" -ne 0 ] || [ "$ACTIVE_END" -ne 0 ]; then
|
||||
current_hhmm=$(date +%k%M | tr -d ' ')
|
||||
current_hhmm_num=$(( 10#${current_hhmm:-0} ))
|
||||
active_start_num=$(( 10#${ACTIVE_START:-800} ))
|
||||
active_end_num=$(( 10#${ACTIVE_END:-2300} ))
|
||||
|
||||
within_active_hours=0
|
||||
if [ "$active_start_num" -lt "$active_end_num" ]; then
|
||||
if [ "$current_hhmm_num" -ge "$active_start_num" ] && [ "$current_hhmm_num" -lt "$active_end_num" ]; then
|
||||
within_active_hours=1
|
||||
fi
|
||||
else
|
||||
if [ "$current_hhmm_num" -ge "$active_start_num" ] || [ "$current_hhmm_num" -lt "$active_end_num" ]; then
|
||||
within_active_hours=1
|
||||
fi
|
||||
fi
|
||||
|
||||
if [ "$within_active_hours" -ne 1 ]; then
|
||||
echo "session-guardian: outside active hours (${current_hhmm}, window ${ACTIVE_START}-${ACTIVE_END})" >&2
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
|
||||
# ── Gate 2: Project Cooldown Log ─────────────────────────────────────────────
|
||||
# Prevent the same project being observed faster than OBSERVER_INTERVAL_SECONDS.
|
||||
# Key: PROJECT_DIR when provided by the observer, otherwise git root path.
|
||||
# Uses mkdir-based lock for safe concurrent access. Skips the cycle on lock contention.
|
||||
# stderr uses basename only — never prints the full absolute path.
|
||||
|
||||
project_root="${PROJECT_DIR:-}"
|
||||
if [ -z "$project_root" ] || [ ! -d "$project_root" ]; then
|
||||
project_root="$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")"
|
||||
fi
|
||||
project_name="$(basename "$project_root")"
|
||||
now="$(date +%s)"
|
||||
|
||||
mkdir -p "$(dirname "$LOG_PATH")" || {
|
||||
echo "session-guardian: cannot create log dir, proceeding" >&2
|
||||
exit 0
|
||||
}
|
||||
|
||||
_lock_dir="${LOG_PATH}.lock"
|
||||
if ! mkdir "$_lock_dir" 2>/dev/null; then
|
||||
# Another observer holds the lock — skip this cycle to avoid double-spawns
|
||||
echo "session-guardian: log locked by concurrent process, skipping cycle" >&2
|
||||
exit 1
|
||||
else
|
||||
trap 'rm -rf "$_lock_dir"' EXIT INT TERM
|
||||
|
||||
last_spawn=0
|
||||
last_spawn=$(awk -F '\t' -v key="$project_root" '$1 == key { value = $2 } END { if (value != "") print value }' "$LOG_PATH" 2>/dev/null) || true
|
||||
last_spawn="${last_spawn:-0}"
|
||||
[[ "$last_spawn" =~ ^[0-9]+$ ]] || last_spawn=0
|
||||
|
||||
elapsed=$(( now - last_spawn ))
|
||||
if [ "$elapsed" -lt "$INTERVAL" ]; then
|
||||
rm -rf "$_lock_dir"
|
||||
trap - EXIT INT TERM
|
||||
echo "session-guardian: cooldown active for '${project_name}' (last spawn ${elapsed}s ago, interval ${INTERVAL}s)" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Update log: remove old entry for this project, append new timestamp (tab-delimited)
|
||||
tmp_log="$(mktemp "$(dirname "$LOG_PATH")/observer-last-run.XXXXXX")"
|
||||
awk -F '\t' -v key="$project_root" '$1 != key' "$LOG_PATH" > "$tmp_log" 2>/dev/null || true
|
||||
printf '%s\t%s\n' "$project_root" "$now" >> "$tmp_log"
|
||||
mv "$tmp_log" "$LOG_PATH"
|
||||
|
||||
rm -rf "$_lock_dir"
|
||||
trap - EXIT INT TERM
|
||||
fi
|
||||
|
||||
# ── Gate 3: Idle Detection ────────────────────────────────────────────────────
|
||||
# Skip cycles when no user input received for too long. Fail open if idle time
|
||||
# cannot be determined (Linux without xprintidle, headless, unknown OS).
|
||||
# Set OBSERVER_MAX_IDLE_SECONDS=0 to disable this gate.
|
||||
|
||||
get_idle_seconds() {
|
||||
local _raw
|
||||
case "$(uname -s)" in
|
||||
Darwin)
|
||||
_raw=$( { /usr/sbin/ioreg -c IOHIDSystem \
|
||||
| /usr/bin/awk '/HIDIdleTime/ {print int($NF/1000000000); exit}'; } \
|
||||
2>/dev/null ) || true
|
||||
printf '%s\n' "${_raw:-0}" | head -n1
|
||||
;;
|
||||
Linux)
|
||||
if command -v xprintidle >/dev/null 2>&1; then
|
||||
_raw=$(xprintidle 2>/dev/null) || true
|
||||
echo $(( ${_raw:-0} / 1000 ))
|
||||
else
|
||||
echo 0 # fail open: xprintidle not installed
|
||||
fi
|
||||
;;
|
||||
*MINGW*|*MSYS*|*CYGWIN*)
|
||||
_raw=$(powershell.exe -NoProfile -NonInteractive -Command \
|
||||
"try { \
|
||||
Add-Type -MemberDefinition '[DllImport(\"user32.dll\")] public static extern bool GetLastInputInfo(ref LASTINPUTINFO p); [StructLayout(LayoutKind.Sequential)] public struct LASTINPUTINFO { public uint cbSize; public int dwTime; }' -Name WinAPI -Namespace PInvoke; \
|
||||
\$l = New-Object PInvoke.WinAPI+LASTINPUTINFO; \$l.cbSize = 8; \
|
||||
[PInvoke.WinAPI]::GetLastInputInfo([ref]\$l) | Out-Null; \
|
||||
[int][Math]::Max(0, [long]([Environment]::TickCount - [long]\$l.dwTime) / 1000) \
|
||||
} catch { 0 }" \
|
||||
2>/dev/null | tr -d '\r') || true
|
||||
printf '%s\n' "${_raw:-0}" | head -n1
|
||||
;;
|
||||
*)
|
||||
echo 0 # fail open: unknown platform
|
||||
;;
|
||||
esac
|
||||
}
|
||||
|
||||
if [ "$MAX_IDLE" -gt 0 ]; then
|
||||
idle_seconds=$(get_idle_seconds)
|
||||
if [ "$idle_seconds" -gt "$MAX_IDLE" ]; then
|
||||
echo "session-guardian: user idle ${idle_seconds}s (threshold ${MAX_IDLE}s), skipping" >&2
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
|
||||
exit 0
|
||||
@@ -113,8 +113,56 @@ if [ -f "$CONFIG_DIR/disabled" ]; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# FIX: Skip if a previous run already aborted due to confirmation/permission prompt
|
||||
# This is the circuit-breaker — stops retrying after a non-interactive failure
|
||||
# ─────────────────────────────────────────────
|
||||
# Automated session guards
|
||||
# Prevents observe.sh from firing on non-human sessions to avoid:
|
||||
# - ECC observing its own Haiku observer sessions (self-loop)
|
||||
# - ECC observing other tools' automated sessions (e.g. claude-mem)
|
||||
# - All-night Haiku usage with no human activity
|
||||
# ─────────────────────────────────────────────
|
||||
|
||||
# Env-var checks first (cheapest — no subprocess spawning):
|
||||
|
||||
# Layer 1: CLAUDE_CODE_ENTRYPOINT — set by Claude Code itself to indicate how
|
||||
# it was invoked. Only interactive terminal sessions should continue; treat any
|
||||
# explicit non-cli entrypoint as automated so future entrypoint types fail closed
|
||||
# without requiring updates here.
|
||||
case "${CLAUDE_CODE_ENTRYPOINT:-cli}" in
|
||||
cli) ;;
|
||||
*) exit 0 ;;
|
||||
esac
|
||||
|
||||
# Layer 2: Respect ECC_HOOK_PROFILE=minimal — suppresses non-essential hooks
|
||||
[ "${ECC_HOOK_PROFILE:-standard}" = "minimal" ] && exit 0
|
||||
|
||||
# Layer 3: Cooperative skip env var — tools like claude-mem can set this
|
||||
# (export ECC_SKIP_OBSERVE=1) before spawning their automated sessions
|
||||
[ "${ECC_SKIP_OBSERVE:-0}" = "1" ] && exit 0
|
||||
|
||||
# Layer 4: Skip subagent sessions — agent_id is only present when a hook fires
|
||||
# inside a subagent (automated by definition, never a human interactive session).
|
||||
# Placed after env-var checks to avoid a Python subprocess on sessions that
|
||||
# already exit via Layers 1-3.
|
||||
_ECC_AGENT_ID=$(echo "$INPUT_JSON" | "$PYTHON_CMD" -c "import json,sys; print(json.load(sys.stdin).get('agent_id',''))" 2>/dev/null || true)
|
||||
[ -n "$_ECC_AGENT_ID" ] && exit 0
|
||||
|
||||
# Layer 5: CWD path exclusions — skip known observer-session directories.
|
||||
# Add custom paths via ECC_OBSERVE_SKIP_PATHS (comma-separated substrings).
|
||||
# Whitespace is trimmed from each pattern; empty patterns are skipped to
|
||||
# prevent an empty-string glob from matching every path.
|
||||
_ECC_SKIP_PATHS="${ECC_OBSERVE_SKIP_PATHS:-observer-sessions,.claude-mem}"
|
||||
if [ -n "$STDIN_CWD" ]; then
|
||||
IFS=',' read -ra _ECC_SKIP_ARRAY <<< "$_ECC_SKIP_PATHS"
|
||||
for _pattern in "${_ECC_SKIP_ARRAY[@]}"; do
|
||||
_pattern="${_pattern#"${_pattern%%[![:space:]]*}"}" # trim leading whitespace
|
||||
_pattern="${_pattern%"${_pattern##*[![:space:]]}"}" # trim trailing whitespace
|
||||
[ -z "$_pattern" ] && continue
|
||||
case "$STDIN_CWD" in *"$_pattern"*) exit 0 ;; esac
|
||||
done
|
||||
fi
|
||||
|
||||
# Skip if a previous run already aborted due to confirmation/permission prompt.
|
||||
# This is the circuit-breaker — stops retrying after a non-interactive failure.
|
||||
if [ -f "$SENTINEL_FILE" ]; then
|
||||
echo "[observe] Skipping: previous run aborted due to confirmation/permission prompt. Remove ${SENTINEL_FILE} to re-enable." >&2
|
||||
exit 0
|
||||
|
||||
192
skills/crosspost/SKILL.md
Normal file
192
skills/crosspost/SKILL.md
Normal file
@@ -0,0 +1,192 @@
|
||||
---
|
||||
name: crosspost
|
||||
description: Multi-platform content distribution across X, LinkedIn, Threads, and Bluesky. Adapts content per platform using content-engine patterns. Never posts identical content cross-platform. Use when the user wants to distribute content across social platforms.
|
||||
origin: ECC
|
||||
---
|
||||
|
||||
# Crosspost
|
||||
|
||||
Distribute content across multiple social platforms with platform-native adaptation.
|
||||
|
||||
## When to Use
|
||||
|
||||
- User wants to post content to multiple platforms
|
||||
- Publishing announcements, launches, or updates across social media
|
||||
- Repurposing a post from one platform to others
|
||||
- User says "crosspost", "post everywhere", "share on all platforms", or "distribute this"
|
||||
|
||||
## How It Works
|
||||
|
||||
### Core Rules
|
||||
|
||||
1. **Never post identical content cross-platform.** Each platform gets a native adaptation.
|
||||
2. **Primary platform first.** Post to the main platform, then adapt for others.
|
||||
3. **Respect platform conventions.** Length limits, formatting, link handling all differ.
|
||||
4. **One idea per post.** If the source content has multiple ideas, split across posts.
|
||||
5. **Attribution matters.** If crossposting someone else's content, credit the source.
|
||||
|
||||
### Platform Specifications
|
||||
|
||||
| Platform | Max Length | Link Handling | Hashtags | Media |
|
||||
|----------|-----------|---------------|----------|-------|
|
||||
| X | 280 chars (4000 for Premium) | Counted in length | Minimal (1-2 max) | Images, video, GIFs |
|
||||
| LinkedIn | 3000 chars | Not counted in length | 3-5 relevant | Images, video, docs, carousels |
|
||||
| Threads | 500 chars | Separate link attachment | None typical | Images, video |
|
||||
| Bluesky | 300 chars | Via facets (rich text) | None (use feeds) | Images |
|
||||
|
||||
### Workflow
|
||||
|
||||
### Step 1: Create Source Content
|
||||
|
||||
Start with the core idea. Use `content-engine` skill for high-quality drafts:
|
||||
- Identify the single core message
|
||||
- Determine the primary platform (where the audience is biggest)
|
||||
- Draft the primary platform version first
|
||||
|
||||
### Step 2: Identify Target Platforms
|
||||
|
||||
Ask the user or determine from context:
|
||||
- Which platforms to target
|
||||
- Priority order (primary gets the best version)
|
||||
- Any platform-specific requirements (e.g., LinkedIn needs professional tone)
|
||||
|
||||
### Step 3: Adapt Per Platform
|
||||
|
||||
For each target platform, transform the content:
|
||||
|
||||
**X adaptation:**
|
||||
- Open with a hook, not a summary
|
||||
- Cut to the core insight fast
|
||||
- Keep links out of main body when possible
|
||||
- Use thread format for longer content
|
||||
|
||||
**LinkedIn adaptation:**
|
||||
- Strong first line (visible before "see more")
|
||||
- Short paragraphs with line breaks
|
||||
- Frame around lessons, results, or professional takeaways
|
||||
- More explicit context than X (LinkedIn audience needs framing)
|
||||
|
||||
**Threads adaptation:**
|
||||
- Conversational, casual tone
|
||||
- Shorter than LinkedIn, less compressed than X
|
||||
- Visual-first if possible
|
||||
|
||||
**Bluesky adaptation:**
|
||||
- Direct and concise (300 char limit)
|
||||
- Community-oriented tone
|
||||
- Use feeds/lists for topic targeting instead of hashtags
|
||||
|
||||
### Step 4: Post Primary Platform
|
||||
|
||||
Post to the primary platform first:
|
||||
- Use `x-api` skill for X
|
||||
- Use platform-specific APIs or tools for others
|
||||
- Capture the post URL for cross-referencing
|
||||
|
||||
### Step 5: Post to Secondary Platforms
|
||||
|
||||
Post adapted versions to remaining platforms:
|
||||
- Stagger timing (not all at once — 30-60 min gaps)
|
||||
- Include cross-platform references where appropriate ("longer thread on X" etc.)
|
||||
|
||||
## Examples
|
||||
|
||||
### Source: Product Launch
|
||||
|
||||
**X version:**
|
||||
```
|
||||
We just shipped [feature].
|
||||
|
||||
[One specific thing it does that's impressive]
|
||||
|
||||
[Link]
|
||||
```
|
||||
|
||||
**LinkedIn version:**
|
||||
```
|
||||
Excited to share: we just launched [feature] at [Company].
|
||||
|
||||
Here's why it matters:
|
||||
|
||||
[2-3 short paragraphs with context]
|
||||
|
||||
[Takeaway for the audience]
|
||||
|
||||
[Link]
|
||||
```
|
||||
|
||||
**Threads version:**
|
||||
```
|
||||
just shipped something cool — [feature]
|
||||
|
||||
[casual explanation of what it does]
|
||||
|
||||
link in bio
|
||||
```
|
||||
|
||||
### Source: Technical Insight
|
||||
|
||||
**X version:**
|
||||
```
|
||||
TIL: [specific technical insight]
|
||||
|
||||
[Why it matters in one sentence]
|
||||
```
|
||||
|
||||
**LinkedIn version:**
|
||||
```
|
||||
A pattern I've been using that's made a real difference:
|
||||
|
||||
[Technical insight with professional framing]
|
||||
|
||||
[How it applies to teams/orgs]
|
||||
|
||||
#relevantHashtag
|
||||
```
|
||||
|
||||
## API Integration
|
||||
|
||||
### Batch Crossposting Service (Example Pattern)
|
||||
If using a crossposting service (e.g., Postbridge, Buffer, or a custom API), the pattern looks like:
|
||||
|
||||
```python
|
||||
import os
|
||||
import requests
|
||||
|
||||
resp = requests.post(
|
||||
"https://your-crosspost-service.example/api/posts",
|
||||
headers={"Authorization": f"Bearer {os.environ['POSTBRIDGE_API_KEY']}"},
|
||||
json={
|
||||
"platforms": ["twitter", "linkedin", "threads"],
|
||||
"content": {
|
||||
"twitter": {"text": x_version},
|
||||
"linkedin": {"text": linkedin_version},
|
||||
"threads": {"text": threads_version}
|
||||
}
|
||||
},
|
||||
timeout=30
|
||||
)
|
||||
resp.raise_for_status()
|
||||
```
|
||||
|
||||
### Manual Posting
|
||||
Without Postbridge, post to each platform using its native API:
|
||||
- X: Use `x-api` skill patterns
|
||||
- LinkedIn: LinkedIn API v2 with OAuth 2.0
|
||||
- Threads: Threads API (Meta)
|
||||
- Bluesky: AT Protocol API
|
||||
|
||||
## Quality Gate
|
||||
|
||||
Before posting:
|
||||
- [ ] Each platform version reads naturally for that platform
|
||||
- [ ] No identical content across platforms
|
||||
- [ ] Length limits respected
|
||||
- [ ] Links work and are placed appropriately
|
||||
- [ ] Tone matches platform conventions
|
||||
- [ ] Media is sized correctly for each platform
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `content-engine` — Generate platform-native content
|
||||
- `x-api` — X/Twitter API integration
|
||||
155
skills/deep-research/SKILL.md
Normal file
155
skills/deep-research/SKILL.md
Normal file
@@ -0,0 +1,155 @@
|
||||
---
|
||||
name: deep-research
|
||||
description: Multi-source deep research using firecrawl and exa MCPs. Searches the web, synthesizes findings, and delivers cited reports with source attribution. Use when the user wants thorough research on any topic with evidence and citations.
|
||||
origin: ECC
|
||||
---
|
||||
|
||||
# Deep Research
|
||||
|
||||
Produce thorough, cited research reports from multiple web sources using firecrawl and exa MCP tools.
|
||||
|
||||
## When to Activate
|
||||
|
||||
- User asks to research any topic in depth
|
||||
- Competitive analysis, technology evaluation, or market sizing
|
||||
- Due diligence on companies, investors, or technologies
|
||||
- Any question requiring synthesis from multiple sources
|
||||
- User says "research", "deep dive", "investigate", or "what's the current state of"
|
||||
|
||||
## MCP Requirements
|
||||
|
||||
At least one of:
|
||||
- **firecrawl** — `firecrawl_search`, `firecrawl_scrape`, `firecrawl_crawl`
|
||||
- **exa** — `web_search_exa`, `web_search_advanced_exa`, `crawling_exa`
|
||||
|
||||
Both together give the best coverage. Configure in `~/.claude.json` or `~/.codex/config.toml`.
|
||||
|
||||
## Workflow
|
||||
|
||||
### Step 1: Understand the Goal
|
||||
|
||||
Ask 1-2 quick clarifying questions:
|
||||
- "What's your goal — learning, making a decision, or writing something?"
|
||||
- "Any specific angle or depth you want?"
|
||||
|
||||
If the user says "just research it" — skip ahead with reasonable defaults.
|
||||
|
||||
### Step 2: Plan the Research
|
||||
|
||||
Break the topic into 3-5 research sub-questions. Example:
|
||||
- Topic: "Impact of AI on healthcare"
|
||||
- What are the main AI applications in healthcare today?
|
||||
- What clinical outcomes have been measured?
|
||||
- What are the regulatory challenges?
|
||||
- What companies are leading this space?
|
||||
- What's the market size and growth trajectory?
|
||||
|
||||
### Step 3: Execute Multi-Source Search
|
||||
|
||||
For EACH sub-question, search using available MCP tools:
|
||||
|
||||
**With firecrawl:**
|
||||
```
|
||||
firecrawl_search(query: "<sub-question keywords>", limit: 8)
|
||||
```
|
||||
|
||||
**With exa:**
|
||||
```
|
||||
web_search_exa(query: "<sub-question keywords>", numResults: 8)
|
||||
web_search_advanced_exa(query: "<keywords>", numResults: 5, startPublishedDate: "2025-01-01")
|
||||
```
|
||||
|
||||
**Search strategy:**
|
||||
- Use 2-3 different keyword variations per sub-question
|
||||
- Mix general and news-focused queries
|
||||
- Aim for 15-30 unique sources total
|
||||
- Prioritize: academic, official, reputable news > blogs > forums
|
||||
|
||||
### Step 4: Deep-Read Key Sources
|
||||
|
||||
For the most promising URLs, fetch full content:
|
||||
|
||||
**With firecrawl:**
|
||||
```
|
||||
firecrawl_scrape(url: "<url>")
|
||||
```
|
||||
|
||||
**With exa:**
|
||||
```
|
||||
crawling_exa(url: "<url>", tokensNum: 5000)
|
||||
```
|
||||
|
||||
Read 3-5 key sources in full for depth. Do not rely only on search snippets.
|
||||
|
||||
### Step 5: Synthesize and Write Report
|
||||
|
||||
Structure the report:
|
||||
|
||||
```markdown
|
||||
# [Topic]: Research Report
|
||||
*Generated: [date] | Sources: [N] | Confidence: [High/Medium/Low]*
|
||||
|
||||
## Executive Summary
|
||||
[3-5 sentence overview of key findings]
|
||||
|
||||
## 1. [First Major Theme]
|
||||
[Findings with inline citations]
|
||||
- Key point ([Source Name](url))
|
||||
- Supporting data ([Source Name](url))
|
||||
|
||||
## 2. [Second Major Theme]
|
||||
...
|
||||
|
||||
## 3. [Third Major Theme]
|
||||
...
|
||||
|
||||
## Key Takeaways
|
||||
- [Actionable insight 1]
|
||||
- [Actionable insight 2]
|
||||
- [Actionable insight 3]
|
||||
|
||||
## Sources
|
||||
1. [Title](url) — [one-line summary]
|
||||
2. ...
|
||||
|
||||
## Methodology
|
||||
Searched [N] queries across web and news. Analyzed [M] sources.
|
||||
Sub-questions investigated: [list]
|
||||
```
|
||||
|
||||
### Step 6: Deliver
|
||||
|
||||
- **Short topics**: Post the full report in chat
|
||||
- **Long reports**: Post the executive summary + key takeaways, save full report to a file
|
||||
|
||||
## Parallel Research with Subagents
|
||||
|
||||
For broad topics, use Claude Code's Task tool to parallelize:
|
||||
|
||||
```
|
||||
Launch 3 research agents in parallel:
|
||||
1. Agent 1: Research sub-questions 1-2
|
||||
2. Agent 2: Research sub-questions 3-4
|
||||
3. Agent 3: Research sub-question 5 + cross-cutting themes
|
||||
```
|
||||
|
||||
Each agent searches, reads sources, and returns findings. The main session synthesizes into the final report.
|
||||
|
||||
## Quality Rules
|
||||
|
||||
1. **Every claim needs a source.** No unsourced assertions.
|
||||
2. **Cross-reference.** If only one source says it, flag it as unverified.
|
||||
3. **Recency matters.** Prefer sources from the last 12 months.
|
||||
4. **Acknowledge gaps.** If you couldn't find good info on a sub-question, say so.
|
||||
5. **No hallucination.** If you don't know, say "insufficient data found."
|
||||
6. **Separate fact from inference.** Label estimates, projections, and opinions clearly.
|
||||
|
||||
## Examples
|
||||
|
||||
```
|
||||
"Research the current state of nuclear fusion energy"
|
||||
"Deep dive into Rust vs Go for backend services in 2026"
|
||||
"Research the best strategies for bootstrapping a SaaS business"
|
||||
"What's happening with the US housing market right now?"
|
||||
"Investigate the competitive landscape for AI code editors"
|
||||
```
|
||||
191
skills/dmux-workflows/SKILL.md
Normal file
191
skills/dmux-workflows/SKILL.md
Normal file
@@ -0,0 +1,191 @@
|
||||
---
|
||||
name: dmux-workflows
|
||||
description: Multi-agent orchestration using dmux (tmux pane manager for AI agents). Patterns for parallel agent workflows across Claude Code, Codex, OpenCode, and other harnesses. Use when running multiple agent sessions in parallel or coordinating multi-agent development workflows.
|
||||
origin: ECC
|
||||
---
|
||||
|
||||
# dmux Workflows
|
||||
|
||||
Orchestrate parallel AI agent sessions using dmux, a tmux pane manager for agent harnesses.
|
||||
|
||||
## When to Activate
|
||||
|
||||
- Running multiple agent sessions in parallel
|
||||
- Coordinating work across Claude Code, Codex, and other harnesses
|
||||
- Complex tasks that benefit from divide-and-conquer parallelism
|
||||
- User says "run in parallel", "split this work", "use dmux", or "multi-agent"
|
||||
|
||||
## What is dmux
|
||||
|
||||
dmux is a tmux-based orchestration tool that manages AI agent panes:
|
||||
- Press `n` to create a new pane with a prompt
|
||||
- Press `m` to merge pane output back to the main session
|
||||
- Supports: Claude Code, Codex, OpenCode, Cline, Gemini, Qwen
|
||||
|
||||
**Install:** `npm install -g dmux` or see [github.com/standardagents/dmux](https://github.com/standardagents/dmux)
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Start dmux session
|
||||
dmux
|
||||
|
||||
# Create agent panes (press 'n' in dmux, then type prompt)
|
||||
# Pane 1: "Implement the auth middleware in src/auth/"
|
||||
# Pane 2: "Write tests for the user service"
|
||||
# Pane 3: "Update API documentation"
|
||||
|
||||
# Each pane runs its own agent session
|
||||
# Press 'm' to merge results back
|
||||
```
|
||||
|
||||
## Workflow Patterns
|
||||
|
||||
### Pattern 1: Research + Implement
|
||||
|
||||
Split research and implementation into parallel tracks:
|
||||
|
||||
```
|
||||
Pane 1 (Research): "Research best practices for rate limiting in Node.js.
|
||||
Check current libraries, compare approaches, and write findings to
|
||||
/tmp/rate-limit-research.md"
|
||||
|
||||
Pane 2 (Implement): "Implement rate limiting middleware for our Express API.
|
||||
Start with a basic token bucket, we'll refine after research completes."
|
||||
|
||||
# After Pane 1 completes, merge findings into Pane 2's context
|
||||
```
|
||||
|
||||
### Pattern 2: Multi-File Feature
|
||||
|
||||
Parallelize work across independent files:
|
||||
|
||||
```
|
||||
Pane 1: "Create the database schema and migrations for the billing feature"
|
||||
Pane 2: "Build the billing API endpoints in src/api/billing/"
|
||||
Pane 3: "Create the billing dashboard UI components"
|
||||
|
||||
# Merge all, then do integration in main pane
|
||||
```
|
||||
|
||||
### Pattern 3: Test + Fix Loop
|
||||
|
||||
Run tests in one pane, fix in another:
|
||||
|
||||
```
|
||||
Pane 1 (Watcher): "Run the test suite in watch mode. When tests fail,
|
||||
summarize the failures."
|
||||
|
||||
Pane 2 (Fixer): "Fix failing tests based on the error output from pane 1"
|
||||
```
|
||||
|
||||
### Pattern 4: Cross-Harness
|
||||
|
||||
Use different AI tools for different tasks:
|
||||
|
||||
```
|
||||
Pane 1 (Claude Code): "Review the security of the auth module"
|
||||
Pane 2 (Codex): "Refactor the utility functions for performance"
|
||||
Pane 3 (Claude Code): "Write E2E tests for the checkout flow"
|
||||
```
|
||||
|
||||
### Pattern 5: Code Review Pipeline
|
||||
|
||||
Parallel review perspectives:
|
||||
|
||||
```
|
||||
Pane 1: "Review src/api/ for security vulnerabilities"
|
||||
Pane 2: "Review src/api/ for performance issues"
|
||||
Pane 3: "Review src/api/ for test coverage gaps"
|
||||
|
||||
# Merge all reviews into a single report
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Independent tasks only.** Don't parallelize tasks that depend on each other's output.
|
||||
2. **Clear boundaries.** Each pane should work on distinct files or concerns.
|
||||
3. **Merge strategically.** Review pane output before merging to avoid conflicts.
|
||||
4. **Use git worktrees.** For file-conflict-prone work, use separate worktrees per pane.
|
||||
5. **Resource awareness.** Each pane uses API tokens — keep total panes under 5-6.
|
||||
|
||||
## Git Worktree Integration
|
||||
|
||||
For tasks that touch overlapping files:
|
||||
|
||||
```bash
|
||||
# Create worktrees for isolation
|
||||
git worktree add -b feat/auth ../feature-auth HEAD
|
||||
git worktree add -b feat/billing ../feature-billing HEAD
|
||||
|
||||
# Run agents in separate worktrees
|
||||
# Pane 1: cd ../feature-auth && claude
|
||||
# Pane 2: cd ../feature-billing && claude
|
||||
|
||||
# Merge branches when done
|
||||
git merge feat/auth
|
||||
git merge feat/billing
|
||||
```
|
||||
|
||||
## Complementary Tools
|
||||
|
||||
| Tool | What It Does | When to Use |
|
||||
|------|-------------|-------------|
|
||||
| **dmux** | tmux pane management for agents | Parallel agent sessions |
|
||||
| **Superset** | Terminal IDE for 10+ parallel agents | Large-scale orchestration |
|
||||
| **Claude Code Task tool** | In-process subagent spawning | Programmatic parallelism within a session |
|
||||
| **Codex multi-agent** | Built-in agent roles | Codex-specific parallel work |
|
||||
|
||||
## ECC Helper
|
||||
|
||||
ECC now includes a helper for external tmux-pane orchestration with separate git worktrees:
|
||||
|
||||
```bash
|
||||
node scripts/orchestrate-worktrees.js plan.json --execute
|
||||
```
|
||||
|
||||
Example `plan.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"sessionName": "skill-audit",
|
||||
"baseRef": "HEAD",
|
||||
"launcherCommand": "codex exec --cwd {worktree_path_sh} --task-file {task_file_sh}",
|
||||
"workers": [
|
||||
{ "name": "docs-a", "task": "Fix skills 1-4 and write handoff notes." },
|
||||
{ "name": "docs-b", "task": "Fix skills 5-8 and write handoff notes." }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
The helper:
|
||||
- Creates one branch-backed git worktree per worker
|
||||
- Optionally overlays selected `seedPaths` from the main checkout into each worker worktree
|
||||
- Writes per-worker `task.md`, `handoff.md`, and `status.md` files under `.orchestration/<session>/`
|
||||
- Starts a tmux session with one pane per worker
|
||||
- Launches each worker command in its own pane
|
||||
- Leaves the main pane free for the orchestrator
|
||||
|
||||
Use `seedPaths` when workers need access to dirty or untracked local files that are not yet part of `HEAD`, such as local orchestration scripts, draft plans, or docs:
|
||||
|
||||
```json
|
||||
{
|
||||
"sessionName": "workflow-e2e",
|
||||
"seedPaths": [
|
||||
"scripts/orchestrate-worktrees.js",
|
||||
"scripts/lib/tmux-worktree-orchestrator.js",
|
||||
".claude/plan/workflow-e2e-test.json"
|
||||
],
|
||||
"launcherCommand": "bash {repo_root_sh}/scripts/orchestrate-codex-worker.sh {task_file_sh} {handoff_file_sh} {status_file_sh}",
|
||||
"workers": [
|
||||
{ "name": "seed-check", "task": "Verify seeded files are present before starting work." }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **Pane not responding:** Switch to the pane directly or inspect it with `tmux capture-pane -pt <session>:0.<pane-index>`.
|
||||
- **Merge conflicts:** Use git worktrees to isolate file changes per pane.
|
||||
- **High token usage:** Reduce number of parallel panes. Each pane is a full agent session.
|
||||
- **tmux not found:** Install with `brew install tmux` (macOS) or `apt install tmux` (Linux).
|
||||
175
skills/exa-search/SKILL.md
Normal file
175
skills/exa-search/SKILL.md
Normal file
@@ -0,0 +1,175 @@
|
||||
---
|
||||
name: exa-search
|
||||
description: Neural search via Exa MCP for web, code, and company research. Use when the user needs web search, code examples, company intel, people lookup, or AI-powered deep research with Exa's neural search engine.
|
||||
origin: ECC
|
||||
---
|
||||
|
||||
# Exa Search
|
||||
|
||||
Neural search for web content, code, companies, and people via the Exa MCP server.
|
||||
|
||||
## When to Activate
|
||||
|
||||
- User needs current web information or news
|
||||
- Searching for code examples, API docs, or technical references
|
||||
- Researching companies, competitors, or market players
|
||||
- Finding professional profiles or people in a domain
|
||||
- Running background research for any development task
|
||||
- User says "search for", "look up", "find", or "what's the latest on"
|
||||
|
||||
## MCP Requirement
|
||||
|
||||
Exa MCP server must be configured. Add to `~/.claude.json`:
|
||||
|
||||
```json
|
||||
"exa-web-search": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"exa-mcp-server",
|
||||
"tools=web_search_exa,web_search_advanced_exa,get_code_context_exa,crawling_exa,company_research_exa,people_search_exa,deep_researcher_start,deep_researcher_check"
|
||||
],
|
||||
"env": { "EXA_API_KEY": "YOUR_EXA_API_KEY_HERE" }
|
||||
}
|
||||
```
|
||||
|
||||
Get an API key at [exa.ai](https://exa.ai).
|
||||
If you omit the `tools=...` argument, only a smaller default tool set may be enabled.
|
||||
|
||||
## Core Tools
|
||||
|
||||
### web_search_exa
|
||||
General web search for current information, news, or facts.
|
||||
|
||||
```
|
||||
web_search_exa(query: "latest AI developments 2026", numResults: 5)
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Param | Type | Default | Notes |
|
||||
|-------|------|---------|-------|
|
||||
| `query` | string | required | Search query |
|
||||
| `numResults` | number | 8 | Number of results |
|
||||
|
||||
### web_search_advanced_exa
|
||||
Filtered search with domain and date constraints.
|
||||
|
||||
```
|
||||
web_search_advanced_exa(
|
||||
query: "React Server Components best practices",
|
||||
numResults: 5,
|
||||
includeDomains: ["github.com", "react.dev"],
|
||||
startPublishedDate: "2025-01-01"
|
||||
)
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Param | Type | Default | Notes |
|
||||
|-------|------|---------|-------|
|
||||
| `query` | string | required | Search query |
|
||||
| `numResults` | number | 8 | Number of results |
|
||||
| `includeDomains` | string[] | none | Limit to specific domains |
|
||||
| `excludeDomains` | string[] | none | Exclude specific domains |
|
||||
| `startPublishedDate` | string | none | ISO date filter (start) |
|
||||
| `endPublishedDate` | string | none | ISO date filter (end) |
|
||||
|
||||
### get_code_context_exa
|
||||
Find code examples and documentation from GitHub, Stack Overflow, and docs sites.
|
||||
|
||||
```
|
||||
get_code_context_exa(query: "Python asyncio patterns", tokensNum: 3000)
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Param | Type | Default | Notes |
|
||||
|-------|------|---------|-------|
|
||||
| `query` | string | required | Code or API search query |
|
||||
| `tokensNum` | number | 5000 | Content tokens (1000-50000) |
|
||||
|
||||
### company_research_exa
|
||||
Research companies for business intelligence and news.
|
||||
|
||||
```
|
||||
company_research_exa(companyName: "Anthropic", numResults: 5)
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Param | Type | Default | Notes |
|
||||
|-------|------|---------|-------|
|
||||
| `companyName` | string | required | Company name |
|
||||
| `numResults` | number | 5 | Number of results |
|
||||
|
||||
### people_search_exa
|
||||
Find professional profiles and bios.
|
||||
|
||||
```
|
||||
people_search_exa(query: "AI safety researchers at Anthropic", numResults: 5)
|
||||
```
|
||||
|
||||
### crawling_exa
|
||||
Extract full page content from a URL.
|
||||
|
||||
```
|
||||
crawling_exa(url: "https://example.com/article", tokensNum: 5000)
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Param | Type | Default | Notes |
|
||||
|-------|------|---------|-------|
|
||||
| `url` | string | required | URL to extract |
|
||||
| `tokensNum` | number | 5000 | Content tokens |
|
||||
|
||||
### deep_researcher_start / deep_researcher_check
|
||||
Start an AI research agent that runs asynchronously.
|
||||
|
||||
```
|
||||
# Start research
|
||||
deep_researcher_start(query: "comprehensive analysis of AI code editors in 2026")
|
||||
|
||||
# Check status (returns results when complete)
|
||||
deep_researcher_check(researchId: "<id from start>")
|
||||
```
|
||||
|
||||
## Usage Patterns
|
||||
|
||||
### Quick Lookup
|
||||
```
|
||||
web_search_exa(query: "Node.js 22 new features", numResults: 3)
|
||||
```
|
||||
|
||||
### Code Research
|
||||
```
|
||||
get_code_context_exa(query: "Rust error handling patterns Result type", tokensNum: 3000)
|
||||
```
|
||||
|
||||
### Company Due Diligence
|
||||
```
|
||||
company_research_exa(companyName: "Vercel", numResults: 5)
|
||||
web_search_advanced_exa(query: "Vercel funding valuation 2026", numResults: 3)
|
||||
```
|
||||
|
||||
### Technical Deep Dive
|
||||
```
|
||||
# Start async research
|
||||
deep_researcher_start(query: "WebAssembly component model status and adoption")
|
||||
# ... do other work ...
|
||||
deep_researcher_check(researchId: "<id>")
|
||||
```
|
||||
|
||||
## Tips
|
||||
|
||||
- Use `web_search_exa` for broad queries, `web_search_advanced_exa` for filtered results
|
||||
- Lower `tokensNum` (1000-2000) for focused code snippets, higher (5000+) for comprehensive context
|
||||
- Combine `company_research_exa` with `web_search_advanced_exa` for thorough company analysis
|
||||
- Use `crawling_exa` to get full content from specific URLs found in search results
|
||||
- `deep_researcher_start` is best for comprehensive topics that benefit from AI synthesis
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `deep-research` — Full research workflow using firecrawl + exa together
|
||||
- `market-research` — Business-oriented research with decision frameworks
|
||||
284
skills/fal-ai-media/SKILL.md
Normal file
284
skills/fal-ai-media/SKILL.md
Normal file
@@ -0,0 +1,284 @@
|
||||
---
|
||||
name: fal-ai-media
|
||||
description: Unified media generation via fal.ai MCP — image, video, and audio. Covers text-to-image (Nano Banana), text/image-to-video (Seedance, Kling, Veo 3), text-to-speech (CSM-1B), and video-to-audio (ThinkSound). Use when the user wants to generate images, videos, or audio with AI.
|
||||
origin: ECC
|
||||
---
|
||||
|
||||
# fal.ai Media Generation
|
||||
|
||||
Generate images, videos, and audio using fal.ai models via MCP.
|
||||
|
||||
## When to Activate
|
||||
|
||||
- User wants to generate images from text prompts
|
||||
- Creating videos from text or images
|
||||
- Generating speech, music, or sound effects
|
||||
- Any media generation task
|
||||
- User says "generate image", "create video", "text to speech", "make a thumbnail", or similar
|
||||
|
||||
## MCP Requirement
|
||||
|
||||
fal.ai MCP server must be configured. Add to `~/.claude.json`:
|
||||
|
||||
```json
|
||||
"fal-ai": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "fal-ai-mcp-server"],
|
||||
"env": { "FAL_KEY": "YOUR_FAL_KEY_HERE" }
|
||||
}
|
||||
```
|
||||
|
||||
Get an API key at [fal.ai](https://fal.ai).
|
||||
|
||||
## MCP Tools
|
||||
|
||||
The fal.ai MCP provides these tools:
|
||||
- `search` — Find available models by keyword
|
||||
- `find` — Get model details and parameters
|
||||
- `generate` — Run a model with parameters
|
||||
- `result` — Check async generation status
|
||||
- `status` — Check job status
|
||||
- `cancel` — Cancel a running job
|
||||
- `estimate_cost` — Estimate generation cost
|
||||
- `models` — List popular models
|
||||
- `upload` — Upload files for use as inputs
|
||||
|
||||
---
|
||||
|
||||
## Image Generation
|
||||
|
||||
### Nano Banana 2 (Fast)
|
||||
Best for: quick iterations, drafts, text-to-image, image editing.
|
||||
|
||||
```
|
||||
generate(
|
||||
app_id: "fal-ai/nano-banana-2",
|
||||
input_data: {
|
||||
"prompt": "a futuristic cityscape at sunset, cyberpunk style",
|
||||
"image_size": "landscape_16_9",
|
||||
"num_images": 1,
|
||||
"seed": 42
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Nano Banana Pro (High Fidelity)
|
||||
Best for: production images, realism, typography, detailed prompts.
|
||||
|
||||
```
|
||||
generate(
|
||||
app_id: "fal-ai/nano-banana-pro",
|
||||
input_data: {
|
||||
"prompt": "professional product photo of wireless headphones on marble surface, studio lighting",
|
||||
"image_size": "square",
|
||||
"num_images": 1,
|
||||
"guidance_scale": 7.5
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Common Image Parameters
|
||||
|
||||
| Param | Type | Options | Notes |
|
||||
|-------|------|---------|-------|
|
||||
| `prompt` | string | required | Describe what you want |
|
||||
| `image_size` | string | `square`, `portrait_4_3`, `landscape_16_9`, `portrait_16_9`, `landscape_4_3` | Aspect ratio |
|
||||
| `num_images` | number | 1-4 | How many to generate |
|
||||
| `seed` | number | any integer | Reproducibility |
|
||||
| `guidance_scale` | number | 1-20 | How closely to follow the prompt (higher = more literal) |
|
||||
|
||||
### Image Editing
|
||||
Use Nano Banana 2 with an input image for inpainting, outpainting, or style transfer:
|
||||
|
||||
```
|
||||
# First upload the source image
|
||||
upload(file_path: "/path/to/image.png")
|
||||
|
||||
# Then generate with image input
|
||||
generate(
|
||||
app_id: "fal-ai/nano-banana-2",
|
||||
input_data: {
|
||||
"prompt": "same scene but in watercolor style",
|
||||
"image_url": "<uploaded_url>",
|
||||
"image_size": "landscape_16_9"
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Video Generation
|
||||
|
||||
### Seedance 1.0 Pro (ByteDance)
|
||||
Best for: text-to-video, image-to-video with high motion quality.
|
||||
|
||||
```
|
||||
generate(
|
||||
app_id: "fal-ai/seedance-1-0-pro",
|
||||
input_data: {
|
||||
"prompt": "a drone flyover of a mountain lake at golden hour, cinematic",
|
||||
"duration": "5s",
|
||||
"aspect_ratio": "16:9",
|
||||
"seed": 42
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Kling Video v3 Pro
|
||||
Best for: text/image-to-video with native audio generation.
|
||||
|
||||
```
|
||||
generate(
|
||||
app_id: "fal-ai/kling-video/v3/pro",
|
||||
input_data: {
|
||||
"prompt": "ocean waves crashing on a rocky coast, dramatic clouds",
|
||||
"duration": "5s",
|
||||
"aspect_ratio": "16:9"
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Veo 3 (Google DeepMind)
|
||||
Best for: video with generated sound, high visual quality.
|
||||
|
||||
```
|
||||
generate(
|
||||
app_id: "fal-ai/veo-3",
|
||||
input_data: {
|
||||
"prompt": "a bustling Tokyo street market at night, neon signs, crowd noise",
|
||||
"aspect_ratio": "16:9"
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Image-to-Video
|
||||
Start from an existing image:
|
||||
|
||||
```
|
||||
generate(
|
||||
app_id: "fal-ai/seedance-1-0-pro",
|
||||
input_data: {
|
||||
"prompt": "camera slowly zooms out, gentle wind moves the trees",
|
||||
"image_url": "<uploaded_image_url>",
|
||||
"duration": "5s"
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Video Parameters
|
||||
|
||||
| Param | Type | Options | Notes |
|
||||
|-------|------|---------|-------|
|
||||
| `prompt` | string | required | Describe the video |
|
||||
| `duration` | string | `"5s"`, `"10s"` | Video length |
|
||||
| `aspect_ratio` | string | `"16:9"`, `"9:16"`, `"1:1"` | Frame ratio |
|
||||
| `seed` | number | any integer | Reproducibility |
|
||||
| `image_url` | string | URL | Source image for image-to-video |
|
||||
|
||||
---
|
||||
|
||||
## Audio Generation
|
||||
|
||||
### CSM-1B (Conversational Speech)
|
||||
Text-to-speech with natural, conversational quality.
|
||||
|
||||
```
|
||||
generate(
|
||||
app_id: "fal-ai/csm-1b",
|
||||
input_data: {
|
||||
"text": "Hello, welcome to the demo. Let me show you how this works.",
|
||||
"speaker_id": 0
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### ThinkSound (Video-to-Audio)
|
||||
Generate matching audio from video content.
|
||||
|
||||
```
|
||||
generate(
|
||||
app_id: "fal-ai/thinksound",
|
||||
input_data: {
|
||||
"video_url": "<video_url>",
|
||||
"prompt": "ambient forest sounds with birds chirping"
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### ElevenLabs (via API, no MCP)
|
||||
For professional voice synthesis, use ElevenLabs directly:
|
||||
|
||||
```python
|
||||
import os
|
||||
import requests
|
||||
|
||||
resp = requests.post(
|
||||
"https://api.elevenlabs.io/v1/text-to-speech/<voice_id>",
|
||||
headers={
|
||||
"xi-api-key": os.environ["ELEVENLABS_API_KEY"],
|
||||
"Content-Type": "application/json"
|
||||
},
|
||||
json={
|
||||
"text": "Your text here",
|
||||
"model_id": "eleven_turbo_v2_5",
|
||||
"voice_settings": {"stability": 0.5, "similarity_boost": 0.75}
|
||||
}
|
||||
)
|
||||
with open("output.mp3", "wb") as f:
|
||||
f.write(resp.content)
|
||||
```
|
||||
|
||||
### VideoDB Generative Audio
|
||||
If VideoDB is configured, use its generative audio:
|
||||
|
||||
```python
|
||||
# Voice generation
|
||||
audio = coll.generate_voice(text="Your narration here", voice="alloy")
|
||||
|
||||
# Music generation
|
||||
music = coll.generate_music(prompt="upbeat electronic background music", duration=30)
|
||||
|
||||
# Sound effects
|
||||
sfx = coll.generate_sound_effect(prompt="thunder crack followed by rain")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cost Estimation
|
||||
|
||||
Before generating, check estimated cost:
|
||||
|
||||
```
|
||||
estimate_cost(
|
||||
estimate_type: "unit_price",
|
||||
endpoints: {
|
||||
"fal-ai/nano-banana-pro": {
|
||||
"unit_quantity": 1
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
## Model Discovery
|
||||
|
||||
Find models for specific tasks:
|
||||
|
||||
```
|
||||
search(query: "text to video")
|
||||
find(endpoint_ids: ["fal-ai/seedance-1-0-pro"])
|
||||
models()
|
||||
```
|
||||
|
||||
## Tips
|
||||
|
||||
- Use `seed` for reproducible results when iterating on prompts
|
||||
- Start with lower-cost models (Nano Banana 2) for prompt iteration, then switch to Pro for finals
|
||||
- For video, keep prompts descriptive but concise — focus on motion and scene
|
||||
- Image-to-video produces more controlled results than pure text-to-video
|
||||
- Check `estimate_cost` before running expensive video generations
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `videodb` — Video processing, editing, and streaming
|
||||
- `video-editing` — AI-powered video editing workflows
|
||||
- `content-engine` — Content creation for social platforms
|
||||
397
skills/prompt-optimizer/SKILL.md
Normal file
397
skills/prompt-optimizer/SKILL.md
Normal file
@@ -0,0 +1,397 @@
|
||||
---
|
||||
name: prompt-optimizer
|
||||
description: >-
|
||||
Analyze raw prompts, identify intent and gaps, match ECC components
|
||||
(skills/commands/agents/hooks), and output a ready-to-paste optimized
|
||||
prompt. Advisory role only — never executes the task itself.
|
||||
TRIGGER when: user says "optimize prompt", "improve my prompt",
|
||||
"how to write a prompt for", "help me prompt", "rewrite this prompt",
|
||||
or explicitly asks to enhance prompt quality. Also triggers on Chinese
|
||||
equivalents: "优化prompt", "改进prompt", "怎么写prompt", "帮我优化这个指令".
|
||||
DO NOT TRIGGER when: user wants the task executed directly, or says
|
||||
"just do it" / "直接做". DO NOT TRIGGER when user says "优化代码",
|
||||
"优化性能", "optimize performance", "optimize this code" — those are
|
||||
refactoring/performance tasks, not prompt optimization.
|
||||
origin: community
|
||||
metadata:
|
||||
author: YannJY02
|
||||
version: "1.0.0"
|
||||
---
|
||||
|
||||
# Prompt Optimizer
|
||||
|
||||
Analyze a draft prompt, critique it, match it to ECC ecosystem components,
|
||||
and output a complete optimized prompt the user can paste and run.
|
||||
|
||||
## When to Use
|
||||
|
||||
- User says "optimize this prompt", "improve my prompt", "rewrite this prompt"
|
||||
- User says "help me write a better prompt for..."
|
||||
- User says "what's the best way to ask Claude Code to..."
|
||||
- User says "优化prompt", "改进prompt", "怎么写prompt", "帮我优化这个指令"
|
||||
- User pastes a draft prompt and asks for feedback or enhancement
|
||||
- User says "I don't know how to prompt for this"
|
||||
- User says "how should I use ECC for..."
|
||||
- User explicitly invokes `/prompt-optimize`
|
||||
|
||||
### Do Not Use When
|
||||
|
||||
- User wants the task done directly (just execute it)
|
||||
- User says "优化代码", "优化性能", "optimize this code", "optimize performance" — these are refactoring tasks, not prompt optimization
|
||||
- User is asking about ECC configuration (use `configure-ecc` instead)
|
||||
- User wants a skill inventory (use `skill-stocktake` instead)
|
||||
- User says "just do it" or "直接做"
|
||||
|
||||
## How It Works
|
||||
|
||||
**Advisory only — do not execute the user's task.**
|
||||
|
||||
Do NOT write code, create files, run commands, or take any implementation
|
||||
action. Your ONLY output is an analysis plus an optimized prompt.
|
||||
|
||||
If the user says "just do it", "直接做", or "don't optimize, just execute",
|
||||
do not switch into implementation mode inside this skill. Tell the user this
|
||||
skill only produces optimized prompts, and instruct them to make a normal
|
||||
task request if they want execution instead.
|
||||
|
||||
Run this 6-phase pipeline sequentially. Present results using the Output Format below.
|
||||
|
||||
### Analysis Pipeline
|
||||
|
||||
### Phase 0: Project Detection
|
||||
|
||||
Before analyzing the prompt, detect the current project context:
|
||||
|
||||
1. Check if a `CLAUDE.md` exists in the working directory — read it for project conventions
|
||||
2. Detect tech stack from project files:
|
||||
- `package.json` → Node.js / TypeScript / React / Next.js
|
||||
- `go.mod` → Go
|
||||
- `pyproject.toml` / `requirements.txt` → Python
|
||||
- `Cargo.toml` → Rust
|
||||
- `build.gradle` / `pom.xml` → Java / Kotlin / Spring Boot
|
||||
- `Package.swift` → Swift
|
||||
- `Gemfile` → Ruby
|
||||
- `composer.json` → PHP
|
||||
- `*.csproj` / `*.sln` → .NET
|
||||
- `Makefile` / `CMakeLists.txt` → C / C++
|
||||
- `cpanfile` / `Makefile.PL` → Perl
|
||||
3. Note detected tech stack for use in Phase 3 and Phase 4
|
||||
|
||||
If no project files are found (e.g., the prompt is abstract or for a new project),
|
||||
skip detection and flag "tech stack unknown" in Phase 4.
|
||||
|
||||
### Phase 1: Intent Detection
|
||||
|
||||
Classify the user's task into one or more categories:
|
||||
|
||||
| Category | Signal Words | Example |
|
||||
|----------|-------------|---------|
|
||||
| New Feature | build, create, add, implement, 创建, 实现, 添加 | "Build a login page" |
|
||||
| Bug Fix | fix, broken, not working, error, 修复, 报错 | "Fix the auth flow" |
|
||||
| Refactor | refactor, clean up, restructure, 重构, 整理 | "Refactor the API layer" |
|
||||
| Research | how to, what is, explore, investigate, 怎么, 如何 | "How to add SSO" |
|
||||
| Testing | test, coverage, verify, 测试, 覆盖率 | "Add tests for the cart" |
|
||||
| Review | review, audit, check, 审查, 检查 | "Review my PR" |
|
||||
| Documentation | document, update docs, 文档 | "Update the API docs" |
|
||||
| Infrastructure | deploy, CI, docker, database, 部署, 数据库 | "Set up CI/CD pipeline" |
|
||||
| Design | design, architecture, plan, 设计, 架构 | "Design the data model" |
|
||||
|
||||
### Phase 2: Scope Assessment
|
||||
|
||||
If Phase 0 detected a project, use codebase size as a signal. Otherwise, estimate
|
||||
from the prompt description alone and mark the estimate as uncertain.
|
||||
|
||||
| Scope | Heuristic | Orchestration |
|
||||
|-------|-----------|---------------|
|
||||
| TRIVIAL | Single file, < 50 lines | Direct execution |
|
||||
| LOW | Single component or module | Single command or skill |
|
||||
| MEDIUM | Multiple components, same domain | Command chain + /verify |
|
||||
| HIGH | Cross-domain, 5+ files | /plan first, then phased execution |
|
||||
| EPIC | Multi-session, multi-PR, architectural shift | Use blueprint skill for multi-session plan |
|
||||
|
||||
### Phase 3: ECC Component Matching
|
||||
|
||||
Map intent + scope + tech stack (from Phase 0) to specific ECC components.
|
||||
|
||||
#### By Intent Type
|
||||
|
||||
| Intent | Commands | Skills | Agents |
|
||||
|--------|----------|--------|--------|
|
||||
| New Feature | /plan, /tdd, /code-review, /verify | tdd-workflow, verification-loop | planner, tdd-guide, code-reviewer |
|
||||
| Bug Fix | /tdd, /build-fix, /verify | tdd-workflow | tdd-guide, build-error-resolver |
|
||||
| Refactor | /refactor-clean, /code-review, /verify | verification-loop | refactor-cleaner, code-reviewer |
|
||||
| Research | /plan | search-first, iterative-retrieval | — |
|
||||
| Testing | /tdd, /e2e, /test-coverage | tdd-workflow, e2e-testing | tdd-guide, e2e-runner |
|
||||
| Review | /code-review | security-review | code-reviewer, security-reviewer |
|
||||
| Documentation | /update-docs, /update-codemaps | — | doc-updater |
|
||||
| Infrastructure | /plan, /verify | docker-patterns, deployment-patterns, database-migrations | architect |
|
||||
| Design (MEDIUM-HIGH) | /plan | — | planner, architect |
|
||||
| Design (EPIC) | — | blueprint (invoke as skill) | planner, architect |
|
||||
|
||||
#### By Tech Stack
|
||||
|
||||
| Tech Stack | Skills to Add | Agent |
|
||||
|------------|--------------|-------|
|
||||
| Python / Django | django-patterns, django-tdd, django-security, django-verification, python-patterns, python-testing | python-reviewer |
|
||||
| Go | golang-patterns, golang-testing | go-reviewer, go-build-resolver |
|
||||
| Spring Boot / Java | springboot-patterns, springboot-tdd, springboot-security, springboot-verification, java-coding-standards, jpa-patterns | code-reviewer |
|
||||
| Kotlin / Android | kotlin-coroutines-flows, compose-multiplatform-patterns, android-clean-architecture | kotlin-reviewer |
|
||||
| TypeScript / React | frontend-patterns, backend-patterns, coding-standards | code-reviewer |
|
||||
| Swift / iOS | swiftui-patterns, swift-concurrency-6-2, swift-actor-persistence, swift-protocol-di-testing | code-reviewer |
|
||||
| PostgreSQL | postgres-patterns, database-migrations | database-reviewer |
|
||||
| Perl | perl-patterns, perl-testing, perl-security | code-reviewer |
|
||||
| C++ | cpp-coding-standards, cpp-testing | code-reviewer |
|
||||
| Other / Unlisted | coding-standards (universal) | code-reviewer |
|
||||
|
||||
### Phase 4: Missing Context Detection
|
||||
|
||||
Scan the prompt for missing critical information. Check each item and mark
|
||||
whether Phase 0 auto-detected it or the user must supply it:
|
||||
|
||||
- [ ] **Tech stack** — Detected in Phase 0, or must user specify?
|
||||
- [ ] **Target scope** — Files, directories, or modules mentioned?
|
||||
- [ ] **Acceptance criteria** — How to know the task is done?
|
||||
- [ ] **Error handling** — Edge cases and failure modes addressed?
|
||||
- [ ] **Security requirements** — Auth, input validation, secrets?
|
||||
- [ ] **Testing expectations** — Unit, integration, E2E?
|
||||
- [ ] **Performance constraints** — Load, latency, resource limits?
|
||||
- [ ] **UI/UX requirements** — Design specs, responsive, a11y? (if frontend)
|
||||
- [ ] **Database changes** — Schema, migrations, indexes? (if data layer)
|
||||
- [ ] **Existing patterns** — Reference files or conventions to follow?
|
||||
- [ ] **Scope boundaries** — What NOT to do?
|
||||
|
||||
**If 3+ critical items are missing**, ask the user up to 3 clarification
|
||||
questions before generating the optimized prompt. Then incorporate the
|
||||
answers into the optimized prompt.
|
||||
|
||||
### Phase 5: Workflow & Model Recommendation
|
||||
|
||||
Determine where this prompt sits in the development lifecycle:
|
||||
|
||||
```
|
||||
Research → Plan → Implement (TDD) → Review → Verify → Commit
|
||||
```
|
||||
|
||||
For MEDIUM+ tasks, always start with /plan. For EPIC tasks, use blueprint skill.
|
||||
|
||||
**Model recommendation** (include in output):
|
||||
|
||||
| Scope | Recommended Model | Rationale |
|
||||
|-------|------------------|-----------|
|
||||
| TRIVIAL-LOW | Sonnet 4.6 | Fast, cost-efficient for simple tasks |
|
||||
| MEDIUM | Sonnet 4.6 | Best coding model for standard work |
|
||||
| HIGH | Sonnet 4.6 (main) + Opus 4.6 (planning) | Opus for architecture, Sonnet for implementation |
|
||||
| EPIC | Opus 4.6 (blueprint) + Sonnet 4.6 (execution) | Deep reasoning for multi-session planning |
|
||||
|
||||
**Multi-prompt splitting** (for HIGH/EPIC scope):
|
||||
|
||||
For tasks that exceed a single session, split into sequential prompts:
|
||||
- Prompt 1: Research + Plan (use search-first skill, then /plan)
|
||||
- Prompt 2-N: Implement one phase per prompt (each ends with /verify)
|
||||
- Final Prompt: Integration test + /code-review across all phases
|
||||
- Use /save-session and /resume-session to preserve context between sessions
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
Present your analysis in this exact structure. Respond in the same language
|
||||
as the user's input.
|
||||
|
||||
### Section 1: Prompt Diagnosis
|
||||
|
||||
**Strengths:** List what the original prompt does well.
|
||||
|
||||
**Issues:**
|
||||
|
||||
| Issue | Impact | Suggested Fix |
|
||||
|-------|--------|---------------|
|
||||
| (problem) | (consequence) | (how to fix) |
|
||||
|
||||
**Needs Clarification:** Numbered list of questions the user should answer.
|
||||
If Phase 0 auto-detected the answer, state it instead of asking.
|
||||
|
||||
### Section 2: Recommended ECC Components
|
||||
|
||||
| Type | Component | Purpose |
|
||||
|------|-----------|---------|
|
||||
| Command | /plan | Plan architecture before coding |
|
||||
| Skill | tdd-workflow | TDD methodology guidance |
|
||||
| Agent | code-reviewer | Post-implementation review |
|
||||
| Model | Sonnet 4.6 | Recommended for this scope |
|
||||
|
||||
### Section 3: Optimized Prompt — Full Version
|
||||
|
||||
Present the complete optimized prompt inside a single fenced code block.
|
||||
The prompt must be self-contained and ready to copy-paste. Include:
|
||||
- Clear task description with context
|
||||
- Tech stack (detected or specified)
|
||||
- /command invocations at the right workflow stages
|
||||
- Acceptance criteria
|
||||
- Verification steps
|
||||
- Scope boundaries (what NOT to do)
|
||||
|
||||
For items that reference blueprint, write: "Use the blueprint skill to..."
|
||||
(not `/blueprint`, since blueprint is a skill, not a command).
|
||||
|
||||
### Section 4: Optimized Prompt — Quick Version
|
||||
|
||||
A compact version for experienced ECC users. Vary by intent type:
|
||||
|
||||
| Intent | Quick Pattern |
|
||||
|--------|--------------|
|
||||
| New Feature | `/plan [feature]. /tdd to implement. /code-review. /verify.` |
|
||||
| Bug Fix | `/tdd — write failing test for [bug]. Fix to green. /verify.` |
|
||||
| Refactor | `/refactor-clean [scope]. /code-review. /verify.` |
|
||||
| Research | `Use search-first skill for [topic]. /plan based on findings.` |
|
||||
| Testing | `/tdd [module]. /e2e for critical flows. /test-coverage.` |
|
||||
| Review | `/code-review. Then use security-reviewer agent.` |
|
||||
| Docs | `/update-docs. /update-codemaps.` |
|
||||
| EPIC | `Use blueprint skill for "[objective]". Execute phases with /verify gates.` |
|
||||
|
||||
### Section 5: Enhancement Rationale
|
||||
|
||||
| Enhancement | Reason |
|
||||
|-------------|--------|
|
||||
| (what was added) | (why it matters) |
|
||||
|
||||
### Footer
|
||||
|
||||
> Not what you need? Tell me what to adjust, or make a normal task request
|
||||
> if you want execution instead of prompt optimization.
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Trigger Examples
|
||||
|
||||
- "Optimize this prompt for ECC"
|
||||
- "Rewrite this prompt so Claude Code uses the right commands"
|
||||
- "帮我优化这个指令"
|
||||
- "How should I prompt ECC for this task?"
|
||||
|
||||
### Example 1: Vague Chinese Prompt (Project Detected)
|
||||
|
||||
**User input:**
|
||||
```
|
||||
帮我写一个用户登录页面
|
||||
```
|
||||
|
||||
**Phase 0 detects:** `package.json` with Next.js 15, TypeScript, Tailwind CSS
|
||||
|
||||
**Optimized Prompt (Full):**
|
||||
```
|
||||
使用项目现有技术栈（Next.js 15 + TypeScript + Tailwind CSS）实现用户登录页面。
|
||||
|
||||
技术要求：
|
||||
- 沿用项目现有的组件结构和路由约定
|
||||
- 表单验证使用项目中已有的验证方案（检查是否已用 Zod/Yup/其他）
|
||||
- 认证方式：沿用项目现有认证方案（如无，默认 JWT）
|
||||
- 包含：邮箱/密码登录表单、表单验证、错误提示、加载状态、响应式布局
|
||||
|
||||
工作流：
|
||||
1. /plan 先规划组件结构和认证流程，参考现有页面的模式
|
||||
2. /tdd 测试先行：编写登录表单的单元测试和认证流程的集成测试
|
||||
3. 实现登录页面和认证逻辑
|
||||
4. /code-review 审查实现
|
||||
5. /verify 验证所有测试通过且页面正常渲染
|
||||
|
||||
安全要求：
|
||||
- 密码不明文传输
|
||||
- 防止暴力破解（rate limiting）
|
||||
- XSS 防护
|
||||
- CSRF token
|
||||
|
||||
验收标准：
|
||||
- 所有测试通过，覆盖率 80%+
|
||||
- 页面在移动端和桌面端正常渲染
|
||||
- 登录成功跳转到 dashboard，失败显示错误信息
|
||||
|
||||
不要做：
|
||||
- 不要实现注册页面
|
||||
- 不要实现忘记密码功能
|
||||
- 不要修改现有的路由结构
|
||||
```
|
||||
|
||||
### Example 2: Moderate English Prompt
|
||||
|
||||
**User input:**
|
||||
```
|
||||
Add a REST API endpoint for user profile updates with validation
|
||||
```
|
||||
|
||||
**Phase 0 detects:** `go.mod` with Go 1.22, Chi router
|
||||
|
||||
**Optimized Prompt (Full):**
|
||||
```
|
||||
Add a REST API endpoint for user profile updates (PATCH /api/users/:id).
|
||||
|
||||
Tech stack: Go 1.22 + Chi router (detected from project)
|
||||
|
||||
Requirements:
|
||||
- PATCH /api/users/:id — partial update of user profile
|
||||
- Input validation for fields: name, email, avatar_url, bio
|
||||
- Auth: require valid token, users can only update own profile
|
||||
- Return 200 with updated user on success
|
||||
- Return 400 with validation errors on invalid input
|
||||
- Return 401/403 for auth failures
|
||||
- Follow existing API patterns in the codebase
|
||||
|
||||
Workflow:
|
||||
1. /plan the endpoint structure, middleware chain, and validation logic
|
||||
2. /tdd — write table-driven tests for success, validation failure, auth failure, not-found
|
||||
3. Implement following existing handler patterns
|
||||
4. /go-review
|
||||
5. /verify — run full test suite, confirm no regressions
|
||||
|
||||
Do not:
|
||||
- Modify existing endpoints
|
||||
- Change the database schema (use existing user table)
|
||||
- Add new dependencies without checking existing ones first (use search-first skill)
|
||||
```
|
||||
|
||||
### Example 3: EPIC Project
|
||||
|
||||
**User input:**
|
||||
```
|
||||
Migrate our monolith to microservices
|
||||
```
|
||||
|
||||
**Optimized Prompt (Full):**
|
||||
```
|
||||
Use the blueprint skill to plan: "Migrate monolith to microservices architecture"
|
||||
|
||||
Before executing, answer these questions in the blueprint:
|
||||
1. Which domain boundaries exist in the current monolith?
|
||||
2. Which service should be extracted first (lowest coupling)?
|
||||
3. Communication pattern: REST APIs, gRPC, or event-driven (Kafka/RabbitMQ)?
|
||||
4. Database strategy: shared DB initially or database-per-service from start?
|
||||
5. Deployment target: Kubernetes, Docker Compose, or serverless?
|
||||
|
||||
The blueprint should produce phases like:
|
||||
- Phase 1: Identify service boundaries and create domain map
|
||||
- Phase 2: Set up infrastructure (API gateway, service mesh, CI/CD per service)
|
||||
- Phase 3: Extract first service (strangler fig pattern)
|
||||
- Phase 4: Verify with integration tests, then extract next service
|
||||
- Phase N: Decommission monolith
|
||||
|
||||
Each phase = 1 PR, with /verify gates between phases.
|
||||
Use /save-session between phases. Use /resume-session to continue.
|
||||
Use git worktrees for parallel service extraction when dependencies allow.
|
||||
|
||||
Recommended: Opus 4.6 for blueprint planning, Sonnet 4.6 for phase execution.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Components
|
||||
|
||||
| Component | When to Reference |
|
||||
|-----------|------------------|
|
||||
| `configure-ecc` | User hasn't set up ECC yet |
|
||||
| `skill-stocktake` | Audit which components are installed (use instead of hardcoded catalog) |
|
||||
| `search-first` | Research phase in optimized prompts |
|
||||
| `blueprint` | EPIC-scope optimized prompts (invoke as skill, not command) |
|
||||
| `strategic-compact` | Long session context management |
|
||||
| `cost-aware-llm-pipeline` | Token optimization recommendations |
|
||||
@@ -96,6 +96,34 @@ Understanding what persists helps you compact with confidence:
|
||||
5. **Write before compacting** — Save important context to files or memory before compacting
|
||||
6. **Use `/compact` with a summary** — Add a custom message: `/compact Focus on implementing auth middleware next`
|
||||
|
||||
## Token Optimization Patterns
|
||||
|
||||
### Trigger-Table Lazy Loading
|
||||
Instead of loading full skill content at session start, use a trigger table that maps keywords to skill paths. Skills load only when triggered, reducing baseline context by 50%+:
|
||||
|
||||
| Trigger | Skill | Load When |
|
||||
|---------|-------|-----------|
|
||||
| "test", "tdd", "coverage" | tdd-workflow | User mentions testing |
|
||||
| "security", "auth", "xss" | security-review | Security-related work |
|
||||
| "deploy", "ci/cd" | deployment-patterns | Deployment context |
|
||||
|
||||
### Context Composition Awareness
|
||||
Monitor what's consuming your context window:
|
||||
- **CLAUDE.md files** — Always loaded, keep lean
|
||||
- **Loaded skills** — Each skill adds 1-5K tokens
|
||||
- **Conversation history** — Grows with each exchange
|
||||
- **Tool results** — File reads, search results add bulk
|
||||
|
||||
### Duplicate Instruction Detection
|
||||
Common sources of duplicate context:
|
||||
- Same rules in both `~/.claude/rules/` and project `.claude/rules/`
|
||||
- Skills that repeat CLAUDE.md instructions
|
||||
- Multiple skills covering overlapping domains
|
||||
|
||||
### Context Optimization Tools
|
||||
- `token-optimizer` MCP — Automated 95%+ token reduction via content deduplication
|
||||
- `context-mode` — Context virtualization (315KB to 5.4KB demonstrated)
|
||||
|
||||
## Related
|
||||
|
||||
- [The Longform Guide](https://x.com/affaanmustafa/status/2014040193557471352) — Token optimization section
|
||||
|
||||
310
skills/video-editing/SKILL.md
Normal file
310
skills/video-editing/SKILL.md
Normal file
@@ -0,0 +1,310 @@
|
||||
---
|
||||
name: video-editing
|
||||
description: AI-assisted video editing workflows for cutting, structuring, and augmenting real footage. Covers the full pipeline from raw capture through FFmpeg, Remotion, ElevenLabs, fal.ai, and final polish in Descript or CapCut. Use when the user wants to edit video, cut footage, create vlogs, or build video content.
|
||||
origin: ECC
|
||||
---
|
||||
|
||||
# Video Editing
|
||||
|
||||
AI-assisted editing for real footage. Not generation from prompts. Editing existing video fast.
|
||||
|
||||
## When to Activate
|
||||
|
||||
- User wants to edit, cut, or structure video footage
|
||||
- Turning long recordings into short-form content
|
||||
- Building vlogs, tutorials, or demo videos from raw capture
|
||||
- Adding overlays, subtitles, music, or voiceover to existing video
|
||||
- Reframing video for different platforms (YouTube, TikTok, Instagram)
|
||||
- User says "edit video", "cut this footage", "make a vlog", or "video workflow"
|
||||
|
||||
## Core Thesis
|
||||
|
||||
AI video editing is useful when you stop asking it to create the whole video and start using it to compress, structure, and augment real footage. The value is not generation. The value is compression.
|
||||
|
||||
## The Pipeline
|
||||
|
||||
```
|
||||
Screen Studio / raw footage
|
||||
→ Claude / Codex
|
||||
→ FFmpeg
|
||||
→ Remotion
|
||||
→ ElevenLabs / fal.ai
|
||||
→ Descript or CapCut
|
||||
```
|
||||
|
||||
Each layer has a specific job. Do not skip layers. Do not try to make one tool do everything.
|
||||
|
||||
## Layer 1: Capture (Screen Studio / Raw Footage)
|
||||
|
||||
Collect the source material:
|
||||
- **Screen Studio**: polished screen recordings for app demos, coding sessions, browser workflows
|
||||
- **Raw camera footage**: vlog footage, interviews, event recordings
|
||||
- **Desktop capture via VideoDB**: session recording with real-time context (see `videodb` skill)
|
||||
|
||||
Output: raw files ready for organization.
|
||||
|
||||
## Layer 2: Organization (Claude / Codex)
|
||||
|
||||
Use Claude Code or Codex to:
|
||||
- **Transcribe and label**: generate transcript, identify topics and themes
|
||||
- **Plan structure**: decide what stays, what gets cut, what order works
|
||||
- **Identify dead sections**: find pauses, tangents, repeated takes
|
||||
- **Generate edit decision list**: timestamps for cuts, segments to keep
|
||||
- **Scaffold FFmpeg and Remotion code**: generate the commands and compositions
|
||||
|
||||
```
|
||||
Example prompt:
|
||||
"Here's the transcript of a 4-hour recording. Identify the 8 strongest segments
|
||||
for a 24-minute vlog. Give me FFmpeg cut commands for each segment."
|
||||
```
|
||||
|
||||
This layer is about structure, not final creative taste.
|
||||
|
||||
## Layer 3: Deterministic Cuts (FFmpeg)
|
||||
|
||||
FFmpeg handles the boring but critical work: splitting, trimming, concatenating, and preprocessing.
|
||||
|
||||
### Extract segment by timestamp
|
||||
|
||||
```bash
|
||||
ffmpeg -i raw.mp4 -ss 00:12:30 -to 00:15:45 -c copy segment_01.mp4
|
||||
```
|
||||
|
||||
### Batch cut from edit decision list
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# cuts.txt: start,end,label
|
||||
while IFS=, read -r start end label; do
|
||||
ffmpeg -i raw.mp4 -ss "$start" -to "$end" -c copy "segments/${label}.mp4"
|
||||
done < cuts.txt
|
||||
```
|
||||
|
||||
### Concatenate segments
|
||||
|
||||
```bash
|
||||
# Create file list
|
||||
for f in segments/*.mp4; do echo "file '$f'"; done > concat.txt
|
||||
ffmpeg -f concat -safe 0 -i concat.txt -c copy assembled.mp4
|
||||
```
|
||||
|
||||
### Create proxy for faster editing
|
||||
|
||||
```bash
|
||||
ffmpeg -i raw.mp4 -vf "scale=960:-2" -c:v libx264 -preset ultrafast -crf 28 proxy.mp4
|
||||
```
|
||||
|
||||
### Extract audio for transcription
|
||||
|
||||
```bash
|
||||
ffmpeg -i raw.mp4 -vn -acodec pcm_s16le -ar 16000 audio.wav
|
||||
```
|
||||
|
||||
### Normalize audio levels
|
||||
|
||||
```bash
|
||||
ffmpeg -i segment.mp4 -af loudnorm=I=-16:TP=-1.5:LRA=11 -c:v copy normalized.mp4
|
||||
```
|
||||
|
||||
## Layer 4: Programmable Composition (Remotion)
|
||||
|
||||
Remotion turns editing problems into composable code. Use it for things that traditional editors make painful:
|
||||
|
||||
### When to use Remotion
|
||||
|
||||
- Overlays: text, images, branding, lower thirds
|
||||
- Data visualizations: charts, stats, animated numbers
|
||||
- Motion graphics: transitions, explainer animations
|
||||
- Composable scenes: reusable templates across videos
|
||||
- Product demos: annotated screenshots, UI highlights
|
||||
|
||||
### Basic Remotion composition
|
||||
|
||||
```tsx
|
||||
import { AbsoluteFill, Sequence, Video, useCurrentFrame } from "remotion";
|
||||
|
||||
export const VlogComposition: React.FC = () => {
|
||||
const frame = useCurrentFrame();
|
||||
|
||||
return (
|
||||
<AbsoluteFill>
|
||||
{/* Main footage */}
|
||||
<Sequence from={0} durationInFrames={300}>
|
||||
<Video src="/segments/intro.mp4" />
|
||||
</Sequence>
|
||||
|
||||
{/* Title overlay */}
|
||||
<Sequence from={30} durationInFrames={90}>
|
||||
<AbsoluteFill style={{
|
||||
justifyContent: "center",
|
||||
alignItems: "center",
|
||||
}}>
|
||||
<h1 style={{
|
||||
fontSize: 72,
|
||||
color: "white",
|
||||
textShadow: "2px 2px 8px rgba(0,0,0,0.8)",
|
||||
}}>
|
||||
The AI Editing Stack
|
||||
</h1>
|
||||
</AbsoluteFill>
|
||||
</Sequence>
|
||||
|
||||
{/* Next segment */}
|
||||
<Sequence from={300} durationInFrames={450}>
|
||||
<Video src="/segments/demo.mp4" />
|
||||
</Sequence>
|
||||
</AbsoluteFill>
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
### Render output
|
||||
|
||||
```bash
|
||||
npx remotion render src/index.ts VlogComposition output.mp4
|
||||
```
|
||||
|
||||
See the [Remotion docs](https://www.remotion.dev/docs) for detailed patterns and API reference.
|
||||
|
||||
## Layer 5: Generated Assets (ElevenLabs / fal.ai)
|
||||
|
||||
Generate only what you need. Do not generate the whole video.
|
||||
|
||||
### Voiceover with ElevenLabs
|
||||
|
||||
```python
|
||||
import os
|
||||
import requests
|
||||
|
||||
resp = requests.post(
|
||||
f"https://api.elevenlabs.io/v1/text-to-speech/{voice_id}",
|
||||
headers={
|
||||
"xi-api-key": os.environ["ELEVENLABS_API_KEY"],
|
||||
"Content-Type": "application/json"
|
||||
},
|
||||
json={
|
||||
"text": "Your narration text here",
|
||||
"model_id": "eleven_turbo_v2_5",
|
||||
"voice_settings": {"stability": 0.5, "similarity_boost": 0.75}
|
||||
}
|
||||
)
|
||||
with open("voiceover.mp3", "wb") as f:
|
||||
f.write(resp.content)
|
||||
```
|
||||
|
||||
### Music and SFX with fal.ai
|
||||
|
||||
Use the `fal-ai-media` skill for:
|
||||
- Background music generation
|
||||
- Sound effects (ThinkSound model for video-to-audio)
|
||||
- Transition sounds
|
||||
|
||||
### Generated visuals with fal.ai
|
||||
|
||||
Use for insert shots, thumbnails, or b-roll that doesn't exist:
|
||||
```
|
||||
generate(app_id: "fal-ai/nano-banana-pro", input_data: {
|
||||
"prompt": "professional thumbnail for tech vlog, dark background, code on screen",
|
||||
"image_size": "landscape_16_9"
|
||||
})
|
||||
```
|
||||
|
||||
### VideoDB generative audio
|
||||
|
||||
If VideoDB is configured:
|
||||
```python
|
||||
voiceover = coll.generate_voice(text="Narration here", voice="alloy")
|
||||
music = coll.generate_music(prompt="lo-fi background for coding vlog", duration=120)
|
||||
sfx = coll.generate_sound_effect(prompt="subtle whoosh transition")
|
||||
```
|
||||
|
||||
## Layer 6: Final Polish (Descript / CapCut)
|
||||
|
||||
The last layer is human. Use a traditional editor for:
|
||||
- **Pacing**: adjust cuts that feel too fast or slow
|
||||
- **Captions**: auto-generated, then manually cleaned
|
||||
- **Color grading**: basic correction and mood
|
||||
- **Final audio mix**: balance voice, music, and SFX levels
|
||||
- **Export**: platform-specific formats and quality settings
|
||||
|
||||
This is where taste lives. AI clears the repetitive work. You make the final calls.
|
||||
|
||||
## Social Media Reframing
|
||||
|
||||
Different platforms need different aspect ratios:
|
||||
|
||||
| Platform | Aspect Ratio | Resolution |
|
||||
|----------|-------------|------------|
|
||||
| YouTube | 16:9 | 1920x1080 |
|
||||
| TikTok / Reels | 9:16 | 1080x1920 |
|
||||
| Instagram Feed | 1:1 | 1080x1080 |
|
||||
| X / Twitter | 16:9 or 1:1 | 1280x720 or 720x720 |
|
||||
|
||||
### Reframe with FFmpeg
|
||||
|
||||
```bash
|
||||
# 16:9 to 9:16 (center crop)
|
||||
ffmpeg -i input.mp4 -vf "crop=ih*9/16:ih,scale=1080:1920" vertical.mp4
|
||||
|
||||
# 16:9 to 1:1 (center crop)
|
||||
ffmpeg -i input.mp4 -vf "crop=ih:ih,scale=1080:1080" square.mp4
|
||||
```
|
||||
|
||||
### Reframe with VideoDB
|
||||
|
||||
```python
|
||||
from videodb import ReframeMode
|
||||
|
||||
# Smart reframe (AI-guided subject tracking)
|
||||
reframed = video.reframe(start=0, end=60, target="vertical", mode=ReframeMode.smart)
|
||||
```
|
||||
|
||||
## Scene Detection and Auto-Cut
|
||||
|
||||
### FFmpeg scene detection
|
||||
|
||||
```bash
|
||||
# Detect scene changes (threshold 0.3 = moderate sensitivity)
|
||||
ffmpeg -i input.mp4 -vf "select='gt(scene,0.3)',showinfo" -vsync vfr -f null - 2>&1 | grep showinfo
|
||||
```
|
||||
|
||||
### Silence detection for auto-cut
|
||||
|
||||
```bash
|
||||
# Find silent segments (useful for cutting dead air)
|
||||
ffmpeg -i input.mp4 -af silencedetect=noise=-30dB:d=2 -f null - 2>&1 | grep silence
|
||||
```
|
||||
|
||||
### Highlight extraction
|
||||
|
||||
Use Claude to analyze transcript + scene timestamps:
|
||||
```
|
||||
"Given this transcript with timestamps and these scene change points,
|
||||
identify the 5 most engaging 30-second clips for social media."
|
||||
```
|
||||
|
||||
## What Each Tool Does Best
|
||||
|
||||
| Tool | Strength | Weakness |
|
||||
|------|----------|----------|
|
||||
| Claude / Codex | Organization, planning, code generation | Not the creative taste layer |
|
||||
| FFmpeg | Deterministic cuts, batch processing, format conversion | No visual editing UI |
|
||||
| Remotion | Programmable overlays, composable scenes, reusable templates | Learning curve for non-devs |
|
||||
| Screen Studio | Polished screen recordings immediately | Only screen capture |
|
||||
| ElevenLabs | Voice, narration, music, SFX | Not the center of the workflow |
|
||||
| Descript / CapCut | Final pacing, captions, polish | Manual, not automatable |
|
||||
|
||||
## Key Principles
|
||||
|
||||
1. **Edit, don't generate.** This workflow is for cutting real footage, not creating from prompts.
|
||||
2. **Structure before style.** Get the story right in Layer 2 before touching anything visual.
|
||||
3. **FFmpeg is the backbone.** Boring but critical. Where long footage becomes manageable.
|
||||
4. **Remotion for repeatability.** If you'll do it more than once, make it a Remotion component.
|
||||
5. **Generate selectively.** Only use AI generation for assets that don't exist, not for everything.
|
||||
6. **Taste is the last layer.** AI clears repetitive work. You make the final creative calls.
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `fal-ai-media` — AI image, video, and audio generation
|
||||
- `videodb` — Server-side video processing, indexing, and streaming
|
||||
- `content-engine` — Platform-native content distribution
|
||||
@@ -108,7 +108,7 @@ The user must set `VIDEO_DB_API_KEY` using **either** method:
|
||||
- **Export in terminal** (before starting Claude): `export VIDEO_DB_API_KEY=your-key`
|
||||
- **Project `.env` file**: Save `VIDEO_DB_API_KEY=your-key` in the project's `.env` file
|
||||
|
||||
Get a free API key at https://console.videodb.io (50 free uploads, no credit card).
|
||||
Get a free API key at [console.videodb.io](https://console.videodb.io) (50 free uploads, no credit card).
|
||||
|
||||
**Do NOT** read, write, or handle the API key yourself. Always let the user set it.
|
||||
|
||||
@@ -354,7 +354,6 @@ Reference documentation is in the `reference/` directory adjacent to this SKILL.
|
||||
- [reference/capture-reference.md](reference/capture-reference.md) - Capture SDK and WebSocket events
|
||||
- [reference/use-cases.md](reference/use-cases.md) - Common video processing patterns and examples
|
||||
|
||||
|
||||
**Do not use ffmpeg, moviepy, or local encoding tools** when VideoDB supports the operation. The following are all handled server-side by VideoDB — trimming, combining clips, overlaying audio or music, adding subtitles, text/image overlays, transcoding, resolution changes, aspect-ratio conversion, resizing for platform requirements, transcription, and media generation. Only fall back to local tools for operations listed under Limitations in reference/editor.md (transitions, speed changes, crop/zoom, colour grading, volume mixing).
|
||||
|
||||
### When to use what
|
||||
|
||||
@@ -380,7 +380,7 @@ results = video.search(
|
||||
```
|
||||
|
||||
> **Note:** `filter` is an explicit named parameter in `video.search()`. `scene_index_id` is passed through `**kwargs` to the API.
|
||||
|
||||
>
|
||||
> **Important:** `video.search()` raises `InvalidRequestError` with message `"No results found"` when there are no matches. Always wrap search calls in try/except. For scene search, use `score_threshold=0.3` or higher to filter low-relevance noise.
|
||||
|
||||
For scene search, use `search_type=SearchType.semantic` with `index_type=IndexType.scene`. Pass `scene_index_id` when targeting a specific scene index. See [search.md](search.md) for details.
|
||||
|
||||
@@ -107,7 +107,7 @@ Use [scripts/ws_listener.py](../scripts/ws_listener.py) to connect and dump even
|
||||
}
|
||||
```
|
||||
|
||||
> For latest details, see https://docs.videodb.io/pages/ingest/capture-sdks/realtime-context.md
|
||||
> For latest details, see [VideoDB Realtime Context docs](https://docs.videodb.io/pages/ingest/capture-sdks/realtime-context.md).
|
||||
|
||||
---
|
||||
|
||||
|
||||
209
skills/x-api/SKILL.md
Normal file
209
skills/x-api/SKILL.md
Normal file
@@ -0,0 +1,209 @@
|
||||
---
|
||||
name: x-api
|
||||
description: X/Twitter API integration for posting tweets, threads, reading timelines, search, and analytics. Covers OAuth auth patterns, rate limits, and platform-native content posting. Use when the user wants to interact with X programmatically.
|
||||
origin: ECC
|
||||
---
|
||||
|
||||
# X API
|
||||
|
||||
Programmatic interaction with X (Twitter) for posting, reading, searching, and analytics.
|
||||
|
||||
## When to Activate
|
||||
|
||||
- User wants to post tweets or threads programmatically
|
||||
- Reading timeline, mentions, or user data from X
|
||||
- Searching X for content, trends, or conversations
|
||||
- Building X integrations or bots
|
||||
- Analytics and engagement tracking
|
||||
- User says "post to X", "tweet", "X API", or "Twitter API"
|
||||
|
||||
## Authentication
|
||||
|
||||
### OAuth 2.0 Bearer Token (App-Only)
|
||||
|
||||
Best for: read-heavy operations, search, public data.
|
||||
|
||||
```bash
|
||||
# Environment setup
|
||||
export X_BEARER_TOKEN="your-bearer-token"
|
||||
```
|
||||
|
||||
```python
|
||||
import os
|
||||
import requests
|
||||
|
||||
bearer = os.environ["X_BEARER_TOKEN"]
|
||||
headers = {"Authorization": f"Bearer {bearer}"}
|
||||
|
||||
# Search recent tweets
|
||||
resp = requests.get(
|
||||
"https://api.x.com/2/tweets/search/recent",
|
||||
headers=headers,
|
||||
params={"query": "claude code", "max_results": 10}
|
||||
)
|
||||
tweets = resp.json()
|
||||
```
|
||||
|
||||
### OAuth 1.0a (User Context)
|
||||
|
||||
Required for: posting tweets, managing account, DMs.
|
||||
|
||||
```bash
|
||||
# Environment setup — source before use
|
||||
export X_API_KEY="your-api-key"
|
||||
export X_API_SECRET="your-api-secret"
|
||||
export X_ACCESS_TOKEN="your-access-token"
|
||||
export X_ACCESS_SECRET="your-access-secret"
|
||||
```
|
||||
|
||||
```python
|
||||
import os
|
||||
from requests_oauthlib import OAuth1Session
|
||||
|
||||
oauth = OAuth1Session(
|
||||
os.environ["X_API_KEY"],
|
||||
client_secret=os.environ["X_API_SECRET"],
|
||||
resource_owner_key=os.environ["X_ACCESS_TOKEN"],
|
||||
resource_owner_secret=os.environ["X_ACCESS_SECRET"],
|
||||
)
|
||||
```
|
||||
|
||||
## Core Operations
|
||||
|
||||
### Post a Tweet
|
||||
|
||||
```python
|
||||
resp = oauth.post(
|
||||
"https://api.x.com/2/tweets",
|
||||
json={"text": "Hello from Claude Code"}
|
||||
)
|
||||
resp.raise_for_status()
|
||||
tweet_id = resp.json()["data"]["id"]
|
||||
```
|
||||
|
||||
### Post a Thread
|
||||
|
||||
```python
|
||||
def post_thread(oauth, tweets: list[str]) -> list[str]:
|
||||
ids = []
|
||||
reply_to = None
|
||||
for text in tweets:
|
||||
payload = {"text": text}
|
||||
if reply_to:
|
||||
payload["reply"] = {"in_reply_to_tweet_id": reply_to}
|
||||
resp = oauth.post("https://api.x.com/2/tweets", json=payload)
|
||||
resp.raise_for_status()
|
||||
tweet_id = resp.json()["data"]["id"]
|
||||
ids.append(tweet_id)
|
||||
reply_to = tweet_id
|
||||
return ids
|
||||
```
|
||||
|
||||
### Read User Timeline
|
||||
|
||||
```python
|
||||
resp = requests.get(
|
||||
f"https://api.x.com/2/users/{user_id}/tweets",
|
||||
headers=headers,
|
||||
params={
|
||||
"max_results": 10,
|
||||
"tweet.fields": "created_at,public_metrics",
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Search Tweets
|
||||
|
||||
```python
|
||||
resp = requests.get(
|
||||
"https://api.x.com/2/tweets/search/recent",
|
||||
headers=headers,
|
||||
params={
|
||||
"query": "from:affaanmustafa -is:retweet",
|
||||
"max_results": 10,
|
||||
"tweet.fields": "public_metrics,created_at",
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Get User by Username
|
||||
|
||||
```python
|
||||
resp = requests.get(
|
||||
"https://api.x.com/2/users/by/username/affaanmustafa",
|
||||
headers=headers,
|
||||
params={"user.fields": "public_metrics,description,created_at"}
|
||||
)
|
||||
```
|
||||
|
||||
### Upload Media and Post
|
||||
|
||||
```python
|
||||
# Media upload uses v1.1 endpoint
|
||||
|
||||
# Step 1: Upload media
|
||||
media_resp = oauth.post(
|
||||
"https://upload.twitter.com/1.1/media/upload.json",
|
||||
files={"media": open("image.png", "rb")}
|
||||
)
|
||||
media_id = media_resp.json()["media_id_string"]
|
||||
|
||||
# Step 2: Post with media
|
||||
resp = oauth.post(
|
||||
"https://api.x.com/2/tweets",
|
||||
json={"text": "Check this out", "media": {"media_ids": [media_id]}}
|
||||
)
|
||||
```
|
||||
|
||||
## Rate Limits
|
||||
|
||||
X API rate limits vary by endpoint, auth method, and account tier, and they change over time. Always:
|
||||
- Check the current X developer docs before hardcoding assumptions
|
||||
- Read `x-rate-limit-remaining` and `x-rate-limit-reset` headers at runtime
|
||||
- Back off automatically instead of relying on static tables in code
|
||||
|
||||
```python
|
||||
import time
|
||||
|
||||
remaining = int(resp.headers.get("x-rate-limit-remaining", 0))
|
||||
if remaining < 5:
|
||||
reset = int(resp.headers.get("x-rate-limit-reset", 0))
|
||||
wait = max(0, reset - int(time.time()))
|
||||
print(f"Rate limit approaching. Resets in {wait}s")
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
```python
|
||||
resp = oauth.post("https://api.x.com/2/tweets", json={"text": content})
|
||||
if resp.status_code == 201:
|
||||
return resp.json()["data"]["id"]
|
||||
elif resp.status_code == 429:
|
||||
reset = int(resp.headers["x-rate-limit-reset"])
|
||||
raise Exception(f"Rate limited. Resets at {reset}")
|
||||
elif resp.status_code == 403:
|
||||
raise Exception(f"Forbidden: {resp.json().get('detail', 'check permissions')}")
|
||||
else:
|
||||
raise Exception(f"X API error {resp.status_code}: {resp.text}")
|
||||
```
|
||||
|
||||
## Security
|
||||
|
||||
- **Never hardcode tokens.** Use environment variables or `.env` files.
|
||||
- **Never commit `.env` files.** Add to `.gitignore`.
|
||||
- **Rotate tokens** if exposed. Regenerate at developer.x.com.
|
||||
- **Use read-only tokens** when write access is not needed.
|
||||
- **Store OAuth secrets securely** — not in source code or logs.
|
||||
|
||||
## Integration with Content Engine
|
||||
|
||||
Use `content-engine` skill to generate platform-native content, then post via X API:
|
||||
1. Generate content with content-engine (X platform format)
|
||||
2. Validate length (280 chars for single tweet)
|
||||
3. Post via X API using patterns above
|
||||
4. Track engagement via public_metrics
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `content-engine` — Generate platform-native content for X
|
||||
- `crosspost` — Distribute content across X, LinkedIn, and other platforms
|
||||
Reference in New Issue
Block a user