@heytherevibin/skillforge 0.2.1

package/skills/workspace-surface-audit/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: workspace-surface-audit
+description: Audit the active repo, MCP servers, plugins, connectors, env surfaces, and harness setup, then recommend the highest-value the toolset-native skills, hooks, agents, and operator workflows. Use when the user wants help setting up Claude Code or understanding what capabilities are actually available in their environment.
+---
+
+# Workspace Surface Audit
+
+Read-only audit skill for answering the question "what can this workspace and machine actually do right now, and what should we add or enable next?"
+
+This is the the toolset-native answer to setup-audit plugins. It does not modify files unless the user explicitly asks for follow-up implementation.
+
+## When to Use
+
+- User says "set up Claude Code", "recommend automations", "what plugins or MCPs should I use?", or "what am I missing?"
+- Auditing a machine or repo before installing more skills, hooks, or connectors
+- Comparing official marketplace plugins against the toolset-native coverage
+- Reviewing `.env`, `.mcp.json`, plugin settings, or connected-app surfaces to find missing workflow layers
+- Deciding whether a capability should be a skill, hook, agent, MCP, or external connector
+
+## Non-Negotiable Rules
+
+- Never print secret values. Surface only provider names, capability names, file paths, and whether a key or config exists.
+- Prefer the toolset-native workflows over generic "install another plugin" advice when the toolset can reasonably own the surface.
+- Treat external plugins as benchmarks and inspiration, not authoritative product boundaries.
+- Separate three things clearly:
+  - already available now
+  - available but not wrapped well in the toolset
+  - not available and would require a new integration
+
+## Audit Inputs
+
+Inspect only the files and settings needed to answer the question well:
+
+1. Repo surface
+   - `package.json`, lockfiles, language markers, framework config, `README.md`
+   - `.mcp.json`, `.lsp.json`, `.claude/settings*.json`, `.codex/*`
+   - `AGENTS.md`, `CLAUDE.md`, install manifests, hook configs
+2. Environment surface
+   - `.env*` files in the active repo and obvious adjacent the toolset workspaces
+   - Surface only key names such as `STRIPE_API_KEY`, `TWILIO_AUTH_TOKEN`, `FAL_KEY`
+3. Connected tool surface
+   - Installed plugins, enabled connectors, MCP servers, LSPs, and app integrations
+4. the toolset surface
+   - Existing skills, commands, hooks, agents, and install modules that already cover the need
+
+## Audit Process
+
+### Phase 1: Inventory What Exists
+
+Produce a compact inventory:
+
+- active harness targets
+- installed plugins and connected apps
+- configured MCP servers
+- configured LSP servers
+- env-backed services implied by key names
+- existing the toolset skills already relevant to the workspace
+
+If a surface exists only as a primitive, call that out. Example:
+
+- "Stripe is available via connected app, but the toolset lacks a billing-operator skill"
+- "Google Drive is connected, but there is no the toolset-native Google Workspace operator workflow"
+
+### Phase 2: Benchmark Against Official and Installed Surfaces
+
+Compare the workspace against:
+
+- official Claude plugins that overlap with setup, review, docs, design, or workflow quality
+- locally installed plugins in Claude or Codex
+- the user's currently connected app surfaces
+
+Do not just list names. For each comparison, answer:
+
+1. what they actually do
+2. whether the toolset already has parity
+3. whether the toolset only has primitives
+4. whether the toolset is missing the workflow entirely
+
+### Phase 3: Turn Gaps Into the toolset Decisions
+
+For every real gap, recommend the correct the toolset-native shape:
+
+| Gap Type | Preferred the toolset Shape |
+|----------|---------------------|
+| Repeatable operator workflow | Skill |
+| Automatic enforcement or side-effect | Hook |
+| Specialized delegated role | Agent |
+| External tool bridge | MCP server or connector |
+| Install/bootstrap guidance | Setup or audit skill |
+
+Default to user-facing skills that orchestrate existing tools when the need is operational rather than infrastructural.
+
+## Output Format
+
+Return five sections in this order:
+
+1. **Current surface**
+   - what is already usable right now
+2. **Parity**
+   - where the toolset already matches or exceeds the benchmark
+3. **Primitive-only gaps**
+   - tools exist, but the toolset lacks a clean operator skill
+4. **Missing integrations**
+   - capability not available yet
+5. **Top 3-5 next moves**
+   - concrete the toolset-native additions, ordered by impact
+
+## Recommendation Rules
+
+- Recommend at most 1-2 highest-value ideas per category.
+- Favor skills with obvious user intent and business value:
+  - setup audit
+  - billing/customer ops
+  - issue/program ops
+  - Google Workspace ops
+  - deployment/ops control
+- If a connector is company-specific, recommend it only when it is genuinely available or clearly useful to the user's workflow.
+- If the toolset already has a strong primitive, propose a wrapper skill instead of inventing a brand-new subsystem.
+
+## Good Outcomes
+
+- The user can immediately see what is connected, what is missing, and what the toolset should own next.
+- Recommendations are specific enough to implement in the repo without another discovery pass.
+- The final answer is organized around workflows, not API brands.

package/skills/x-api/SKILL.md

@@ -0,0 +1,233 @@
+---
+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.
+---
+
+# X API
+
+> **Drift-prone skill.** X API endpoints, access tiers, quotas, and write
+> permissions change frequently. Verify current developer docs and account
+> access before quoting rate limits or implementing a posting/search flow.
+
+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, and any write flow.
+
+```bash
+# Environment setup — source before use
+export X_CONSUMER_KEY="your-consumer-key"
+export X_CONSUMER_SECRET="your-consumer-secret"
+export X_ACCESS_TOKEN="your-access-token"
+export X_ACCESS_TOKEN_SECRET="your-access-token-secret"
+```
+
+Legacy aliases such as `X_API_KEY`, `X_API_SECRET`, and `X_ACCESS_SECRET` may exist in older setups. Prefer the `X_CONSUMER_*` and `X_ACCESS_TOKEN_SECRET` names when documenting or wiring new flows.
+
+```python
+import os
+from requests_oauthlib import OAuth1Session
+
+oauth = OAuth1Session(
+    os.environ["X_CONSUMER_KEY"],
+    client_secret=os.environ["X_CONSUMER_SECRET"],
+    resource_owner_key=os.environ["X_ACCESS_TOKEN"],
+    resource_owner_secret=os.environ["X_ACCESS_TOKEN_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)
+        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:example_user -is:retweet",
+        "max_results": 10,
+        "tweet.fields": "public_metrics,created_at",
+    }
+)
+```
+
+### Pull Recent Original Posts for Voice Modeling
+
+```python
+resp = requests.get(
+    "https://api.x.com/2/tweets/search/recent",
+    headers=headers,
+    params={
+        "query": "from:example_user -is:retweet -is:reply",
+        "max_results": 25,
+        "tweet.fields": "created_at,public_metrics",
+    }
+)
+voice_samples = resp.json()
+```
+
+### Get User by Username
+
+```python
+resp = requests.get(
+    "https://api.x.com/2/users/by/username/example_user",
+    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 `brand-voice` plus `content-engine` to generate platform-native content, then post via X API:
+1. Pull recent original posts when voice matching matters
+2. Build or reuse a `VOICE PROFILE`
+3. Generate content with `content-engine` in X-native format
+4. Validate length and thread structure
+5. Return the draft for approval unless the user explicitly asked to post now
+6. Post via X API only after approval
+7. Track engagement via public_metrics
+
+## Related Skills
+
+- `brand-voice` — Build a reusable voice profile from real X and site/source material
+- `content-engine` — Generate platform-native content for X
+- `crosspost` — Distribute content across X, LinkedIn, and other platforms
+- `connections-optimizer` — Reorganize the X graph before drafting network-driven outreach