From 933cc6c77f3a6ff67defe05bb350ef1ef52981a6 Mon Sep 17 00:00:00 2001 From: farizanjum Date: Sat, 17 Oct 2026 12:01:59 +0530 Subject: [PATCH 01/13] chore(mcp): add Mintlify MCP server config and build:docs script --- .mcp.json | 7 +++++++ package.json | 4 +++- 2 files changed, 10 insertions(+), 1 deletion(-) create mode 100644 .mcp.json diff --git a/.mcp.json b/.mcp.json new file mode 100644 index 0000000..c892c6e --- /dev/null +++ b/.mcp.json @@ -0,0 +1,7 @@ +{ + "mcpServers": { + "Mintlify": { + "url": "https://mcp.mintlify.com" + } + } +} diff --git a/package.json b/package.json index f91f10f..f358002 100644 --- a/package.json +++ b/package.json @@ -5,6 +5,7 @@ "scripts": { "test": "vitest", "build:plugin": "tsx scripts/build-claude-plugin.ts", + "build:docs": "tsx scripts/build-mintlify-docs.ts", "prepare": "husky" }, "devDependencies": { @@ -30,7 +31,8 @@ "skills/**": [ "tsx scripts/update-readme.ts", "tsx scripts/update-contributing.ts", - "git add README.md CONTRIBUTING.md" + "tsx scripts/build-mintlify-docs.ts", + "git add README.md CONTRIBUTING.md docs" ] } } From 98d4c1c9be35299b46f62e0fb00db79fc3229454 Mon Sep 17 00:00:00 2001 From: farizanjum Date: Sat, 17 Oct 2026 12:02:03 +0530 Subject: [PATCH 02/13] feat(docs): add Mintlify MDX generator and sync script --- scripts/build-mintlify-docs.ts | 528 +++++++++++++++++++++++++++++++++ 1 file changed, 528 insertions(+) create mode 100644 scripts/build-mintlify-docs.ts diff --git a/scripts/build-mintlify-docs.ts b/scripts/build-mintlify-docs.ts new file mode 100644 index 0000000..9ab5406 --- /dev/null +++ b/scripts/build-mintlify-docs.ts @@ -0,0 +1,528 @@ +import fs from 'node:fs'; +import path from 'node:path'; +import { inspectSkillFrontmatter } from '../packages/cli/src/frontmatter'; +import { findSkillSourceSync } from '../packages/cli/src/skill-discovery'; + +const ROOT_DIR = path.resolve(__dirname, '..'); +const SKILLS_DIR = path.join(ROOT_DIR, 'skills'); +const REGISTRY_PATH = path.join(ROOT_DIR, 'packages', 'cli', 'registry.json'); +const CONTRIBUTING_PATH = path.join(ROOT_DIR, 'CONTRIBUTING.md'); +const DOCS_DIR = path.join(ROOT_DIR, 'docs'); +const DOCS_SKILLS_DIR = path.join(DOCS_DIR, 'skills'); +const DOCS_JSON_PATH = path.join(DOCS_DIR, 'docs.json'); + +interface SkillEntry { + name: string; + description: string; + version: string; + author: string; + compatibility: string; + category: string; + categorySlug: string; + docRoute: string; +} + +const CATEGORY_ORDER = [ + 'Visual & Media', + 'Content', + 'Launch', + 'GTM Intelligence', + 'Outreach', + 'Research', + 'Developer Tools', + 'Other', +]; + +const TAG_TO_CATEGORY: Record = { + 'AI': 'Developer Tools', + 'Branding': 'Launch', + 'Copywriting': 'Content', + 'Developer Tools': 'Developer Tools', + 'Email': 'Outreach', + 'Marketing': 'GTM Intelligence', + 'SEO': 'Research', + 'Social Media': 'Content', +}; + +const ALLOWED_HTML_TAGS = new Set([ + 'a', 'b', 'i', 'u', 's', 'em', 'strong', 'sub', 'sup', 'code', 'pre', + 'div', 'span', 'p', 'br', 'hr', 'img', 'video', 'picture', 'source', + 'table', 'thead', 'tbody', 'tfoot', 'tr', 'th', 'td', 'ul', 'ol', 'li', + 'dl', 'dt', 'dd', 'details', 'summary', 'blockquote', 'h1', 'h2', 'h3', + 'h4', 'h5', 'h6', 'kbd', 'mark', 'small', + 'Info', 'Note', 'Tip', 'Warning', 'Check', 'Tabs', 'Tab', 'Card', + 'CardGroup', 'Steps', 'Step', 'Frame', 'Accordion', 'AccordionGroup', + 'CodeGroup', 'Callout', +]); + +function categoryToSlug(category: string): string { + return category + .toLowerCase() + .replace(/&/g, 'and') + .replace(/[^a-z0-9]+/g, '-') + .replace(/^-+|-+$/g, ''); +} + +function getCategoryFromPkg(skillDir: string): string | null { + const pkgPath = path.join(skillDir, 'package.json'); + if (!fs.existsSync(pkgPath)) return null; + try { + const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')); + if (typeof pkg.category === 'string' && pkg.category.trim()) { + return pkg.category.trim(); + } + } catch (_) {} + return null; +} + +function detectCategoryFromContent(name: string, description: string): string { + const n = name.toLowerCase(); + const text = (name + ' ' + description).toLowerCase(); + + if (/^(vid-|graphic-|blog-cover-image)/.test(n)) return 'Visual & Media'; + if (/^(email-newsletter|cook-the-blog|noise2blog|human-tone|linkedin-post|tweet-thread|noise-to-linkedin|newsletter)/.test(n)) return 'Content'; + if (/^(producthunt|show-hn|oss-launch|brand-alchemy|product-update-logger)/.test(n)) return 'Launch'; + if (/^(hackernews|reddit-icp|reddit-post|npm-downloads|yc-intent|twitter-gtm|sdk-adoption|gh-issue|map-your-market|competitor-pr|google-trends|meta-ads|meta-tribe|company-radar)/.test(n)) return 'GTM Intelligence'; + if (/^(outreach-sequence|cold-email)/.test(n)) return 'Outreach'; + if (/^(pricing-|position-me|meeting-brief|linkedin-job-post|where-your-customer|vc-)/.test(n)) return 'Research'; + if (/^(kill-the-standup|dependency-update|docs-from-code|pr-description|explain-this-pr|claude-md|llms-txt|schema-markup)/.test(n)) return 'Developer Tools'; + + if (/\b(gif|mp4|motion.graphic|animation|slide.?deck|e.?book|cover.image|chart|graphic|png|video)\b/.test(text)) return 'Visual & Media'; + if (/pull.request|\bstandup\b|\bdependency\b|llms\.txt|json.?ld|schema.markup|claude\.md|agents\.md|codebase.scan|docs.from.code/.test(text)) return 'Developer Tools'; + if (/product.hunt|show.hn|\boss.launch\b|\bbrand.strateg|\bnaming.expert\b|\blaunch.kit\b|\bproduct.update\b/.test(text)) return 'Launch'; + if (/cold.email|outreach.sequence|email.verif/.test(text)) return 'Outreach'; + if (/pricing.page|venture.capital|\binvestor\b|\bvc\b|buyer.pain|pre.call.brief|where.*customer|icp.*channel/.test(text)) return 'Research'; + if (/hacker.news|npm.*download|yc.*startup|sdk.*adopt|google.trends|meta.ads|demand.signal|competitor.*pr|map.*market|\bgtm\b|tribe.v2|reddit.*monitor|twitter.*gtm/.test(text)) return 'GTM Intelligence'; + if (/\breddit\b|\bblog\b|newsletter|linkedin.post|carousel|tweet.thread/.test(text)) return 'Content'; + return 'Other'; +} + +function getCategory(name: string, description: string, tags?: string[], skillDir?: string): string { + if (skillDir) { + const pkg = getCategoryFromPkg(skillDir); + if (pkg) return pkg; + } + const fromContent = detectCategoryFromContent(name, description); + if (fromContent !== 'Other') return fromContent; + if (tags && tags.length > 0) { + for (const tag of tags) { + if (TAG_TO_CATEGORY[tag]) return TAG_TO_CATEGORY[tag]; + } + } + return 'Other'; +} + +function extractReadmeDescription(skillDir: string): string { + const readmePath = path.join(skillDir, 'README.md'); + if (!fs.existsSync(readmePath)) return ''; + + const content = fs.readFileSync(readmePath, 'utf-8'); + const lines = content.split('\n'); + + for (const line of lines) { + const trimmed = line.trim().replace(/^\uFEFF/, ''); + if (!trimmed) continue; + if (trimmed.startsWith('#')) continue; + if (trimmed.startsWith('<')) continue; + if (trimmed.startsWith('![')) continue; + if (trimmed.startsWith('```')) continue; + if (trimmed.startsWith('---')) continue; + if (trimmed.startsWith('[![')) continue; + if (trimmed.startsWith('| ')) continue; + if (trimmed === '**') continue; + if (trimmed.startsWith('> ')) { + const text = trimmed.slice(2).trim().replace(/\*\*/g, '').replace(/`/g, ''); + if (text.length > 20) return sanitizePlainText(text); + } + if (trimmed.length > 20) { + return sanitizePlainText(trimmed.replace(/\*\*/g, '').replace(/`/g, '')); + } + } + return ''; +} + +function sanitizePlainText(raw: string): string { + return raw + .replace(/]*>/gm, '') + .replace(/!\[.*?\]\(.*?\)/g, '') + .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1') + .replace(/(\*\*|__|\*|_)/g, '') + .replace(/`/g, '') + .replace(/\r?\n/g, ' ') + .trim(); +} + +function buildInstallTabsMdx(skillName: string): string { + const githubUrl = encodeURIComponent(`https://github.com/Varnan-Tech/opendirectory/tree/main/skills/${skillName}`); + const manusUrl = `https://manus.im/import-skills?githubUrl=${githubUrl}&utm_source=opendirectory`; + + return ` + + \`\`\`bash + npx "@opendirectory.dev/skills" install ${skillName} --target claude + \`\`\` + + + \`\`\`bash + npx skills add Varnan-Tech/opendirectory --skill ${skillName} + \`\`\` + + + \`\`\`bash + /plugin marketplace add Varnan-Tech/opendirectory + /plugin install opendirectory-gtm-skills@opendirectory-marketplace + \`\`\` + + + 1. Copy \`https://github.com/Varnan-Tech/opendirectory/tree/main/skills/${skillName}\` into [download-directory.github.io](https://download-directory.github.io/) to download the ZIP. + 2. Open **Claude Desktop** -> **Customize** -> **Skills** -> **+** -> **Upload a skill** and drop the folder containing \`SKILL.md\`. + + + [**Install ${skillName} in Manus AI**](${manusUrl}) + +`; +} + +/** + * Sanitizes a single line of Markdown (outside fenced code blocks) so that + * Mintlify's strict MDX v2/v3 parser never fails on unescaped `{`, `}`, `<`, + * or non-self-closed HTML void tags. + */ +function sanitizeNonCodeLine(line: string, skillRouteMap: Map): string { + // Rewrite relative links to other skills: (../skill-name) or (../skill-name/...) + let updated = line.replace(/\]\(\.\.\/([a-zA-Z0-9_-]+)\/?\)/g, (full, targetSkill) => { + const route = skillRouteMap.get(targetSkill); + return route ? `](/${route})` : full; + }); + + // Self-close void HTML tags (,
,
, ) + updated = updated.replace(/<(img|source)\b([^>]*?)(?/gi, '<$1$2 />'); + updated = updated.replace(//gi, '
'); + updated = updated.replace(//gi, '
'); + + // Split by inline code spans (`...`) so we never touch characters inside backticks + const segments = updated.split(/(`+[^`]*`+)/g); + for (let i = 0; i < segments.length; i++) { + if (i % 2 === 1) continue; // inside inline code span + let seg = segments[i]; + + // Escape { and } in regular text + seg = seg.replace(/\{/g, '\\{').replace(/\}/g, '\\}'); + + // Escape bare < that are not valid HTML/MDX tags + seg = seg.replace(/<(\/?)([a-zA-Z0-9_-]+)?([^>]*>)?/g, (match, slash, tagName, rest) => { + if (tagName && rest !== undefined && ALLOWED_HTML_TAGS.has(tagName)) { + return match; + } + return '<' + match.slice(1); + }); + + segments[i] = seg; + } + + return segments.join(''); +} + +function convertMarkdownToMdxBody( + rawMarkdown: string, + skillRouteMap: Map, + stripFirstH1 = true, +): string { + let content = rawMarkdown.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n'); + + // Strip YAML frontmatter if any exists in README + if (content.startsWith('---\n')) { + const endIdx = content.indexOf('\n---\n', 4); + if (endIdx !== -1) { + content = content.slice(endIdx + 5); + } + } + + // Extract managed install block and replace with a placeholder before line-by-line sanitization + const installPlaceholder = '___MINTLIFY_INSTALL_TABS_PLACEHOLDER___'; + content = content.replace( + /[\s\S]*?/g, + installPlaceholder, + ); + + // Strip any remaining HTML comments + content = content.replace(//g, ''); + + const lines = content.split('\n'); + const outLines: string[] = []; + let inCodeFence = false; + let fenceMarker = ''; + let h1Stripped = !stripFirstH1; + + for (const line of lines) { + const trimmed = line.trim(); + + // Detect code fence start/end + const fenceMatch = trimmed.match(/^(`{3,}|~{3,})/); + if (fenceMatch) { + if (!inCodeFence) { + inCodeFence = true; + fenceMarker = fenceMatch[1][0].repeat(fenceMatch[1].length); + } else if (trimmed.startsWith(fenceMarker[0].repeat(fenceMarker.length))) { + inCodeFence = false; + fenceMarker = ''; + } + outLines.push(line); + continue; + } + + if (inCodeFence) { + outLines.push(line); + continue; + } + + if (!h1Stripped && /^#\s+/.test(trimmed)) { + h1Stripped = true; + continue; + } + + if (trimmed === installPlaceholder) { + outLines.push(installPlaceholder); + continue; + } + + outLines.push(sanitizeNonCodeLine(line, skillRouteMap)); + } + + return outLines.join('\n').trim(); +} + +function loadSkills(): SkillEntry[] { + let registry: any[] = []; + if (fs.existsSync(REGISTRY_PATH)) { + try { + registry = JSON.parse(fs.readFileSync(REGISTRY_PATH, 'utf-8')); + } catch (_) {} + } + + const folders = fs + .readdirSync(SKILLS_DIR) + .filter(name => fs.statSync(path.join(SKILLS_DIR, name)).isDirectory()) + .sort((a, b) => a.localeCompare(b)); + + return folders.map(name => { + const skillDir = path.join(SKILLS_DIR, name); + const regEntry = registry.find(r => r.name === name); + const readmeDesc = extractReadmeDescription(skillDir); + const description = readmeDesc || regEntry?.description || `Documentation for the ${name} skill.`; + + let version = regEntry?.version || '1.0.0'; + let author = regEntry?.author || 'opendirectory'; + let compatibility = 'All targets (claude, codex, opencode, gemini, anti-gravity, openclaw, hermes)'; + + const source = findSkillSourceSync(skillDir); + if (source && fs.existsSync(source.skillMdPath)) { + try { + const parsed = inspectSkillFrontmatter(fs.readFileSync(source.skillMdPath, 'utf-8')); + if (parsed.data.version) version = String(parsed.data.version); + if (parsed.data.author) author = String(parsed.data.author); + if (parsed.compatibility.kind === 'valid') { + compatibility = parsed.compatibility.targets.join(', '); + } + } catch (_) {} + } + + const category = getCategory(name, description, regEntry?.tags, skillDir); + const categorySlug = categoryToSlug(category); + const docRoute = `skills/${categorySlug}/${name}`; + + return { + name, + description, + version, + author, + compatibility, + category, + categorySlug, + docRoute, + }; + }); +} + +function buildMintlifyDocs() { + const skills = loadSkills(); + const skillRouteMap = new Map(); + for (const s of skills) { + skillRouteMap.set(s.name, s.docRoute); + } + + // Clean and recreate docs/skills + if (fs.existsSync(DOCS_SKILLS_DIR)) { + fs.rmSync(DOCS_SKILLS_DIR, { recursive: true, force: true }); + } + fs.mkdirSync(DOCS_SKILLS_DIR, { recursive: true }); + + // 1. Generate each skill's .mdx file + for (const skill of skills) { + const skillDir = path.join(SKILLS_DIR, skill.name); + const readmePath = path.join(skillDir, 'README.md'); + const source = findSkillSourceSync(skillDir); + const rawContent = fs.existsSync(readmePath) + ? fs.readFileSync(readmePath, 'utf-8') + : source && fs.existsSync(source.skillMdPath) + ? fs.readFileSync(source.skillMdPath, 'utf-8') + : `# ${skill.name}\n\n${skill.description}`; + + let body = convertMarkdownToMdxBody(rawContent, skillRouteMap, true); + const installTabs = buildInstallTabsMdx(skill.name); + + if (body.includes('___MINTLIFY_INSTALL_TABS_PLACEHOLDER___')) { + body = body.replace('___MINTLIFY_INSTALL_TABS_PLACEHOLDER___', `## Install\n\n${installTabs}`); + } else { + body = `## Install\n\n${installTabs}\n\n${body}`; + } + + const shortDesc = skill.description.length > 160 + ? skill.description.slice(0, 157).trim() + '...' + : skill.description; + + const mdx = `--- +title: ${JSON.stringify(skill.name)} +description: ${JSON.stringify(shortDesc)} +--- + + + **Category:** ${skill.category} · **Version:** \`${skill.version}\` · **Author:** \`${skill.author}\` · **Compatibility:** ${skill.compatibility} + + +${body} +`; + + const outDir = path.join(DOCS_SKILLS_DIR, skill.categorySlug); + fs.mkdirSync(outDir, { recursive: true }); + fs.writeFileSync(path.join(outDir, `${skill.name}.mdx`), mdx, 'utf-8'); + } + + // 2. Generate docs/skills/overview.mdx + const grouped = new Map(); + for (const skill of skills) { + if (!grouped.has(skill.category)) grouped.set(skill.category, []); + grouped.get(skill.category)!.push(skill); + } + + const orderedCategories = [ + ...CATEGORY_ORDER.filter(c => grouped.has(c)), + ...[...grouped.keys()].filter(c => !CATEGORY_ORDER.includes(c)).sort(), + ]; + + let overviewBody = `--- +title: "Skills Catalog" +description: "Browse all ${skills.length} OpenDirectory agent skills across ${orderedCategories.length} categories." +--- + +OpenDirectory includes **${skills.length} specialized skills** across GTM intelligence, content generation, launch orchestration, outreach, research, visual media, and developer tooling. + +`; + + for (const category of orderedCategories) { + const catSkills = grouped.get(category)!; + overviewBody += `## ${category}\n\n`; + overviewBody += `| Skill | Description | Version |\n|---|---|---|\n`; + for (const s of catSkills) { + const safeDesc = sanitizeNonCodeLine(s.description.replace(/\|/g, '|'), skillRouteMap); + overviewBody += `| [\`${s.name}\`](/${s.docRoute}) | ${safeDesc} | \`${s.version}\` |\n`; + } + overviewBody += `\n`; + } + + fs.writeFileSync(path.join(DOCS_SKILLS_DIR, 'overview.mdx'), overviewBody, 'utf-8'); + + // 3. Generate docs/contributing.mdx from root CONTRIBUTING.md + if (fs.existsSync(CONTRIBUTING_PATH)) { + const rawContributing = fs.readFileSync(CONTRIBUTING_PATH, 'utf-8'); + const contributingBody = convertMarkdownToMdxBody(rawContributing, skillRouteMap, true); + const contributingMdx = `--- +title: "Contributing Guide" +description: "How to build, test, and submit an AI Agent Skill to OpenDirectory." +--- + +${contributingBody} +`; + fs.writeFileSync(path.join(DOCS_DIR, 'contributing.mdx'), contributingMdx, 'utf-8'); + } + + // 4. Write docs/docs.json with auto-synced skill groups + const skillGroups = [ + { + group: 'Catalog', + pages: ['skills/overview'], + }, + ...orderedCategories.map(category => ({ + group: category, + pages: grouped.get(category)!.map(s => s.docRoute), + })), + ]; + + const docsJson = { + $schema: 'https://mintlify.com/docs.json', + theme: 'mint', + name: 'OpenDirectory', + description: 'The open-source registry of AI agent skills for founders who hate marketing.', + colors: { + primary: '#3B82F6', + light: '#58A6FF', + dark: '#1D4ED8', + }, + appearance: { + default: 'dark', + }, + contextual: { + options: ['copy', 'view', 'claude', 'chatgpt', 'mcp', 'cursor', 'vscode'], + }, + navbar: { + links: [ + { + label: 'Website', + href: 'https://www.opendirectory.dev', + }, + { + label: 'npm', + href: 'https://www.npmjs.com/package/@opendirectory.dev/skills', + }, + ], + primary: { + type: 'button', + label: 'GitHub', + href: 'https://github.com/Varnan-Tech/opendirectory', + }, + }, + footer: { + socials: { + github: 'https://github.com/Varnan-Tech/opendirectory', + }, + }, + navigation: { + tabs: [ + { + tab: 'Documentation', + icon: 'book-open', + groups: [ + { + group: 'Getting Started', + pages: ['introduction', 'installation', 'contributing'], + }, + { + group: 'CLI Reference', + pages: ['cli/overview', 'cli/compatibility'], + }, + ], + }, + { + tab: 'Skills Catalog', + icon: 'layer-group', + groups: skillGroups, + }, + ], + }, + }; + + fs.writeFileSync(DOCS_JSON_PATH, JSON.stringify(docsJson, null, 2) + '\n', 'utf-8'); + console.log(`Successfully generated Mintlify docs for ${skills.length} skills across ${orderedCategories.length} categories in ${DOCS_DIR}`); +} + +buildMintlifyDocs(); From 71719cba2db60b8571fc8abe86cb6bffbce0140f Mon Sep 17 00:00:00 2001 From: farizanjum Date: Sat, 17 Oct 2026 12:02:05 +0530 Subject: [PATCH 03/13] docs(mintlify): add core documentation and CLI reference pages --- docs/cli/compatibility.mdx | 45 ++++++++ docs/cli/overview.mdx | 62 +++++++++++ docs/contributing.mdx | 205 +++++++++++++++++++++++++++++++++++++ docs/installation.mdx | 83 +++++++++++++++ docs/introduction.mdx | 68 ++++++++++++ 5 files changed, 463 insertions(+) create mode 100644 docs/cli/compatibility.mdx create mode 100644 docs/cli/overview.mdx create mode 100644 docs/contributing.mdx create mode 100644 docs/installation.mdx create mode 100644 docs/introduction.mdx diff --git a/docs/cli/compatibility.mdx b/docs/cli/compatibility.mdx new file mode 100644 index 0000000..a5a72f4 --- /dev/null +++ b/docs/cli/compatibility.mdx @@ -0,0 +1,45 @@ +--- +title: "Agent Compatibility" +description: "How OpenDirectory validates and enforces per-skill target compatibility across coding agents." +--- + +Every skill in OpenDirectory can declare an optional `compatibility` field in its `SKILL.md` YAML frontmatter to specify which coding agents it supports. + +## Frontmatter Specification + +```yaml +--- +name: my-awesome-skill +description: Scrapes a website and generates a targeted cold email. +compatibility: [codex, opencode] +author: your-github-username +version: 1.0.0 +--- +``` + +### Canonical Target Slugs + +When `compatibility` is present, it must be a non-empty YAML array containing only canonical target slugs: + +- `claude` +- `codex` +- `opencode` +- `gemini` +- `anti-gravity` +- `openclaw` +- `hermes` + + + **Universal Skills:** Omit the `compatibility` key entirely when a skill supports all seven canonical targets. + + +--- + +## Validation & Enforcement Rules + +The `@opendirectory.dev/skills` CLI and pull request validation pipeline strictly enforce compatibility metadata: + +1. **Universal by omission:** If `compatibility` is omitted from `SKILL.md`, the skill is marked as compatible with `all` targets. +2. **Case-insensitive canonical matching:** Values inside the array are trimmed and matched case-insensitively (`Claude` normalizes to `claude`), and returned in canonical target order. +3. **Strict rejection of invalid values:** Empty arrays (`[]`), scalar strings (`compatibility: claude`), non-string items, unknown agent names, or legacy aliases (`claude-code`, `gemini-cli`) fail both PR validation (`scripts/validate-pr.ts`) and CLI installation. +4. **Install-time target check:** If a skill declares `compatibility: [claude, opencode]` and a user runs `install --target gemini`, the CLI blocks installation with an explicit message explaining which targets the skill supports. diff --git a/docs/cli/overview.mdx b/docs/cli/overview.mdx new file mode 100644 index 0000000..46abfa9 --- /dev/null +++ b/docs/cli/overview.mdx @@ -0,0 +1,62 @@ +--- +title: "CLI Overview" +description: "Complete command, flag, and environment variable reference for @opendirectory.dev/skills." +--- + +The `@opendirectory.dev/skills` package is the official command-line interface for browsing, installing, updating, and managing OpenDirectory skills. + +```bash +npx "@opendirectory.dev/skills" [command] [options] +``` + +## Interactive Mode + +Run the CLI with no arguments to launch the full-screen terminal UI (TUI): + +```bash +npx "@opendirectory.dev/skills" +``` + +- Browse skills grouped by category (`Visual & Media`, `Content`, `Launch`, `GTM Intelligence`, `Outreach`, `Research`, `Developer Tools`) +- Type to filter skills in real time +- Press `Space` to multi-select skills and `Enter` to install them in one batch + +--- + +## Commands + +| Command | Description | +|---|---| +| `list` | List all available skills in the registry (interactive by default; pass `--plain` for a static table). | +| `install --target ` | Install a skill for the specified coding agent. Saves the target as your default after the first run. | +| `update [--target ]` | Update an installed skill to the latest version with automatic rollback if the update fails. | +| `uninstall [--target ]` | Remove an installed skill from the target agent directory. | +| `installed` | Inspect and manage currently installed skills (`--plain` outputs a static summary). | + +--- + +## Supported Agent Targets + +Pass any of the canonical target slugs to `--target` (case-insensitive): + +| Target Slug | Agent | Install Directory | +|---|---|---| +| `claude` | Claude Code | `~/.claude/skills/` | +| `opencode` | OpenCode | `~/.config/opencode/skills/` | +| `codex` | OpenAI Codex CLI | `~/.codex/skills/` | +| `gemini` | Gemini CLI | `~/.gemini/skills/` | +| `anti-gravity` | Gemini Anti-Gravity | `~/.gemini/antigravity/skills/` | +| `openclaw` | OpenClaw | `~/.openclaw/skills/` | +| `hermes` | Hermes | `~/.hermes/skills/` | + +--- + +## Global Flags & Environment Variables + +### Flags +- `--plain`: Disable the interactive TUI and emit plain text output for CI pipelines, scripts, and screen readers. +- `--no-banner`: Suppress the ASCII banner on startup. + +### Environment Variables +- `NO_COLOR`: Set to any non-empty value to disable ANSI color output (per [no-color.org](https://no-color.org)). +- `CI`: When set to any non-empty value (or when `stdout`/`stdin` is not a TTY), the CLI automatically enables `--plain` mode. diff --git a/docs/contributing.mdx b/docs/contributing.mdx new file mode 100644 index 0000000..8404ff9 --- /dev/null +++ b/docs/contributing.mdx @@ -0,0 +1,205 @@ +--- +title: "Contributing Guide" +description: "How to build, test, and submit an AI Agent Skill to OpenDirectory." +--- + +Welcome to the OpenDirectory community! We are building the first universal registry for AI Agent Skills. Whether you are a seasoned growth engineer or making your very first open-source contribution, this guide will walk you through exactly how to build and submit a skill. + +**Contributor Rewards:** Top contributors receive exclusive OpenDirectory swag, including limited-edition t-shirts and merchandise. We track contributions closely and reward those who help grow the ecosystem with high-quality GTM and Technical Marketing skills. + +--- + +## What is an AI Agent Skill? + +An AI Agent Skill is a package of instructions, context, and scripts that teaches an AI assistant (like Claude Code, OpenCode, or Cursor) how to perform a specific, complex task. + +Instead of typing a massive prompt every time you want the AI to do something, you create a **Skill**. Once installed, you just type `/your-skill-name` and the AI instantly knows exactly what to do, what scripts to run, and what format to output. + +--- + +## How to Build a Skill (Step-by-Step) + +### Step 1: Clone the Repository +Get the code onto your local machine by opening your terminal and running: + +```bash +git clone https://github.com/Varnan-Tech/opendirectory.git +cd opendirectory +``` + +### Step 2: Create Your Skill Folder +All skills live inside the `skills/` directory. Create a new folder for your skill using a short, descriptive name (use dashes, no spaces). + +```bash +mkdir skills/my-awesome-skill +cd skills/my-awesome-skill +``` + +### Step 3: Choose Your Architecture + +You can build a **Basic Skill** (just instructions) or an **Advanced Skill** (instructions + code execution). + +#### Option A: The Basic Skill +A basic skill is perfect for simple prompt-based tasks. It only requires two files in your folder: + +```text +skills/my-awesome-skill/ +├── README.md +└── SKILL.md +``` + +#### Option B: The Advanced Skill (Highly Recommended) +Advanced skills are production-grade tools that use external scripts (Python/Node), local databases (SQLite), or complex reference materials. This is what makes OpenDirectory powerful. Look at `skills/position-me` in this repository for a real-world example. + +```text +skills/my-advanced-skill/ +├── README.md (The public documentation and cover image) +├── SKILL.md (The YAML frontmatter and AI instructions) +├── .env.example (Template for required API keys) +├── scripts/ (Executable Python/JS scripts for scraping or APIs) +│ └── scraper.py +└── references/ (SOPs, output templates, or complex guidelines) + └── output_format.md +``` + +### Step 4: Write Your Files + +**1. The `SKILL.md` File** +This is the brain of your skill. It MUST start with YAML frontmatter, followed by the instructions you want to give the AI agent. + +```markdown +--- +name: my-awesome-skill +description: Scrapes a website and generates a targeted cold email. +compatibility: [codex, opencode] +author: your-github-username +version: 1.0.0 +--- + +# Cold Email Generator Skill + +When the user asks you to generate a cold email: +1. Run the `scripts/scraper.py` file to extract the target's website data. +2. Read the rules in `references/email_guidelines.md`. +3. Output the final email in a markdown code block. +``` + +**Compatibility:** `compatibility` is the optional list of canonical CLI targets the skill has been tested and is supported on: `claude`, `codex`, `opencode`, `gemini`, `anti-gravity`, `openclaw`, and `hermes`. Omit the field only if the skill supports every target. When present, it must be a non-empty YAML list of those canonical targets; values are trimmed and matched case-insensitively, and aliases, unknown values, scalars, and non-string items fail validation. To add a target, implement and test that support, update this declaration, and submit it in a pull request. + +**2. The `README.md` File** +This is the public face of your skill. + +```markdown +# My Awesome Skill +This skill helps marketers automate their cold outreach by... + +### Prerequisites +- Python 3.10+ +- OpenAI API Key + +### Usage +Once installed, simply type: "Use my-awesome-skill to email john@example.com" +``` + +> **Important:** Every skill's `README.md` MUST include installation steps, how to install via the script, prerequisites, and usage instructions. We have a helper script at `scripts/update_skill_readmes.py` that automatically adds the standard install section (video tutorial + Claude Desktop steps) to all skill READMEs. Run it and verify each README looks correct. +> +> This is highly appreciated and helps users get started quickly. + +### Step 4.5: Add Skill Metadata (Required for Advanced Skills) + +To register your skill in the CLI and place it in the correct category on the main README, we recommend adding a `package.json` inside your skill's root folder. If you don't include one, the CI will auto-detect your skill's category from its name and description. **Do not manually edit the `README.md` table or `packages/cli/registry.json` these are auto-generated by our CI.** + +Create `skills/your-skill-name/package.json`: +```json +{ + "name": "your-skill-name", + "version": "1.0.0", + "description": "A short, one-line summary of what your skill does.", + "category": "GTM Intelligence" +} +``` + +#### Available Categories: +Pick the one that best fits your skill: +- `Visual & Media` +- `Content` +- `Launch` +- `GTM Intelligence` +- `Outreach` +- `Research` +- `Developer Tools` + +If none of these fit, you can create a **new category**. Here's how: + +1. **Pick a category name** : Use `Title Case` (e.g., `Analytics`, `DevOps`, `Security`). Keep it short (1-3 words) and descriptive. +2. **Set it in your `package.json`**: + ```json + { + "name": "your-skill-name", + "category": "Your New Category" + } + ``` +3. **Run the sync scripts** (from the repo root): + ```bash + pnpm exec tsx scripts/update-readme.ts + pnpm exec tsx scripts/build-registry.ts + ``` + The `update-readme.ts` script will automatically: + - Detect your new category + - Render it as a new section at the end of the README table (categories appear alphabetically after the predefined list) + - Place your skill under it +4. **Verify** the README table now has your new category section with your skill listed under it. + +> **Note:** The predefined categories listed above appear in a fixed order in the README. Custom categories are appended alphabetically after them. If you want your new category to appear in a specific position among the predefined ones, add it to the `CATEGORY_ORDER` array in `scripts/update-readme.ts`. + +Before committing, run the sync scripts locally to automatically update the docs: +```bash +pnpm install +pnpm exec tsx scripts/update-readme.ts +pnpm exec tsx scripts/update-contributing.ts +pnpm exec tsx scripts/build-registry.ts +``` + +### Step 5: Test Your Skill Locally +Before submitting a Pull Request, verify that your skill compiles and installs correctly using our CLI tool. + +Run these commands from the root `opendirectory` folder: + +```bash +pnpm install +pnpm build +npx "@opendirectory.dev/skills" install my-awesome-skill --target opencode +``` + +If successful, check your `~/.config/opencode/skills/my-awesome-skill` folder to ensure all your scripts and files were copied perfectly! + +### Step 6: Submit a Pull Request +1. Commit your changes: `git add .` -> `git commit -m "feat: add my-awesome-skill"` +2. Push to your fork and open a Pull Request against the main repository. +3. **Security Scan**: Our automated GitHub Actions will strictly scan your code for formatting and malware. +4. **AI Review**: Greptile and GitHub Copilot are going to review your PR if something is off. +5. **Merge**: If everything passes, a human maintainer will merge your PR, and your skill will instantly be published to NPM and the Claude Marketplace! + +--- + +## Looking for Inspiration? Build One of These! + +If you want to contribute but aren't sure what to build, pick one of these high-demand, advanced Go-To-Market (GTM) ideas. Our automation script tracks these, so once your PR is merged, the box will be checked automatically! + +- [x] `gh-issue-to-demand-signal` - Scans the open GitHub issues of a competitor's public repo, clusters them by theme (missing features, bugs, UX complaints), and outputs a ranked "demand gap" report. Tells you exactly what their users are begging for — which is your product's messaging brief. +- [ ] `who-viewed-my-talk` - Given a conference talk URL (YouTube/Luma/Sessionize), scrapes the comments, likes, and attendee list, cross-references speakers from the event's speaker page, and outputs a warm lead list of people who watched your category of content. +- [ ] `linkedin-hiring-intent-scanner` - Searches LinkedIn job posts for roles that signal buying intent — e.g., "Head of Developer Relations", "Growth Engineer", "RevOps Manager" — at companies in a given funding stage or industry, and outputs a prioritized list with context on why each company is interesting right now. +- [x] `npm-downloads-to-leads` - Takes a list of npm package names (yours or competitors'), pulls weekly download trends via the npm API, identifies packages with breakout velocity, and maps the maintainers to Twitter/GitHub profiles. Useful for finding evangelists before they're famous. +- [x] `sdk-adoption-tracker` - Given your SDK name, searches GitHub code search for public repos that import/require it, categorizes them by company/project type, and tracks week-over-week adoption velocity. Real signal of who's building on you — often invisible until you look. +- [x] `noise-to-linkedin-carousel` - Takes a raw voice note transcript, a rough idea dump, or a messy thread of thoughts, and restructures it into a polished LinkedIn carousel script — slide-by-slide, with a hook slide, 5-7 insight slides, and a CTA slide. Designed for founders who think out loud. +- [x] `oss-launch-kit` - Given a GitHub repo URL, generates the full launch kit: a Show HN post, a Product Hunt description, 5 Reddit posts tailored to relevant subreddits, a Twitter thread, and a "first week" community engagement plan. Built specifically for open-source product launches. +- [ ] `competitor-churner-finder` - Monitors Twitter and Reddit for posts from people expressing frustration with a specific competitor tool (e.g., "switching away from X", "X is broken again"), extracts their profiles, and drafts a timely, empathetic DM that offers your product as the alternative — without being creepy. +- [ ] `ph-daily-radar` - Hits the Product Hunt API every morning, filters launches by category, extracts the makers' Twitter/LinkedIn, and sends you a digest of who launched in your category today — with a drafted "congrats" outreach for each maker. Relationship building on autopilot. +- [x] `domain-expired-opportunity-finder` - Monitors daily expired domain lists, filters for domains that still have backlinks pointing to them (via public Ahrefs/Moz data), and flags ones in your niche that you could buy cheaply and redirect — one of the most underrated SEO plays, almost nobody automates the search. +- [x] `pricing-page-psychology-audit` - Takes a SaaS pricing page URL and audits it against 12 known pricing psychology principles (anchoring, decoy effect, loss aversion framing, feature-vs-value naming, etc.). Outputs specific suggestions on how to reframe each tier. Pricing is the highest-leverage GTM lever and almost nobody stress-tests it. +- [ ] `content-repurpose-queue` - Looks at your last 30 pieces of content (tweets, blogs, LinkedIn posts), flags every one that got above-average engagement but was never repurposed, and generates a queue of 5 repurposing formats for each one. Most people create, post once, and forget. This treats content like an asset. +- [x] `github-discussion-to-devrel-content` - Monitors GitHub Discussions on your own or a competitor's repo, surfaces threads with 10+ replies or unresolved questions, and auto-drafts a short blog post or Twitter thread that answers each one — turning your community's questions into SEO-indexed content. +- [ ] `youtube-tutorial-comment-scraper` - Scrapes comments on popular tutorial videos for competitor products, identifies frustrated users, extracts channel metadata, and finds business emails for outreach. +- [x] `app-store-review-arbitrage` - Scrapes iOS and Android app store reviews for competitor applications, filters for low-star reviews mentioning specific missing features using Python NLP scripts, and generates targeted ad copy highlighting those exact features in your own product. + +This list is continuously updated with new high-demand GTM ideas. If you have a great idea for a skill that you want someone else to build, please open an issue to submit your suggestion. We encourage contributors to share their own ideas and help expand the registry. diff --git a/docs/installation.mdx b/docs/installation.mdx new file mode 100644 index 0000000..f13ed9b --- /dev/null +++ b/docs/installation.mdx @@ -0,0 +1,83 @@ +--- +title: "Installation" +description: "Five ways to install OpenDirectory skills into Claude Code, OpenCode, Codex, Gemini CLI, Anti-Gravity, OpenClaw, Hermes, and Manus AI." +--- + +OpenDirectory supports five installation methods so you can equip any terminal or desktop AI agent in under 30 seconds. + + + + Run the official `@opendirectory.dev/skills` CLI with zero global setup: + + ```bash + # Launch interactive TUI browser + npx "@opendirectory.dev/skills" + + # Or install a specific skill directly + npx "@opendirectory.dev/skills" install --target claude + ``` + + + Requires Node.js 22+. The `--target` flag is required on first use and saved as your default for subsequent installs. + + + + + Install the entire OpenDirectory catalog or a single skill via [skills.sh](https://www.skills.sh/Varnan-Tech/opendirectory): + + ```bash + # Install all skills (auto-detects your installed coding agents) + npx skills add Varnan-Tech/opendirectory + + # Install a single skill + npx skills add Varnan-Tech/opendirectory --skill + ``` + + Add `--global` to install to `~/.claude/skills/` instead of the current project directory. + + + + Add the official OpenDirectory plugin marketplace directly inside Claude Code: + + ```bash + # 1. Register the OpenDirectory marketplace + /plugin marketplace add Varnan-Tech/opendirectory + + # 2. Install the skill pack + /plugin install opendirectory-gtm-skills@opendirectory-marketplace + ``` + + + + 1. Copy the GitHub URL of the skill folder you want to install (for example, `https://github.com/Varnan-Tech/opendirectory/tree/main/skills/show-hn-writer`). + 2. Paste the URL into [download-directory.github.io](https://download-directory.github.io/) and press **Enter** to download the `.zip` archive. + 3. Open the **Claude Desktop App**, click **Customize** in the left sidebar, open the **Skills** tab, and click **+**. + 4. Select **Upload a skill** and drag in the downloaded `.zip` archive or extracted folder containing `SKILL.md`. + + + + Manus AI users can import any skill directly from [opendirectory.dev](https://www.opendirectory.dev): + + 1. Open the skill page on [opendirectory.dev](https://www.opendirectory.dev). + 2. Select the **Manus AI** tab in the installation panel. + 3. Click **Install in Manus AI** to open Manus with the GitHub skill URL pre-filled. + 4. Confirm the import inside your Manus workspace. + + + +--- + +## Managing Installed Skills + +Once installed via the CLI, you can inspect, update, or remove skills at any time: + +```bash +# View installed skills across all agents +npx "@opendirectory.dev/skills" installed + +# Update a skill with automatic rollback on failure +npx "@opendirectory.dev/skills" update + +# Uninstall a skill +npx "@opendirectory.dev/skills" uninstall +``` diff --git a/docs/introduction.mdx b/docs/introduction.mdx new file mode 100644 index 0000000..d2e05d1 --- /dev/null +++ b/docs/introduction.mdx @@ -0,0 +1,68 @@ +--- +title: "Introduction" +description: "Agent skills for founders who hate marketing. Install production-grade GTM, growth, and developer tooling skills in seconds." +--- + +OpenDirectory Banner + +## What is OpenDirectory? + +OpenDirectory is an open-source registry of AI agent skills built for founders, growth engineers, and technical marketers. Each skill packages a verified workflow (`SKILL.md`), executable scripts (`scripts/`), and reference playbooks (`references/`) that install directly into your AI coding agent. + +Instead of rewriting long prompts every session, install a skill once and your agent immediately knows what scripts to run, how to process data, and how to verify the output. + + + + Install any skill in seconds via `npx "@opendirectory.dev/skills"`, `skills.sh`, Claude Desktop, Claude Code Plugin, or Manus AI. + + + Explore 60+ production-grade skills across Visual & Media, Content, Launch, GTM Intelligence, Outreach, Research, and Developer Tools. + + + Interactive TUI browser, non-interactive CI flags, and multi-agent installation commands. + + + Build and submit your own Basic or Advanced skill to the OpenDirectory registry. + + + +--- + +## Quick Start + + + + Launch the full-screen terminal UI to browse by category, search, and multi-select skills: + ```bash + npx "@opendirectory.dev/skills" + ``` + + + Choose your target agent (`claude`, `opencode`, `codex`, `gemini`, `anti-gravity`, `openclaw`, or `hermes`): + ```bash + npx "@opendirectory.dev/skills" install show-hn-writer --target claude + ``` + + + Ask your agent in plain English or trigger the skill directly with `/show-hn-writer`. + + + +--- + +## Supported Coding Agents + +| Agent | CLI Target Flag | Default Install Path | +|---|---|---| +| **Claude Code** | `--target claude` | `~/.claude/skills/` | +| **OpenCode** | `--target opencode` | `~/.config/opencode/skills/` | +| **OpenAI Codex CLI** | `--target codex` | `~/.codex/skills/` | +| **Gemini CLI** | `--target gemini` | `~/.gemini/skills/` | +| **Gemini Anti-Gravity** | `--target anti-gravity` | `~/.gemini/antigravity/skills/` | +| **OpenClaw** | `--target openclaw` | `~/.openclaw/skills/` | +| **Hermes** | `--target hermes` | `~/.hermes/skills/` | +| **Manus AI** | 1-click web import | Imported directly via [opendirectory.dev](https://www.opendirectory.dev) | From a9ef651b81352c2d96008d271897210cebc9b2c2 Mon Sep 17 00:00:00 2001 From: farizanjum Date: Sat, 17 Oct 2026 12:02:07 +0530 Subject: [PATCH 04/13] docs(mintlify): generate skills catalog MDX pages and docs.json --- docs/docs.json | 188 ++++++++++++++++ docs/skills/content/cook-the-blog.mdx | 122 ++++++++++ docs/skills/content/email-newsletter.mdx | 108 +++++++++ .../github-discussion-to-devrel-content.mdx | 184 +++++++++++++++ docs/skills/content/human-tone.mdx | 63 ++++++ .../content/linkedin-post-generator.mdx | 143 ++++++++++++ docs/skills/content/newsletter-digest.mdx | 183 +++++++++++++++ .../content/noise-to-linkedin-carousel.mdx | 110 +++++++++ docs/skills/content/noise2blog.mdx | 143 ++++++++++++ .../content/store-listing-optimizer.mdx | 58 +++++ .../skills/content/tweet-thread-from-blog.mdx | 145 ++++++++++++ .../developer-tools/claude-md-generator.mdx | 114 ++++++++++ .../developer-tools/dependency-update-bot.mdx | 137 ++++++++++++ .../skills/developer-tools/docs-from-code.mdx | 133 +++++++++++ docs/skills/developer-tools/dx-roaster.mdx | 154 +++++++++++++ .../developer-tools/explain-this-pr.mdx | 110 +++++++++ .../developer-tools/kill-the-standup.mdx | 120 ++++++++++ .../developer-tools/llms-txt-generator.mdx | 178 +++++++++++++++ .../developer-tools/pr-description-writer.mdx | 117 ++++++++++ .../schema-markup-generator.mdx | 150 +++++++++++++ .../app-store-review-arbitrage.mdx | 142 ++++++++++++ .../skills/gtm-intelligence/company-radar.mdx | 173 +++++++++++++++ .../gtm-intelligence/competitor-pr-finder.mdx | 139 ++++++++++++ .../skills/gtm-intelligence/geo-gap-fixer.mdx | 158 +++++++++++++ .../gh-issue-to-demand-signal.mdx | 130 +++++++++++ .../google-trends-api-skills.mdx | 114 ++++++++++ .../gtm-intelligence/hackernews-intel.mdx | 197 ++++++++++++++++ .../gtm-intelligence/map-your-market.mdx | 159 +++++++++++++ .../gtm-intelligence/meta-ads-skill.mdx | 105 +++++++++ .../gtm-intelligence/meta-tribeV2-skill.mdx | 117 ++++++++++ .../npm-downloads-to-leads.mdx | 159 +++++++++++++ .../gtm-intelligence/reddit-icp-monitor.mdx | 153 +++++++++++++ .../gtm-intelligence/reddit-post-engine.mdx | 139 ++++++++++++ .../gtm-intelligence/sdk-adoption-tracker.mdx | 163 ++++++++++++++ .../twitter-GTM-find-skill.mdx | 120 ++++++++++ .../xquik-x-follower-scraper.mdx | 111 +++++++++ .../xquik-x-tweet-scraper.mdx | 108 +++++++++ .../yc-intent-radar-skill.mdx | 75 +++++++ docs/skills/launch/brand-alchemy.mdx | 71 ++++++ docs/skills/launch/oss-launch-kit.mdx | 74 ++++++ docs/skills/launch/product-update-logger.mdx | 209 +++++++++++++++++ docs/skills/launch/producthunt-launch-kit.mdx | 131 +++++++++++ docs/skills/launch/show-hn-writer.mdx | 124 +++++++++++ .../domain-expired-opportunity-finder.mdx | 210 ++++++++++++++++++ docs/skills/outreach/cold-email-verifier.mdx | 83 +++++++ .../outreach/outreach-sequence-builder.mdx | 144 ++++++++++++ docs/skills/overview.mdx | 111 +++++++++ .../linkedin-job-post-to-buyer-pain-map.mdx | 160 +++++++++++++ .../research/meeting-brief-generator.mdx | 126 +++++++++++ .../research/podcast-transcript-fetcher.mdx | 186 ++++++++++++++++ docs/skills/research/position-me.mdx | 107 +++++++++ docs/skills/research/pricing-finder.mdx | 154 +++++++++++++ .../pricing-page-psychology-audit.mdx | 195 ++++++++++++++++ docs/skills/research/vc-curated-match.mdx | 78 +++++++ docs/skills/research/vc-finder.mdx | 132 +++++++++++ .../research/where-your-customer-lives.mdx | 165 ++++++++++++++ .../visual-and-media/blog-cover-image-cli.mdx | 150 +++++++++++++ .../visual-and-media/graphic-case-study.mdx | 132 +++++++++++ .../skills/visual-and-media/graphic-chart.mdx | 127 +++++++++++ .../skills/visual-and-media/graphic-ebook.mdx | 133 +++++++++++ docs/skills/visual-and-media/graphic-gif.mdx | 122 ++++++++++ .../visual-and-media/graphic-slide-deck.mdx | 139 ++++++++++++ .../hyperframes-product-launch-video.mdx | 128 +++++++++++ .../visual-and-media/vid-motion-graphics.mdx | 101 +++++++++ .../visual-and-media/vid-product-launch.mdx | 168 ++++++++++++++ .../visual-and-media/vid-sizzle-reel.mdx | 144 ++++++++++++ 66 files changed, 8926 insertions(+) create mode 100644 docs/docs.json create mode 100644 docs/skills/content/cook-the-blog.mdx create mode 100644 docs/skills/content/email-newsletter.mdx create mode 100644 docs/skills/content/github-discussion-to-devrel-content.mdx create mode 100644 docs/skills/content/human-tone.mdx create mode 100644 docs/skills/content/linkedin-post-generator.mdx create mode 100644 docs/skills/content/newsletter-digest.mdx create mode 100644 docs/skills/content/noise-to-linkedin-carousel.mdx create mode 100644 docs/skills/content/noise2blog.mdx create mode 100644 docs/skills/content/store-listing-optimizer.mdx create mode 100644 docs/skills/content/tweet-thread-from-blog.mdx create mode 100644 docs/skills/developer-tools/claude-md-generator.mdx create mode 100644 docs/skills/developer-tools/dependency-update-bot.mdx create mode 100644 docs/skills/developer-tools/docs-from-code.mdx create mode 100644 docs/skills/developer-tools/dx-roaster.mdx create mode 100644 docs/skills/developer-tools/explain-this-pr.mdx create mode 100644 docs/skills/developer-tools/kill-the-standup.mdx create mode 100644 docs/skills/developer-tools/llms-txt-generator.mdx create mode 100644 docs/skills/developer-tools/pr-description-writer.mdx create mode 100644 docs/skills/developer-tools/schema-markup-generator.mdx create mode 100644 docs/skills/gtm-intelligence/app-store-review-arbitrage.mdx create mode 100644 docs/skills/gtm-intelligence/company-radar.mdx create mode 100644 docs/skills/gtm-intelligence/competitor-pr-finder.mdx create mode 100644 docs/skills/gtm-intelligence/geo-gap-fixer.mdx create mode 100644 docs/skills/gtm-intelligence/gh-issue-to-demand-signal.mdx create mode 100644 docs/skills/gtm-intelligence/google-trends-api-skills.mdx create mode 100644 docs/skills/gtm-intelligence/hackernews-intel.mdx create mode 100644 docs/skills/gtm-intelligence/map-your-market.mdx create mode 100644 docs/skills/gtm-intelligence/meta-ads-skill.mdx create mode 100644 docs/skills/gtm-intelligence/meta-tribeV2-skill.mdx create mode 100644 docs/skills/gtm-intelligence/npm-downloads-to-leads.mdx create mode 100644 docs/skills/gtm-intelligence/reddit-icp-monitor.mdx create mode 100644 docs/skills/gtm-intelligence/reddit-post-engine.mdx create mode 100644 docs/skills/gtm-intelligence/sdk-adoption-tracker.mdx create mode 100644 docs/skills/gtm-intelligence/twitter-GTM-find-skill.mdx create mode 100644 docs/skills/gtm-intelligence/xquik-x-follower-scraper.mdx create mode 100644 docs/skills/gtm-intelligence/xquik-x-tweet-scraper.mdx create mode 100644 docs/skills/gtm-intelligence/yc-intent-radar-skill.mdx create mode 100644 docs/skills/launch/brand-alchemy.mdx create mode 100644 docs/skills/launch/oss-launch-kit.mdx create mode 100644 docs/skills/launch/product-update-logger.mdx create mode 100644 docs/skills/launch/producthunt-launch-kit.mdx create mode 100644 docs/skills/launch/show-hn-writer.mdx create mode 100644 docs/skills/other/domain-expired-opportunity-finder.mdx create mode 100644 docs/skills/outreach/cold-email-verifier.mdx create mode 100644 docs/skills/outreach/outreach-sequence-builder.mdx create mode 100644 docs/skills/overview.mdx create mode 100644 docs/skills/research/linkedin-job-post-to-buyer-pain-map.mdx create mode 100644 docs/skills/research/meeting-brief-generator.mdx create mode 100644 docs/skills/research/podcast-transcript-fetcher.mdx create mode 100644 docs/skills/research/position-me.mdx create mode 100644 docs/skills/research/pricing-finder.mdx create mode 100644 docs/skills/research/pricing-page-psychology-audit.mdx create mode 100644 docs/skills/research/vc-curated-match.mdx create mode 100644 docs/skills/research/vc-finder.mdx create mode 100644 docs/skills/research/where-your-customer-lives.mdx create mode 100644 docs/skills/visual-and-media/blog-cover-image-cli.mdx create mode 100644 docs/skills/visual-and-media/graphic-case-study.mdx create mode 100644 docs/skills/visual-and-media/graphic-chart.mdx create mode 100644 docs/skills/visual-and-media/graphic-ebook.mdx create mode 100644 docs/skills/visual-and-media/graphic-gif.mdx create mode 100644 docs/skills/visual-and-media/graphic-slide-deck.mdx create mode 100644 docs/skills/visual-and-media/hyperframes-product-launch-video.mdx create mode 100644 docs/skills/visual-and-media/vid-motion-graphics.mdx create mode 100644 docs/skills/visual-and-media/vid-product-launch.mdx create mode 100644 docs/skills/visual-and-media/vid-sizzle-reel.mdx diff --git a/docs/docs.json b/docs/docs.json new file mode 100644 index 0000000..68f88fe --- /dev/null +++ b/docs/docs.json @@ -0,0 +1,188 @@ +{ + "$schema": "https://mintlify.com/docs.json", + "theme": "mint", + "name": "OpenDirectory", + "description": "The open-source registry of AI agent skills for founders who hate marketing.", + "colors": { + "primary": "#3B82F6", + "light": "#58A6FF", + "dark": "#1D4ED8" + }, + "appearance": { + "default": "dark" + }, + "contextual": { + "options": [ + "copy", + "view", + "claude", + "chatgpt", + "mcp", + "cursor", + "vscode" + ] + }, + "navbar": { + "links": [ + { + "label": "Website", + "href": "https://www.opendirectory.dev" + }, + { + "label": "npm", + "href": "https://www.npmjs.com/package/@opendirectory.dev/skills" + } + ], + "primary": { + "type": "button", + "label": "GitHub", + "href": "https://github.com/Varnan-Tech/opendirectory" + } + }, + "footer": { + "socials": { + "github": "https://github.com/Varnan-Tech/opendirectory" + } + }, + "navigation": { + "tabs": [ + { + "tab": "Documentation", + "icon": "book-open", + "groups": [ + { + "group": "Getting Started", + "pages": [ + "introduction", + "installation", + "contributing" + ] + }, + { + "group": "CLI Reference", + "pages": [ + "cli/overview", + "cli/compatibility" + ] + } + ] + }, + { + "tab": "Skills Catalog", + "icon": "layer-group", + "groups": [ + { + "group": "Catalog", + "pages": [ + "skills/overview" + ] + }, + { + "group": "Visual & Media", + "pages": [ + "skills/visual-and-media/blog-cover-image-cli", + "skills/visual-and-media/graphic-case-study", + "skills/visual-and-media/graphic-chart", + "skills/visual-and-media/graphic-ebook", + "skills/visual-and-media/graphic-gif", + "skills/visual-and-media/graphic-slide-deck", + "skills/visual-and-media/hyperframes-product-launch-video", + "skills/visual-and-media/vid-motion-graphics", + "skills/visual-and-media/vid-product-launch", + "skills/visual-and-media/vid-sizzle-reel" + ] + }, + { + "group": "Content", + "pages": [ + "skills/content/cook-the-blog", + "skills/content/email-newsletter", + "skills/content/github-discussion-to-devrel-content", + "skills/content/human-tone", + "skills/content/linkedin-post-generator", + "skills/content/newsletter-digest", + "skills/content/noise-to-linkedin-carousel", + "skills/content/noise2blog", + "skills/content/store-listing-optimizer", + "skills/content/tweet-thread-from-blog" + ] + }, + { + "group": "Launch", + "pages": [ + "skills/launch/brand-alchemy", + "skills/launch/oss-launch-kit", + "skills/launch/product-update-logger", + "skills/launch/producthunt-launch-kit", + "skills/launch/show-hn-writer" + ] + }, + { + "group": "GTM Intelligence", + "pages": [ + "skills/gtm-intelligence/app-store-review-arbitrage", + "skills/gtm-intelligence/company-radar", + "skills/gtm-intelligence/competitor-pr-finder", + "skills/gtm-intelligence/geo-gap-fixer", + "skills/gtm-intelligence/gh-issue-to-demand-signal", + "skills/gtm-intelligence/google-trends-api-skills", + "skills/gtm-intelligence/hackernews-intel", + "skills/gtm-intelligence/map-your-market", + "skills/gtm-intelligence/meta-ads-skill", + "skills/gtm-intelligence/meta-tribeV2-skill", + "skills/gtm-intelligence/npm-downloads-to-leads", + "skills/gtm-intelligence/reddit-icp-monitor", + "skills/gtm-intelligence/reddit-post-engine", + "skills/gtm-intelligence/sdk-adoption-tracker", + "skills/gtm-intelligence/twitter-GTM-find-skill", + "skills/gtm-intelligence/xquik-x-follower-scraper", + "skills/gtm-intelligence/xquik-x-tweet-scraper", + "skills/gtm-intelligence/yc-intent-radar-skill" + ] + }, + { + "group": "Outreach", + "pages": [ + "skills/outreach/cold-email-verifier", + "skills/outreach/outreach-sequence-builder" + ] + }, + { + "group": "Research", + "pages": [ + "skills/research/linkedin-job-post-to-buyer-pain-map", + "skills/research/meeting-brief-generator", + "skills/research/podcast-transcript-fetcher", + "skills/research/position-me", + "skills/research/pricing-finder", + "skills/research/pricing-page-psychology-audit", + "skills/research/vc-curated-match", + "skills/research/vc-finder", + "skills/research/where-your-customer-lives" + ] + }, + { + "group": "Developer Tools", + "pages": [ + "skills/developer-tools/claude-md-generator", + "skills/developer-tools/dependency-update-bot", + "skills/developer-tools/docs-from-code", + "skills/developer-tools/dx-roaster", + "skills/developer-tools/explain-this-pr", + "skills/developer-tools/kill-the-standup", + "skills/developer-tools/llms-txt-generator", + "skills/developer-tools/pr-description-writer", + "skills/developer-tools/schema-markup-generator" + ] + }, + { + "group": "Other", + "pages": [ + "skills/other/domain-expired-opportunity-finder" + ] + } + ] + } + ] + } +} diff --git a/docs/skills/content/cook-the-blog.mdx b/docs/skills/content/cook-the-blog.mdx new file mode 100644 index 0000000..3aa9280 --- /dev/null +++ b/docs/skills/content/cook-the-blog.mdx @@ -0,0 +1,122 @@ +--- +title: "cook-the-blog" +description: "This guide explains how to set up, configure, and run the cook-the-blog skill. This AI agent pipeline autonomously researches companies, extracts SEO keyword..." +--- + + + **Category:** Content · **Version:** `1.0.0` · **Author:** `OpenDirectory` · **Compatibility:** All targets (claude, codex, opencode, gemini, anti-gravity, openclaw, hermes) + + +cook-the-blog-cover + +This guide explains how to set up, configure, and run the `cook-the-blog` skill. This AI agent pipeline autonomously researches companies, extracts SEO keywords, generates custom cover images, writes high-converting MDX case studies without AI fluff, uploads assets to cloud storage, and pushes the final code to your designated GitHub repository. + +## Install + + + + ```bash + npx "@opendirectory.dev/skills" install cook-the-blog --target claude + ``` + + + ```bash + npx skills add Varnan-Tech/opendirectory --skill cook-the-blog + ``` + + + ```bash + /plugin marketplace add Varnan-Tech/opendirectory + /plugin install opendirectory-gtm-skills@opendirectory-marketplace + ``` + + + 1. Copy `https://github.com/Varnan-Tech/opendirectory/tree/main/skills/cook-the-blog` into [download-directory.github.io](https://download-directory.github.io/) to download the ZIP. + 2. Open **Claude Desktop** -> **Customize** -> **Skills** -> **+** -> **Upload a skill** and drop the folder containing `SKILL.md`. + + + [**Install cook-the-blog in Manus AI**](https://manus.im/import-skills?githubUrl=https%3A%2F%2Fgithub.com%2FVarnan-Tech%2Fopendirectory%2Ftree%2Fmain%2Fskills%2Fcook-the-blog&utm_source=opendirectory) + + + + +## Prerequisites & Dependencies + +Before running the skill, the AI agent needs access to several external tools, APIs, and environment details. + +**Agent Instruction:** Before executing the pipeline for the first time, you (the AI Agent) must explicitly ask the user for any missing configuration details listed below (Target Repo, GCS Bucket, Email, etc.). **Do not hardcode these values into the skill.md file automatically without asking.** + +### 1. Tavily Search (Deep Research) +Used for deep, high-quality web research to extract hard metrics, founder details, and GTM strategies. +- **Setup:** You need a Tavily API key from [Tavily](https://tavily.com/). +- **Installation:** Install the Tavily MCP server so the agent can use it natively. + ```bash + npx -y @modelcontextprotocol/server-tavily + ``` +- **Environment Variable:** Set `TAVILY_API_KEY` in your agent's environment or MCP config. + +### 2. SerpApi (SEO Keyword Research) +Used to pull Google Trends data to find breakout search queries. +- **Setup:** Get a SerpApi key from [SerpApi](https://serpapi.com/). +- **Installation:** Ensure Python 3 and the `requests` / `google-search-results` libraries are installed. The user must provide a custom Python script (e.g., `blog_seo_research.py`) that queries the Google Trends API. The agent must be told the exact file path to this script. +- **Environment Variable:** `SERPAPI_KEY` + +### 3. Blog Cover Image CLI +A custom Node.js CLI tool used to generate 16:9 minimalist cover images with company logos. +- **Installation:** Install the tool globally via npm. + ```bash + npm i -g blog-cover-image-cli + ``` +- **Usage:** The agent calls it via `blog-cover-cli generate -t "Title" -l "Logo URL" -o "./cover.png"`. + +### 4. Cloud Storage (e.g., Google Cloud Storage, AWS S3) +Used to host the generated cover images. The user must specify which cloud provider they want to use. +- **Setup (Example for GCP):** The user needs a Google Cloud Service Account with storage write permissions. +- **Installation:** Install the Google Cloud SDK (`gcloud` and `gsutil`). +- **Authentication:** The user must provide a `service-account.json` file to authenticate. + ```bash + gcloud auth activate-service-account --key-file=service-account.json + ``` +- **Target Bucket:** The user must provide the target bucket URL (e.g., `gs://your-bucket-name/covers/`). + +### 5. GitHub CLI & Git +Used for pushing the final MDX file to the target repository. +- **Setup:** Ensure `git` and `gh` (GitHub CLI) are installed on the host. +- **Authentication:** Log in to the GitHub CLI using a personal access token. + ```bash + gh auth login --with-token < token.txt + ``` +- **Configuration:** The agent will need the user's `git config user.name` and `git config user.email` to ensure proper commit attribution. + +### 6. Email Notifications (SMTP) +Used to send a final success summary to the admin. +- **Setup:** The agent creates a Python script (`send_summary.py`) using the built-in `smtplib`. +- **Credentials:** The user must provide a dedicated sender Gmail account and an **App Password** (not their real password), as well as the destination admin email. + +### 7. Stop Slop (AI Output Quality) +Used to ensure the generated case studies avoid typical AI fluff and maintain a high-quality, human-like tone. +- **Setup:** Add the [Stop Slop](https://github.com/hardikpandya/stop-slop) skill to your agent's loaded skills before running the generation pipeline. + +--- + +## Configuration Variables to Ask For + +When initializing this skill, the agent must ask the user to provide or confirm the following placeholders before running the pipeline: + +1. **`[TARGET_REPO_URL]`**: The exact GitHub repository URL or slug (e.g., `username/my-blog-repo`). +2. **`[TARGET_BUCKET]`**: The cloud storage bucket path (e.g., `gs://my-images-bucket/blogs/`). +3. **`[PUBLIC_IMAGE_BASE_URL]`**: The public base URL where the uploaded images will be accessible (e.g., `https://storage.googleapis.com/my-images-bucket/blogs/`). +4. **`[GIT_USER_NAME]` & `[GIT_USER_EMAIL]`**: The exact name and email to use for Git commit authorship. +5. **`[ADMIN_EMAIL]`**: Where to send the final summary report. +6. **`[SENDER_EMAIL]` & `[SENDER_APP_PASSWORD]`**: The credentials for the SMTP Python script. +7. **`[PATH_TO_SEO_SCRIPT]`**: The exact path to the Python script that handles the SerpApi Google Trends queries. +8. **Brand Promotion Link**: The URL and pitch text to inject into the final FAQ of the MDX template (e.g., "If you want to build this, check out [MyBrand](https://mybrand.com)"). + +--- + +## How to Run + +1. Once the user has provided the environment variables and configuration details, place the `skill.md` file in your agent's workspace. +2. The agent will read `skill.md` to understand the 8-step execution loop. +3. Trigger the agent by saying: *"Run the case study generator for [Company Name]."* +4. The agent will autonomously execute the entire pipeline from research to deployment. diff --git a/docs/skills/content/email-newsletter.mdx b/docs/skills/content/email-newsletter.mdx new file mode 100644 index 0000000..ac0c609 --- /dev/null +++ b/docs/skills/content/email-newsletter.mdx @@ -0,0 +1,108 @@ +--- +title: "email-newsletter" +description: "Draft and design a complete HTML email newsletter from a topic or content brief. Output is paste-ready for Loops, Mailchimp, Beehiiv, Resend, or any standard..." +--- + + + **Category:** Content · **Version:** `1.0.0` · **Author:** `OpenDirectory` · **Compatibility:** All targets (claude, codex, opencode, gemini, anti-gravity, openclaw, hermes) + + +Draft and design a complete HTML email newsletter from a topic or content brief. Output is paste-ready for Loops, Mailchimp, Beehiiv, Resend, or any standard email platform. + +## Install + + + + ```bash + npx "@opendirectory.dev/skills" install email-newsletter --target claude + ``` + + + ```bash + npx skills add Varnan-Tech/opendirectory --skill email-newsletter + ``` + + + ```bash + /plugin marketplace add Varnan-Tech/opendirectory + /plugin install opendirectory-gtm-skills@opendirectory-marketplace + ``` + + + 1. Copy `https://github.com/Varnan-Tech/opendirectory/tree/main/skills/email-newsletter` into [download-directory.github.io](https://download-directory.github.io/) to download the ZIP. + 2. Open **Claude Desktop** -> **Customize** -> **Skills** -> **+** -> **Upload a skill** and drop the folder containing `SKILL.md`. + + + [**Install email-newsletter in Manus AI**](https://manus.im/import-skills?githubUrl=https%3A%2F%2Fgithub.com%2FVarnan-Tech%2Fopendirectory%2Ftree%2Fmain%2Fskills%2Femail-newsletter&utm_source=opendirectory) + + + + +## What it does + +- Asks the 19 questions that actually determine your newsletter layout +- Writes all sections: hero, intro, main content, stat callout, CTA, footer +- Generates table-based HTML with inline styles -- compatible with every major email client +- Tunes variable syntax per platform (Loops, Mailchimp, Beehiiv, Resend) +- Produces 3 subject line options using proven formulas +- Includes a plain-text fallback for deliverability + +## Example + +> "Write a newsletter about how AI is changing B2B sales. Audience: VPs of Sales at 100-500 person SaaS companies. CTA: join our upcoming webinar. Tone: direct. Platform: Beehiiv." + +Output: full HTML email with hero headline, 3-section body, stat callout, CTA block, and footer -- plus 3 subject line options and a plain-text version, tuned for Beehiiv. + +## Supported platforms + +| Platform | Notes | +|---|---| +| Loops | `{{unsubscribe_url}}` syntax. Paste into custom HTML editor | +| Mailchimp | `*\|UNSUB\|*` syntax. Use "Code your own" template. Includes `mc:edit` regions | +| Beehiiv | `%%unsubscribe_url%%` syntax. Works with custom HTML block | +| Resend | `{unsubscribeUrl}` syntax. React Email `.tsx` output available on request | +| Generic | `[UNSUBSCRIBE_URL]` placeholder -- replace before sending | + +## Output formats + +- **Standard HTML** (default): inline-styled, table-based, 600px max-width +- **Plain text**: always included unless you opt out +- **React Email** (on request): `.tsx` component output for Resend / dev teams + +## Parameters + +| Param | Required | Notes | +|---|---|---| +| topic | Yes | What the newsletter is about | +| audience | Yes | Who is reading | +| cta | Yes | Primary action you want readers to take | +| company_name | No | Brand name for header and footer | +| tagline | No | One-line description for footer | +| city_country | No | Footer location (e.g. "San Francisco, US") | +| cta_url | No | Actual link for CTA button -- placeholder used if omitted | +| brand_color | No | Hex code -- used for strip, stat border, category label | +| background | No | dark / light / custom hex (default: dark) | +| display_font | No | editorial serif / modern sans / system fonts (default: Instrument Serif) | +| button_style | No | pill / softly rounded / sharp (default: pill) | +| visual_style | No | editorial / technical+data / warm+founder / bold+campaign | +| tone | No | educational / conversational / bold+direct / formal / playful | +| platform | No | loops / mailchimp / beehiiv / resend (default: generic) | +| personalization | No | none / first name / first name + company (default: none) | +| length | No | brief (300w) / standard (500-700w) / deep dive (800w+) | +| format | No | editorial article / numbered breakdown / personal story / data report | +| subject_line | No | If omitted, 3 options are suggested | +| secondary_sections | No | sponsor block / product callout / event / quick links | + +## No API keys required + +Pure AI skill. No external services, no scraping, no dependencies to install. + +## Design principles + +- Max width 600px (email client standard) +- Inline styles only -- no external CSS, email clients strip it +- Table-based layout for Outlook compatibility +- Georgia serif for hero headlines, Arial/system font for body +- CTA buttons use the table+td VML-compatible structure +- All images include alt text +- Dark mode aware where platform supports it diff --git a/docs/skills/content/github-discussion-to-devrel-content.mdx b/docs/skills/content/github-discussion-to-devrel-content.mdx new file mode 100644 index 0000000..f7b1e81 --- /dev/null +++ b/docs/skills/content/github-discussion-to-devrel-content.mdx @@ -0,0 +1,184 @@ +--- +title: "github-discussion-to-devrel-content" +description: "Your users keep asking the same questions in GitHub Discussions. This skill finds those patterns, tells you which docs to fix first, and drafts the actual FA..." +--- + + + **Category:** Content · **Version:** `1.0.0` · **Author:** `ajaycodesitbetter` · **Compatibility:** All targets (claude, codex, opencode, gemini, anti-gravity, openclaw, hermes) + + +Your users keep asking the same questions in GitHub Discussions. This skill finds those patterns, tells you which docs to fix first, and drafts the actual FAQ entries and content angles — backed by verbatim quotes and direct links to the threads that prove the gap is real. + +You get two ranked lists: documentation holes with ready-to-paste fix drafts, and content opportunities with specific angles and outlines. Unanswered community pain gets flagged as urgent. + +--- + +## Install + + + + ```bash + npx "@opendirectory.dev/skills" install github-discussion-to-devrel-content --target claude + ``` + + + ```bash + npx skills add Varnan-Tech/opendirectory --skill github-discussion-to-devrel-content + ``` + + + ```bash + /plugin marketplace add Varnan-Tech/opendirectory + /plugin install opendirectory-gtm-skills@opendirectory-marketplace + ``` + + + 1. Copy `https://github.com/Varnan-Tech/opendirectory/tree/main/skills/github-discussion-to-devrel-content` into [download-directory.github.io](https://download-directory.github.io/) to download the ZIP. + 2. Open **Claude Desktop** -> **Customize** -> **Skills** -> **+** -> **Upload a skill** and drop the folder containing `SKILL.md`. + + + [**Install github-discussion-to-devrel-content in Manus AI**](https://manus.im/import-skills?githubUrl=https%3A%2F%2Fgithub.com%2FVarnan-Tech%2Fopendirectory%2Ftree%2Fmain%2Fskills%2Fgithub-discussion-to-devrel-content&utm_source=opendirectory) + + + + +## What It Does + +- Scans your own repo's Discussions (not competitors' — that's `gh-issue-to-demand-signal`) +- Clusters recurring confusion by underlying concept, not surface keywords +- Ranks each cluster by frequency, engagement, recency, and unanswered rate +- Drafts the actual FAQ / doc fix as a Markdown snippet you can paste into your docs +- Generates a specific content angle and outline for each content opportunity +- Flags unanswered community pain as ⚠️ URGENT so you know what's bleeding +- Refuses to fabricate patterns when data is thin (low-signal guard built in) + +## What It Does NOT Do + +- Does not mine competitor repos — use `gh-issue-to-demand-signal` for outbound GTM signals +- Does not write full-length blog posts or published docs pages — use `noise2blog` to expand a draft into a finished asset +- Does not post to LinkedIn, Twitter, or any platform +- Does not predict SEO, engagement, or content performance outcomes +- Does not access private repositories + +--- + +## Requirements + +| Requirement | Purpose | How to Get | +|---|---|---| +| GitHub Personal Access Token | Fetch discussions via GraphQL API | [github.com/settings/tokens](https://github.com/settings/tokens) — enable `read:discussion` scope | +| Python 3.10+ | Run the fetcher script | No external packages required — stdlib only | + +No paid APIs. No third-party SaaS. Free GitHub accounts work. + +--- + +## Setup + +```bash +cp .env.example .env +# Edit .env and add your GITHUB_TOKEN +``` + +--- + +## How to Use + +### Step 1 — Fetch Discussions + +```bash +# Basic usage (last 90 days, all categories, min 3 comments) +python scripts/fetch_discussions.py --repo owner/repo + +# Filter to Q&A category only +python scripts/fetch_discussions.py --repo owner/repo --category "Q&A" + +# Docs gaps only, last 60 days +python scripts/fetch_discussions.py --repo owner/repo --days-back 60 --mode docs + +# Content opportunities only +python scripts/fetch_discussions.py --repo owner/repo --mode content + +# Full GitHub URL also accepted +python scripts/fetch_discussions.py --repo https://github.com/owner/repo +``` + +Output: `discussions_raw.json` in the working directory. + +### Step 2 — Run the Skill + +Once `discussions_raw.json` is present, tell your agent: + +``` +"Run the github-discussion-to-devrel-content skill and produce the DevRel backlog." +``` + +Or: + +``` +"Analyze discussions_raw.json and generate devrel-backlog.md" +``` + +Output: `devrel-backlog.md` — a ranked Markdown report ready to commit. + +--- + +## CLI Options + +| Flag | Default | Description | +|---|---|---| +| `--repo` | required | `owner/repo` or full GitHub URL | +| `--days-back` | 90 | Days of discussion history to inspect | +| `--min-comments` | 3 | Minimum comment count to include a discussion | +| `--max-items` | 100 | Cap on discussions fetched (API cost control) | +| `--category` | all | Filter by discussion category name (e.g., `Q&A`) | +| `--mode` | combined | `docs`, `content`, or `combined` | +| `--output` | `discussions_raw.json` | Output file path | + +--- + +## Output + +`devrel-backlog.md` contains: + +**Run Summary** — repo, date, discussions analyzed, clusters found, mode. + +**Docs / FAQ Gaps** — Up to 7 ranked items. Each includes: +- Priority score (0–100, relative ranking within this run) +- Frequency and engagement metrics +- A verbatim evidence quote from the thread +- A direct link to the source discussion +- A ready-to-paste **Draft FAQ / Doc Update** as a Markdown snippet +- ⚠️ URGENT badge if the community pain is unresolved + +**Content Opportunities** — Up to 7 ranked items. Each includes: +- A working content title and type (blog post, tutorial, FAQ entry, Twitter thread, video script) +- Why this matters for the founder +- A verbatim evidence quote and source link +- A **Recommended Angle** and 3–4 point outline tied to the community confusion + +> **Note on scores:** Priority scores are relative rankings within this analysis run, not absolute quality measures. A score of 84 ranks higher than a score of 71 in this dataset. Scores are not comparable across different repos or different run configurations. + +--- + +## Project Structure + +``` +github-discussion-to-devrel-content/ +├── SKILL.md +├── README.md +├── .env.example +├── scripts/ +│ └── fetch_discussions.py +├── evals/ +│ └── evals.json +└── references/ + ├── output-format.md + └── scoring-guide.md +``` + +--- + +## License + +MIT diff --git a/docs/skills/content/human-tone.mdx b/docs/skills/content/human-tone.mdx new file mode 100644 index 0000000..da967c4 --- /dev/null +++ b/docs/skills/content/human-tone.mdx @@ -0,0 +1,63 @@ +--- +title: "human-tone" +description: "AI assistants write terrible marketing copy. They rely on generic filler words, force everything into lists of three, and bury your actual product under laye..." +--- + + + **Category:** Content · **Version:** `1.0.0` · **Author:** `opendirectory` · **Compatibility:** All targets (claude, codex, opencode, gemini, anti-gravity, openclaw, hermes) + + +human-tone-skill-cover-image + + +AI assistants write terrible marketing copy. They rely on generic filler words, force everything into lists of three, and bury your actual product under layers of hype. + +The Human Tone skill teaches your AI how to edit its own work. It provides strict rules for stripping out robotic patterns and rewriting text to sound like a direct conversation from a founder to a customer. + +## Install + + + + ```bash + npx "@opendirectory.dev/skills" install human-tone --target claude + ``` + + + ```bash + npx skills add Varnan-Tech/opendirectory --skill human-tone + ``` + + + ```bash + /plugin marketplace add Varnan-Tech/opendirectory + /plugin install opendirectory-gtm-skills@opendirectory-marketplace + ``` + + + 1. Copy `https://github.com/Varnan-Tech/opendirectory/tree/main/skills/human-tone` into [download-directory.github.io](https://download-directory.github.io/) to download the ZIP. + 2. Open **Claude Desktop** -> **Customize** -> **Skills** -> **+** -> **Upload a skill** and drop the folder containing `SKILL.md`. + + + [**Install human-tone in Manus AI**](https://manus.im/import-skills?githubUrl=https%3A%2F%2Fgithub.com%2FVarnan-Tech%2Fopendirectory%2Ftree%2Fmain%2Fskills%2Fhuman-tone&utm_source=opendirectory) + + + + +## What It Fixes + +* Removes words like "streamline", "empower", and "revolutionize". +* Stops the AI from starting emails with "I hope this finds you well". +* Forces the AI to replace vague claims with specific numbers and outcomes. +* Fixes the rigid sentence structures that make AI text obvious. + +## How to Use It + +Once the skill is installed in your workspace, simply ask your AI to humanize your copy. + +**Basic usage:** +> "Take this draft for a cold email and run it through the human-tone skill. Make it short and direct." + +**Advanced usage (Matching a specific voice):** +> "Rewrite this landing page copy using the human-tone skill. Match the writing style in this sample: [paste a sample of your writing]." + +The AI will rewrite the text, provide a bulleted list of what it changed, and flag any placeholders where you need to insert real numbers or actual customer names. diff --git a/docs/skills/content/linkedin-post-generator.mdx b/docs/skills/content/linkedin-post-generator.mdx new file mode 100644 index 0000000..72bb866 --- /dev/null +++ b/docs/skills/content/linkedin-post-generator.mdx @@ -0,0 +1,143 @@ +--- +title: "linkedin-post-generator" +description: "Generate LinkedIn posts from any content: blog posts, articles, GitHub PRs, or a description of what you built. The agent reads your source material, applies..." +--- + + + **Category:** Content · **Version:** `1.0.0` · **Author:** `OpenDirectory` · **Compatibility:** All targets (claude, codex, opencode, gemini, anti-gravity, openclaw, hermes) + + +LinkedIn_post_generator + +Generate LinkedIn posts from any content: blog posts, articles, GitHub PRs, or a description of what you built. The agent reads your source material, applies LinkedIn's content patterns, and produces a post with the right hook, story arc, and formatting. + +## Install + + + + ```bash + npx "@opendirectory.dev/skills" install linkedin-post-generator --target claude + ``` + + + ```bash + npx skills add Varnan-Tech/opendirectory --skill linkedin-post-generator + ``` + + + ```bash + /plugin marketplace add Varnan-Tech/opendirectory + /plugin install opendirectory-gtm-skills@opendirectory-marketplace + ``` + + + 1. Copy `https://github.com/Varnan-Tech/opendirectory/tree/main/skills/linkedin-post-generator` into [download-directory.github.io](https://download-directory.github.io/) to download the ZIP. + 2. Open **Claude Desktop** -> **Customize** -> **Skills** -> **+** -> **Upload a skill** and drop the folder containing `SKILL.md`. + + + [**Install linkedin-post-generator in Manus AI**](https://manus.im/import-skills?githubUrl=https%3A%2F%2Fgithub.com%2FVarnan-Tech%2Fopendirectory%2Ftree%2Fmain%2Fskills%2Flinkedin-post-generator&utm_source=opendirectory) + + + + +## Post Styles + +| Style | Use When | Example Input | +|-------|----------|---------------| +| Founder/Ship | Personal story of building or shipping | "We merged our streaming SDK after 3 weeks" | +| Insight | Educational observation or lesson | Blog article, pattern you noticed, lesson learned | +| Product Launch | Announcing a new tool or feature | PR description, launch brief, feature going GA | +| Tutorial Summary | Distilling a long technical post | Tutorial URL, deep-dive article, step-by-step guide | + +The agent auto-detects the right style. You override it by asking for a specific one. + +## Requirements + +No LLM API key needed. The agent writes the post. + +Composio is optional. Add it to post directly to LinkedIn. + +## Setup + +### Composio (Optional) + +Without Composio, the agent outputs formatted text for copy-paste. No configuration needed. + +To enable direct posting: +1. Get your API key at https://app.composio.dev/settings +2. Connect your LinkedIn account at https://app.composio.dev/app/linkedin +3. Complete the OAuth flow +4. Add the key to your .env file: + +```bash +cp .env.example .env +# Edit .env and add your COMPOSIO_API_KEY +``` + +## How to Use + +From a URL: +``` +"Turn this into a LinkedIn post: https://yourblog.com/my-post" +"Write a LinkedIn post about this article: [URL]" +``` + +From pasted text: +``` +"Here's a case study, turn it into a LinkedIn post: [paste text]" +"Convert this to a LinkedIn post: [paste article]" +``` + +From a PR or shipped feature: +``` +"Write a LinkedIn post about this PR we merged: [paste PR description]" +"Announce our new feature on LinkedIn: [describe the feature]" +``` + +With a style override: +``` +"Write a LinkedIn post in Tutorial Summary style about: [topic]" +"Use the Product Launch style for this: [description]" +``` + +With direct posting: +``` +"Post this to LinkedIn: [paste content]" +"Generate and post a LinkedIn update about [topic]" +``` + +## Output + +| Output | Description | +|--------|-------------| +| LinkedIn post | Formatted text, 900-1,300 characters, ready to publish | +| First comment | Text with source links. Post this immediately after publishing. | +| Hook alternatives | 2 additional hook lines in different formats | +| Posted confirmation | If Composio is configured and you confirm posting | + +## How Posts Are Formatted + +Four rules drive every post the agent writes: + +- Hook first. The first line is all most people see. It works standalone. +- Short paragraphs. 1-3 lines, then a blank line. LinkedIn is mobile-first. +- Links in the first comment. URLs in the post body reduce LinkedIn's distribution. +- Question or CTA at the end. One or the other, not both. + +## Project Structure + +``` +linkedin-post-generator/ +├── SKILL.md +├── README.md +├── .env.example +├── evals/ +│ └── evals.json +└── references/ + ├── linkedin-format.md + └── output-template.md +``` + +## License + +MIT diff --git a/docs/skills/content/newsletter-digest.mdx b/docs/skills/content/newsletter-digest.mdx new file mode 100644 index 0000000..a643d84 --- /dev/null +++ b/docs/skills/content/newsletter-digest.mdx @@ -0,0 +1,183 @@ +--- +title: "newsletter-digest" +description: "Aggregate RSS feeds, synthesize the week's top stories with Gemini, and publish a newsletter digest to Ghost CMS. Supports three digest formats and outputs H..." +--- + + + **Category:** Content · **Version:** `1.0.0` · **Author:** `OpenDirectory` · **Compatibility:** All targets (claude, codex, opencode, gemini, anti-gravity, openclaw, hermes) + + +newsletter-digest + + +Aggregate RSS feeds, synthesize the week's top stories with Gemini, and publish a newsletter digest to Ghost CMS. Supports three digest formats and outputs HTML, Markdown, and plain text for any platform. + +## Install + + + + ```bash + npx "@opendirectory.dev/skills" install newsletter-digest --target claude + ``` + + + ```bash + npx skills add Varnan-Tech/opendirectory --skill newsletter-digest + ``` + + + ```bash + /plugin marketplace add Varnan-Tech/opendirectory + /plugin install opendirectory-gtm-skills@opendirectory-marketplace + ``` + + + 1. Copy `https://github.com/Varnan-Tech/opendirectory/tree/main/skills/newsletter-digest` into [download-directory.github.io](https://download-directory.github.io/) to download the ZIP. + 2. Open **Claude Desktop** -> **Customize** -> **Skills** -> **+** -> **Upload a skill** and drop the folder containing `SKILL.md`. + + + [**Install newsletter-digest in Manus AI**](https://manus.im/import-skills?githubUrl=https%3A%2F%2Fgithub.com%2FVarnan-Tech%2Fopendirectory%2Ftree%2Fmain%2Fskills%2Fnewsletter-digest&utm_source=opendirectory) + + + + +## What It Does + +- Reads your RSS/Atom feed list from `feeds.json` +- Fetches all articles published in the last 7 days (configurable) +- Deduplicates across feeds and sorts by date +- Uses Gemini to synthesize a digest in your chosen format +- Publishes to Ghost as a draft or live post +- Outputs formatted Markdown for Substack, Notion, or any other platform + +## Digest Formats + +| Format | Use When | Target Length | +|--------|----------|---------------| +| Weekly Roundup | General digest covering top stories across all feeds | 350-500 words | +| Topic Deep Dive | Focused issue on a single topic (AI, security, etc.) | 450-650 words | +| Curated Picks | 5 selected articles with editorial context | 250-350 words | + +## Requirements + +| Requirement | Purpose | Where to Get It | +|------------|---------|-----------------| +| GEMINI_API_KEY | Digest synthesis | https://ai.google.dev | +| GHOST_URL + GHOST_ADMIN_KEY | Ghost publishing (optional) | Ghost Admin, Settings, Integrations | +| Node.js 20+ | Running scripts | https://nodejs.org | + +Tavily is not required. The skill uses article excerpts from RSS feeds directly. + +## Setup + +### 1. Set up dependencies + +```bash +cd /path/to/newsletter-digest +npm install +``` + +### 2. Configure environment variables + +```bash +cp .env.example .env +# Edit .env with your keys +``` + +### 3. Configure your feeds + +Edit `feeds.json` with the RSS feeds you want to monitor: + +```json +[ + { "url": "https://hnrss.org/frontpage", "name": "Hacker News" }, + { "url": "https://feeds.feedburner.com/TheHackersNews", "name": "The Hacker News" }, + { "url": "https://changelog.com/feed", "name": "Changelog" } +] +``` + +The file ships with 5 example feeds. Replace them with your own. + +### 4. Set up Ghost publishing (optional) + +1. Go to Ghost Admin, Settings, Integrations +2. Click "Add custom integration" +3. Name it "newsletter-digest" +4. Copy the Admin API Key (format: `key_id:secret`) +5. Set `GHOST_ADMIN_KEY=key_id:secret` in `.env` +6. Set `GHOST_URL=https://your-ghost-site.com` in `.env` + +## How to Use + +Generate a weekly digest: + +``` +"Generate a weekly digest from my RSS feeds" +"Create this week's newsletter" +"Summarize my feeds from the last 7 days" +``` + +Choose a specific format: + +``` +"Create a topic deep dive about AI agents from this week's news" +"Generate a curated picks digest for this week" +"Write a weekly roundup newsletter" +``` + +Extend the date window: + +``` +"Generate a digest from the last 14 days" +"Not many articles this week, extend the window to 2 weeks" +``` + +Publish to Ghost: + +``` +"Generate this week's digest and publish it to Ghost as a draft" +"Create the newsletter and publish it to Ghost" +``` + +Output for Substack: + +``` +"Generate a newsletter digest for Substack" +"Create the digest and give me the Markdown version" +``` + +## Output + +| Output | Description | +|--------|-------------| +| HTML | Ready to paste into any CMS | +| Markdown | For Substack, Notion, Hashnode | +| Plain text | For email clients | +| Ghost draft | Published automatically if configured | + +## Substack Note + +Substack has no public API. The skill outputs a Markdown version of the digest for you to paste directly into the Substack editor. + +## Project Structure + +``` +newsletter-digest/ +├── SKILL.md +├── README.md +├── .env.example +├── package.json +├── feeds.json (your RSS feed list, edit this) +├── evals/ +│ └── evals.json +├── references/ +│ ├── digest-format.md (format rules, length targets, attribution) +│ └── output-template.md (HTML templates for all 3 formats) +└── scripts/ + ├── fetch-feeds.js (RSS fetching, dedup, date filtering) + └── ghost-publish.js (Ghost Admin API posting) +``` + +## License + +MIT diff --git a/docs/skills/content/noise-to-linkedin-carousel.mdx b/docs/skills/content/noise-to-linkedin-carousel.mdx new file mode 100644 index 0000000..242967e --- /dev/null +++ b/docs/skills/content/noise-to-linkedin-carousel.mdx @@ -0,0 +1,110 @@ +--- +title: "noise-to-linkedin-carousel" +description: "noise-to-linkedin-carousel turns rough notes, transcripts, and idea dumps into a LinkedIn-ready carousel content pack with a strong hook, clear slide-by-slid..." +--- + + + **Category:** Content · **Version:** `1.0.0` · **Author:** `ajaycodesitbetter` · **Compatibility:** All targets (claude, codex, opencode, gemini, anti-gravity, openclaw, hermes) + + +![noise-to-linkedin-carousel](./cover.png) + + +**noise-to-linkedin-carousel** turns rough notes, transcripts, and idea dumps into a LinkedIn-ready carousel content pack with a strong hook, clear slide-by-slide structure, and a CTA — built for founders, GTM teams, and technical marketers who think faster than they write. + +## Install + + + + ```bash + npx "@opendirectory.dev/skills" install noise-to-linkedin-carousel --target claude + ``` + + + ```bash + npx skills add Varnan-Tech/opendirectory --skill noise-to-linkedin-carousel + ``` + + + ```bash + /plugin marketplace add Varnan-Tech/opendirectory + /plugin install opendirectory-gtm-skills@opendirectory-marketplace + ``` + + + 1. Copy `https://github.com/Varnan-Tech/opendirectory/tree/main/skills/noise-to-linkedin-carousel` into [download-directory.github.io](https://download-directory.github.io/) to download the ZIP. + 2. Open **Claude Desktop** -> **Customize** -> **Skills** -> **+** -> **Upload a skill** and drop the folder containing `SKILL.md`. + + + [**Install noise-to-linkedin-carousel in Manus AI**](https://manus.im/import-skills?githubUrl=https%3A%2F%2Fgithub.com%2FVarnan-Tech%2Fopendirectory%2Ftree%2Fmain%2Fskills%2Fnoise-to-linkedin-carousel&utm_source=opendirectory) + + + + +## Why This Skill? + +Founders and technical operators often think in fragments: voice notes, bullet dumps, rambling transcripts, or Slack thoughts. They have valuable insights but lack a repeatable workflow to convert those noisy inputs into highly readable, LinkedIn-native carousel content. + +LinkedIn carousels routinely outperform single-image or text-only posts because they encourage swipe-through engagement and let you teach in a structured, visual way. While `linkedin-post-generator` focuses on crafting a single post, **noise-to-linkedin-carousel** is designed specifically to turn messy raw thinking into a multi-slide narrative that a founder, GTM engineer, or designer can immediately turn into a carousel asset. + +This agent skill helps by taking that unstructured "noise" and transforming it into a structured asset pack containing: +- 3 strong cover hook options +- 5-9 correctly sized insight slides (one idea per slide) +- A clear narrative progression +- A custom CTA slide +- A supporting LinkedIn caption + +## Prerequisites + +- [OpenDirectory CLI](https://github.com/Varnan-Tech/opendirectory) +- An OpenDirectory-compatible agent (e.g., **Anti-Gravity** or **OpenCode**) + +## Usage Examples + +Once installed, you can simply message your agent with noisy source material. + +**Example Prompt:** +> I recorded this rough voice note about why most devtools marketing fails. It’s a rant, not a clean outline. Here’s the transcript — turn this into a LinkedIn carousel I can hand to my designer: +> +> “okay so basically what i realized is that most devtools fail because they market features not use cases like everyone lists api endpoints and configs but nobody explains when you’d actually use this thing in production you know what i mean and founders think more features will solve it but the buyer just wants to know what problem disappears after they install you and how fast they get there” + +**Sample Output Shape:** + +- **Thesis:** + Most devtools fail because they market features instead of clear, real-world use cases. + +- **Hooks (3 options):** + 1. “90% of devtools die because they market features, not outcomes.” + 2. “Your devtool doesn’t have a feature problem. It has a use-case problem.” + 3. “If your devtool landing page looks like an API manual, this is for you.” + +- **Slide Breakdown (example):** + - **Slide 1 – Cover (Hook):** One of the hooks above. + - **Slide 2 – Problem:** What most devtools marketing looks like today. + - **Slide 3 – Insight:** Buyers buy outcomes and solved problems, not endpoints. + - **Slide 4 – Insight:** Why “more features” doesn’t fix the positioning gap. + - **Slide 5 – Example:** Before/after example of reframing features as use cases. + - **Slide 6 – Framework:** Simple checklist to rewrite your own devtool pitch. + - **Slide 7 – CTA:** Ask readers to audit their landing page or share with a founder. + +- **Caption:** + A LinkedIn-ready caption that tees up the carousel, adds 1–2 sentences of context, and ends with a natural CTA (e.g., “Reply ‘DEVS’ if you want a teardown of your current page”), plus 2–4 relevant hashtags. + +## Under the Hood + +Unlike simple text generators, this skill operates as a structured workflow: +1. **Thesis Extraction** - It strips away the noise to find the actual point. +2. **Hook Selection** - It maps the thesis to known high-performing LinkedIn hook patterns. +3. **Slide Constraint Enforcement** – It forces one main idea per slide and short, punchy copy so the deck feels like a high-signal LinkedIn carousel, not a pasted blog post. + +## File Architecture + +- `SKILL.md` - Core workflow instructions and formatting constraints. +- `references/output-format.md` - The deterministic output schema. +- `references/hook-patterns.md` - High-performing hook structures. +- `references/slide-types.md` - Rules for cover, context, insight, and CTA slides. +- `references/quality-checklist.md` - GTM-aligned checks run before returning output. + +## Contributing + +Pull requests to refine hook patterns, add new slide structures, or include helper scripts that refine raw transcripts are welcome. diff --git a/docs/skills/content/noise2blog.mdx b/docs/skills/content/noise2blog.mdx new file mode 100644 index 0000000..63d16dd --- /dev/null +++ b/docs/skills/content/noise2blog.mdx @@ -0,0 +1,143 @@ +--- +title: "noise2blog" +description: "Paste your rough notes, bullet points, voice transcript, or tweet dump and get a publication-ready blog post." +--- + + + **Category:** Content · **Version:** `1.0.0` · **Author:** `OpenDirectory` · **Compatibility:** All targets (claude, codex, opencode, gemini, anti-gravity, openclaw, hermes) + + +noise2blog + + +Paste your rough notes, bullet points, voice transcript, or tweet dump and get a publication-ready blog post. + +## Install + + + + ```bash + npx "@opendirectory.dev/skills" install noise2blog --target claude + ``` + + + ```bash + npx skills add Varnan-Tech/opendirectory --skill noise2blog + ``` + + + ```bash + /plugin marketplace add Varnan-Tech/opendirectory + /plugin install opendirectory-gtm-skills@opendirectory-marketplace + ``` + + + 1. Copy `https://github.com/Varnan-Tech/opendirectory/tree/main/skills/noise2blog` into [download-directory.github.io](https://download-directory.github.io/) to download the ZIP. + 2. Open **Claude Desktop** -> **Customize** -> **Skills** -> **+** -> **Upload a skill** and drop the folder containing `SKILL.md`. + + + [**Install noise2blog in Manus AI**](https://manus.im/import-skills?githubUrl=https%3A%2F%2Fgithub.com%2FVarnan-Tech%2Fopendirectory%2Ftree%2Fmain%2Fskills%2Fnoise2blog&utm_source=opendirectory) + + + + +## What It Does + +- Accepts any rough input: bullet points, rough notes, voice transcripts, tweet dumps, short drafts, or a URL +- Detects the right blog post style automatically (Technical Tutorial, Case Study, Thought Leadership, Explainer) +- Enriches claims with Tavily research when you set an API key (supporting data, verification) +- Generates a Markdown post with no AI slop, no em dashes, no banned words +- Formats frontmatter for Ghost, dev.to, Substack, or Hashnode on request + +## Requirements + +| Requirement | Purpose | How to Set Up | +|------------|---------|--------------| +| Google Gemini API key | Generates the blog post | aistudio.google.com, Get API key | +| Tavily API key (optional) | Enriches claims with research | app.tavily.com, API Keys | + +No LLM backend to run. The agent calls the Gemini API directly. + +## Setup + +```bash +cp .env.example .env +``` + +Edit `.env` and fill in: +- `GEMINI_API_KEY` (required) +- `TAVILY_API_KEY` (optional, enables research enrichment) + +## Blog Post Styles + +| Style | Use When | Signals in Your Input | +|-------|----------|----------------------| +| Technical Tutorial | Step-by-step guide, code walkthrough | Numbered steps, commands, "how to" | +| Case Study | Build log, before/after story, lessons learned | Specific results, journey narrative | +| Thought Leadership | Opinion piece, counterintuitive argument | Strong claim, debate framing | +| Explainer | Explaining a concept or tool to newcomers | Definition-first, comparisons | + +The agent detects the style automatically. Override it with: "Use Thought Leadership style" or "Make this a tutorial". + +## How to Use + +From pasted notes: + +``` +"Write a blog post from these notes: [paste your content]" +"Turn these bullet points into a blog post" +"Expand this into an article" +``` + +From a voice transcript: + +``` +"Turn this transcript into a blog post: [paste transcript]" +"Clean up this voice note and make it publishable" +``` + +From a tweet thread: + +``` +"Turn this tweet thread into a blog: [paste tweets]" +"Expand this thread into a full article" +``` + +With style override: + +``` +"Write a thought leadership post from these notes" +"Make this a technical tutorial" +``` + +With platform formatting: + +``` +"Write the post and format it for dev.to" +"Give me Ghost frontmatter too" +``` + +## Output + +- Full blog post in Markdown (800-1,800 words) +- Meta description (1-2 sentences) +- Alternative title option +- Platform-specific frontmatter on request + +## Project Structure + +``` +noise2blog/ +├── SKILL.md +├── README.md +├── .env.example +├── evals/ +│ └── evals.json +└── references/ + ├── blog-format.md + └── output-template.md +``` + +## License + +MIT diff --git a/docs/skills/content/store-listing-optimizer.mdx b/docs/skills/content/store-listing-optimizer.mdx new file mode 100644 index 0000000..eeaff0b --- /dev/null +++ b/docs/skills/content/store-listing-optimizer.mdx @@ -0,0 +1,58 @@ +--- +title: "store-listing-optimizer" +description: "Turn your competitor's complaints into your competitive advantage." +--- + + + **Category:** Content · **Version:** `1.0.0` · **Author:** `opendirectory` · **Compatibility:** All targets (claude, codex, opencode, gemini, anti-gravity, openclaw, hermes) + + +Turn your competitor's complaints into your competitive advantage. + +Given your own app's current store listing and a competitor complaint brief (e.g., generated by `app-store-review-arbitrage`), this skill rewrites your listing to explicitly pre-empt competitor flaws and optimize for ASO (App Store Optimization). + +## Install + + + + ```bash + npx "@opendirectory.dev/skills" install store-listing-optimizer --target claude + ``` + + + ```bash + npx skills add Varnan-Tech/opendirectory --skill store-listing-optimizer + ``` + + + ```bash + /plugin marketplace add Varnan-Tech/opendirectory + /plugin install opendirectory-gtm-skills@opendirectory-marketplace + ``` + + + 1. Copy `https://github.com/Varnan-Tech/opendirectory/tree/main/skills/store-listing-optimizer` into [download-directory.github.io](https://download-directory.github.io/) to download the ZIP. + 2. Open **Claude Desktop** -> **Customize** -> **Skills** -> **+** -> **Upload a skill** and drop the folder containing `SKILL.md`. + + + [**Install store-listing-optimizer in Manus AI**](https://manus.im/import-skills?githubUrl=https%3A%2F%2Fgithub.com%2FVarnan-Tech%2Fopendirectory%2Ftree%2Fmain%2Fskills%2Fstore-listing-optimizer&utm_source=opendirectory) + + + + +## What it does + +- **Audits** your current App Store or Google Play listing. +- **Cross-references** it against your competitor's broken promises and pain points. +- **Rewrites** your Title, Subtitle/Promotional Text, and Description to position you as the direct antidote to the competitor's flaws. +- **Enforces** strict character limits and ASO keyword best practices. + +## Usage + +1. Open your agent (e.g., Claude Code). +2. Ask it to run the skill: + > "Use the store-listing-optimizer skill. Here is my current app description: [PASTE DESCRIPTION]. Here is the competitor brief from the app-store-review-arbitrage skill: [PASTE BRIEF]." + +## Requirements + +No API keys or third-party packages required. This is a pure LLM skill. diff --git a/docs/skills/content/tweet-thread-from-blog.mdx b/docs/skills/content/tweet-thread-from-blog.mdx new file mode 100644 index 0000000..3da2b96 --- /dev/null +++ b/docs/skills/content/tweet-thread-from-blog.mdx @@ -0,0 +1,145 @@ +--- +title: "tweet-thread-from-blog" +description: "Turn any blog post or article into a Twitter/X thread. The agent reads the content, picks the right thread style, and writes 7-10 tweets with a strong hook,..." +--- + + + **Category:** Content · **Version:** `1.0.0` · **Author:** `OpenDirectory` · **Compatibility:** All targets (claude, codex, opencode, gemini, anti-gravity, openclaw, hermes) + + +tweet-thread-from-blog + + +Turn any blog post or article into a Twitter/X thread. The agent reads the content, picks the right thread style, and writes 7-10 tweets with a strong hook, one insight per tweet, and a CTA. Optionally posts the full thread to X via Composio using a reply chain. + +## Install + + + + ```bash + npx "@opendirectory.dev/skills" install tweet-thread-from-blog --target claude + ``` + + + ```bash + npx skills add Varnan-Tech/opendirectory --skill tweet-thread-from-blog + ``` + + + ```bash + /plugin marketplace add Varnan-Tech/opendirectory + /plugin install opendirectory-gtm-skills@opendirectory-marketplace + ``` + + + 1. Copy `https://github.com/Varnan-Tech/opendirectory/tree/main/skills/tweet-thread-from-blog` into [download-directory.github.io](https://download-directory.github.io/) to download the ZIP. + 2. Open **Claude Desktop** -> **Customize** -> **Skills** -> **+** -> **Upload a skill** and drop the folder containing `SKILL.md`. + + + [**Install tweet-thread-from-blog in Manus AI**](https://manus.im/import-skills?githubUrl=https%3A%2F%2Fgithub.com%2FVarnan-Tech%2Fopendirectory%2Ftree%2Fmain%2Fskills%2Ftweet-thread-from-blog&utm_source=opendirectory) + + + + +## Thread Styles + +| Style | Use When | Example Input | +|-------|----------|---------------| +| Data/Insight | Evidence-based article with stats or research findings | Engineering blog post with benchmark numbers | +| How-To | Tutorial or step-by-step guide | "How to set up X in 10 minutes" post | +| Story/Journey | Personal experience, build log, lessons learned | Indie hacker retrospective | +| Hot Take | Opinion piece, contrarian argument | "Why X is wrong" editorial | + +The agent auto-detects the right style. Override it by specifying the style in your prompt. + +## Requirements + +No LLM API key needed. The agent reads the page and writes the thread. + +**Note on X/Twitter posting:** Twitter's API v2 now requires a paid developer account (Basic tier, $100/month minimum). As a result, the Composio Twitter integration returns a 403 error for most users. The skill still generates complete, ready-to-post threads — just copy-paste them manually. Direct posting via Composio is documented below but is only viable if you have a paid Twitter developer account connected. + +## Setup + +### 1. Configure environment variables (optional) + +```bash +cp .env.example .env +# Add COMPOSIO_API_KEY if you want direct posting to X +``` + +### 2. Connect X/Twitter via Composio (optional, requires paid Twitter developer account) + +Twitter's API v2 now requires a paid developer account before Composio can post on your behalf. If you get a 403 error, this is why. Skip this step and use copy-paste output instead. + +1. Sign up for Twitter Developer Portal (Basic tier, ~$100/month): https://developer.twitter.com/en/portal/products +2. Get your Composio API key at: https://app.composio.dev/settings +3. Connect your X/Twitter account at: https://app.composio.dev/app/twitter +4. Complete the OAuth flow + +## How to Use + +From a URL: + +``` +"Turn this into a tweet thread: https://example.com/blog/post" +"Create a Twitter thread from this article: https://example.com/post" +"Write a tweet thread about this blog post: https://example.com/tutorial" +``` + +From pasted content: + +``` +"Make a thread from this: [paste article text]" +"Turn this into a Twitter thread: [paste blog post]" +``` + +With a style override: + +``` +"Turn this into a How-To thread: https://example.com/data-article" +"Write a Hot Take thread from this: https://example.com/opinion" +``` + +With direct posting (requires paid Twitter developer account + Composio setup): + +``` +"Post this blog post as a Twitter thread: https://example.com/post" +``` + +## Output + +| Output | Description | +|--------|-------------| +| Full thread | 7-10 numbered tweets, each under 280 characters | +| Alternative hook | A second hook tweet in a different format | +| Posted confirmation | If COMPOSIO_API_KEY is set and you confirm, the thread posts as a reply chain on X | + +## How Threads Are Formatted + +Hook first. Tweet 1 leads with the most surprising insight or a curiosity gap. It never announces the thread. + +One idea per tweet. If a tweet can be split, it gets split. Each tweet stands alone. + +Numbered throughout. Every tweet starts with its position: "1/8", "2/8", etc. + +CTA last. The final tweet is the only one with a URL or call to action. + +No hashtags. Hashtags reduce the quality signal of technical threads. + +## Project Structure + +``` +tweet-thread-from-blog/ +├── SKILL.md +├── README.md +├── .env.example +├── evals/ +│ └── evals.json +└── references/ + ├── thread-format.md + └── output-template.md +``` + +## License + +MIT diff --git a/docs/skills/developer-tools/claude-md-generator.mdx b/docs/skills/developer-tools/claude-md-generator.mdx new file mode 100644 index 0000000..bbfdbdb --- /dev/null +++ b/docs/skills/developer-tools/claude-md-generator.mdx @@ -0,0 +1,114 @@ +--- +title: "claude-md-generator" +description: "Reads your codebase and writes a CLAUDE.md that gives Claude Code the context it needs: build commands, code conventions, architecture notes, and gotchas. St..." +--- + + + **Category:** Developer Tools · **Version:** `1.0.0` · **Author:** `OpenDirectory` · **Compatibility:** All targets (claude, codex, opencode, gemini, anti-gravity, openclaw, hermes) + + +claude-md-generator + + +Reads your codebase and writes a CLAUDE.md that gives Claude Code the context it needs: build commands, code conventions, architecture notes, and gotchas. Stays under 200 lines. + +## Install + + + + ```bash + npx "@opendirectory.dev/skills" install claude-md-generator --target claude + ``` + + + ```bash + npx skills add Varnan-Tech/opendirectory --skill claude-md-generator + ``` + + + ```bash + /plugin marketplace add Varnan-Tech/opendirectory + /plugin install opendirectory-gtm-skills@opendirectory-marketplace + ``` + + + 1. Copy `https://github.com/Varnan-Tech/opendirectory/tree/main/skills/claude-md-generator` into [download-directory.github.io](https://download-directory.github.io/) to download the ZIP. + 2. Open **Claude Desktop** -> **Customize** -> **Skills** -> **+** -> **Upload a skill** and drop the folder containing `SKILL.md`. + + + [**Install claude-md-generator in Manus AI**](https://manus.im/import-skills?githubUrl=https%3A%2F%2Fgithub.com%2FVarnan-Tech%2Fopendirectory%2Ftree%2Fmain%2Fskills%2Fclaude-md-generator&utm_source=opendirectory) + + + + +## What It Does + +- Scans project files: package.json, tsconfig.json, linter configs, Makefile, directory structure +- Extracts all build, test, lint, and dev commands +- Identifies code style conventions that differ from defaults (path aliases, export patterns, naming) +- Maps non-obvious architecture decisions +- Finds gotchas: auto-generated files, required env var setup, test dependencies +- Generates CLAUDE.md using Gemini, then verifies it stays under 200 lines +- If CLAUDE.md already exists, improves it without discarding custom content + +## Requirements + +| Requirement | Purpose | How to Set Up | +|------------|---------|--------------| +| Gemini API key | CLAUDE.md generation from codebase analysis | aistudio.google.com, Get API key | + +## Setup + +```bash +cp .env.example .env +# Add GEMINI_API_KEY +``` + +## How to Use + +From the project root you want to document: +``` +"Generate a CLAUDE.md for this project" +"Create a CLAUDE.md" +"Write Claude configuration for this repo" +"Help Claude understand this codebase" +``` + +To update an existing CLAUDE.md: +``` +"Update my CLAUDE.md: we added Vitest and changed the build system" +"Improve my existing CLAUDE.md" +``` + +## What Goes in CLAUDE.md + +| Section | Include | Skip | +|---------|---------|------| +| Commands | Exact runnable commands, flags needed, env vars required | `npm install` and other obvious ones | +| Architecture | Non-obvious structure, auto-generated directories | "src contains source files" | +| Code Style | Path aliases, export conventions, non-default settings | Indent size (formatter handles it) | +| Testing | Required setup, how to run one test | "we use Jest" (visible from package.json) | +| Gotchas | Auto-generated files, env var order, known intentional issues | Things derivable from the code | + +## Why Under 200 Lines + +Long CLAUDE.md files get ignored. Claude loads the full file into context every session: a bloated CLAUDE.md with obvious content trains Claude to skim it. A tight 100-150 line CLAUDE.md with only non-obvious facts gets read and used. + +The skill cuts aggressively: if a section says only things Claude can infer from the code, it removes it. + +## Project Structure + +``` +claude-md-generator/ +├── SKILL.md +├── README.md +├── .env.example +├── evals/ +│ └── evals.json +└── references/ + └── section-guide.md +``` + +## License + +MIT diff --git a/docs/skills/developer-tools/dependency-update-bot.mdx b/docs/skills/developer-tools/dependency-update-bot.mdx new file mode 100644 index 0000000..efd2a86 --- /dev/null +++ b/docs/skills/developer-tools/dependency-update-bot.mdx @@ -0,0 +1,137 @@ +--- +title: "dependency-update-bot" +description: "Weekly scan for outdated npm or pip packages. Fetches changelogs for each. Summarizes breaking changes with Gemini. Opens one PR per risk group." +--- + + + **Category:** Developer Tools · **Version:** `1.0.0` · **Author:** `OpenDirectory` · **Compatibility:** All targets (claude, codex, opencode, gemini, anti-gravity, openclaw, hermes) + + +dependency-update-bot + + +Weekly scan for outdated npm or pip packages. Fetches changelogs for each. Summarizes breaking changes with Gemini. Opens one PR per risk group. + +## Install + + + + ```bash + npx "@opendirectory.dev/skills" install dependency-update-bot --target claude + ``` + + + ```bash + npx skills add Varnan-Tech/opendirectory --skill dependency-update-bot + ``` + + + ```bash + /plugin marketplace add Varnan-Tech/opendirectory + /plugin install opendirectory-gtm-skills@opendirectory-marketplace + ``` + + + 1. Copy `https://github.com/Varnan-Tech/opendirectory/tree/main/skills/dependency-update-bot` into [download-directory.github.io](https://download-directory.github.io/) to download the ZIP. + 2. Open **Claude Desktop** -> **Customize** -> **Skills** -> **+** -> **Upload a skill** and drop the folder containing `SKILL.md`. + + + [**Install dependency-update-bot in Manus AI**](https://manus.im/import-skills?githubUrl=https%3A%2F%2Fgithub.com%2FVarnan-Tech%2Fopendirectory%2Ftree%2Fmain%2Fskills%2Fdependency-update-bot&utm_source=opendirectory) + + + + +## What It Does + +- Runs `npm outdated --json` or `pip list --outdated` to find outdated packages +- Classifies each update as patch (low risk), minor (medium risk), or major (high risk) using semver +- Fetches changelogs from GitHub Releases, CHANGELOG.md, or npm/PyPI registry as fallback +- Uses Gemini to summarize what changed between old and new versions, flagging breaking changes +- Creates a branch per risk group, updates the package file, and opens a PR with the changelog summary +- Opens one PR per major update (since each major bump needs individual review) + +## Requirements + +| Requirement | Purpose | How to Set Up | +|------------|---------|--------------| +| Gemini API key | Changelog summarization | aistudio.google.com, Get API key | +| GitHub CLI authenticated | PR creation | `gh auth login` | +| GitHub token (optional) | Higher rate limit for changelog fetching | github.com/settings/tokens, read-only scope | + +## Setup + +```bash +cp .env.example .env +``` + +Fill in: +- `GEMINI_API_KEY` (required) +- `GITHUB_TOKEN` (optional, increases GitHub API rate limit from 60 to 5,000 requests/hour) + +## How to Use + +Scan npm dependencies: +``` +"Check for outdated packages" +"Update my dependencies and open PRs" +"Run the dependency update bot" +``` + +Scan pip dependencies: +``` +"Check my Python packages for updates" +"Scan requirements.txt for outdated dependencies" +``` + +Specific risk level only: +``` +"Only open PRs for patch updates today" +"Show me which packages have major version updates" +``` + +## PR Structure + +Each PR includes: +- Risk level label (patch / minor / major) +- For each package: version bump, changelog summary (3-5 bullets), breaking changes flagged with BREAKING prefix +- How to verify section + +**One PR per risk group** for patch and minor updates. **One PR per package** for major updates (since each breaking change needs individual review). + +## Risk Classification + +| Level | Version Change | Example | Action | +|-------|---------------|---------|--------| +| Patch | Z in X.Y.Z | 4.17.19 to 4.17.21 | Safe to merge after CI passes | +| Minor | Y in X.Y.Z | 4.17.x to 4.18.x | Review changelog before merging | +| Major | X in X.Y.Z | 4.x.x to 5.x.x | Read changelog carefully, test thoroughly | + +If a patch or minor update's changelog contains BREAKING CHANGE keywords, the bot escalates it to major automatically. + +## Changelog Sources + +The bot tries these sources in order for each package: + +1. GitHub Releases API (best) +2. Raw CHANGELOG.md from the repo +3. npm registry README (fallback) +4. PyPI project description (last resort) + +If no changelog is found, the PR still includes the version bump with a note to review manually. + +## Project Structure + +``` +dependency-update-bot/ +├── SKILL.md +├── README.md +├── .env.example +├── evals/ +│ └── evals.json +└── references/ + └── changelog-patterns.md +``` + +## License + +MIT diff --git a/docs/skills/developer-tools/docs-from-code.mdx b/docs/skills/developer-tools/docs-from-code.mdx new file mode 100644 index 0000000..5c1a915 --- /dev/null +++ b/docs/skills/developer-tools/docs-from-code.mdx @@ -0,0 +1,133 @@ +--- +title: "docs-from-code" +description: "Automatically generate and maintain README.md, API reference docs, and an Architecture section by reading your codebase. Uses graphify to build a knowledge g..." +--- + + + **Category:** Developer Tools · **Version:** `1.0.0` · **Author:** `OpenDirectory` · **Compatibility:** All targets (claude, codex, opencode, gemini, anti-gravity, openclaw, hermes) + + +![docs-from-code](https://github.com/user-attachments/assets/493c7c61-9aa9-48e9-a71b-7c77c8c6a949) + +Automatically generate and maintain README.md, API reference docs, and an Architecture section by reading your codebase. Uses [graphify](https://github.com/safishamsi/graphify) to build a knowledge graph first, then uses AI to write clean documentation grounded in what actually exists. + +## Install + + + + ```bash + npx "@opendirectory.dev/skills" install docs-from-code --target claude + ``` + + + ```bash + npx skills add Varnan-Tech/opendirectory --skill docs-from-code + ``` + + + ```bash + /plugin marketplace add Varnan-Tech/opendirectory + /plugin install opendirectory-gtm-skills@opendirectory-marketplace + ``` + + + 1. Copy `https://github.com/Varnan-Tech/opendirectory/tree/main/skills/docs-from-code` into [download-directory.github.io](https://download-directory.github.io/) to download the ZIP. + 2. Open **Claude Desktop** -> **Customize** -> **Skills** -> **+** -> **Upload a skill** and drop the folder containing `SKILL.md`. + + + [**Install docs-from-code in Manus AI**](https://manus.im/import-skills?githubUrl=https%3A%2F%2Fgithub.com%2FVarnan-Tech%2Fopendirectory%2Ftree%2Fmain%2Fskills%2Fdocs-from-code&utm_source=opendirectory) + + + + +## What It Generates + +| Output | When | +|--------|------| +| `README.md` (full) | Project has no README | +| `README.md` (sections) | README exists but API or architecture sections are stale | +| `docs/API.md` | Project has HTTP routes | +| Architecture section | Always, from graphify's god nodes and communities | +| GitHub PR | When you ask it to open one | + +## Why graphify? + +The skill uses graphify as its extraction engine: +- 20 languages via tree-sitter AST: Python, TypeScript, Go, Rust, Java, and 15 more +- Architecture insight: god nodes and community clusters show what everything connects through +- 71.5x fewer tokens than reading raw files, efficient on large codebases +- SHA256 cache: re-runs only process changed files +- Honest tagging: `EXTRACTED` (found in source) vs `INFERRED` (reasonable inference with confidence score) +- Extracts rationale from `# NOTE:`, `# WHY:`, `# HACK:` comments and docstrings + +The bundled `scripts/` (TypeScript and Python AST extractors) serve as a fallback if graphify is unavailable. + +## Supported Languages (via graphify) + +Python, TypeScript, JavaScript, Go, Rust, Java, C, C++, Ruby, C#, Kotlin, Scala, PHP, Swift, Lua, Zig, PowerShell, Elixir, Objective-C, Julia + +## Requirements + +- Python 3.10+ (for graphify) +- Node.js 18+ (for fallback TypeScript extractor) +- `gh` CLI (optional, for opening PRs automatically) +- `GITHUB_TOKEN` env var (optional, for PRs) + +## Setup + +### 1. Set up graphify + +```bash +pip install graphifyy +``` + +No API keys needed for extraction. graphify uses your agent's existing model access. + +### 2. Configure (Optional) + +```bash +cp .env.example .env +# Add GITHUB_TOKEN if you want auto-PR support +``` + +## How to Use + +Be inside your project and ask: + +``` +"Generate a README for this project" +"My API docs are out of date, update them from the code" +"Create docs/API.md from my FastAPI routes" +"Add an architecture section to our README" +"Document this TypeScript library" +``` + +The agent will: +1. Run `graphify . --no-viz` to build a knowledge graph of your codebase +2. Read `GRAPH_REPORT.md` for god nodes, communities, and architecture insights +3. Query the graph for routes, types, and data models +4. Read existing docs to understand what needs updating +5. Generate accurate docs grounded in the graph +6. Write files and optionally open a GitHub PR + +## Project Structure + +``` +docs-from-code/ +├── SKILL.md # Agent instructions +├── README.md # This file +├── .env.example # Environment variables template +├── scripts/ +│ ├── package.json # Script dependencies (ts-morph) +│ ├── extract_ts.ts # TypeScript/JS AST extractor +│ └── extract_py.py # Python AST extractor +├── references/ +│ ├── extraction-guide.md # Per-framework extraction notes +│ └── output-template.md # README and API.md templates +└── evals/ + └── evals.json # Test prompts +``` + +## License + +MIT diff --git a/docs/skills/developer-tools/dx-roaster.mdx b/docs/skills/developer-tools/dx-roaster.mdx new file mode 100644 index 0000000..af5db4c --- /dev/null +++ b/docs/skills/developer-tools/dx-roaster.mdx @@ -0,0 +1,154 @@ +--- +title: "dx-roaster" +description: "Brutally honest developer-experience audit for a GitHub repo. Scores 10 DX dimensions, writes a roast in your chosen tone, ships a prioritized fix list, and..." +--- + + + **Category:** Developer Tools · **Version:** `1.0.0` · **Author:** `OpenDirectory` · **Compatibility:** All targets (claude, codex, opencode, gemini, anti-gravity, openclaw, hermes) + + +Brutally honest developer-experience audit for a GitHub repo. Scores 10 DX dimensions, writes a roast in your chosen tone, ships a prioritized fix list, and sketches what your README could look like. + +Use it before Show HN, Product Hunt, npm publish, or any launch where the first five minutes decide whether visitors stay or bounce. + +This is not a security scan or a linter. It judges the same thing a stranger would in 30 seconds: can I understand this, install it, and run it? + +--- + +## Install + + + + ```bash + npx "@opendirectory.dev/skills" install dx-roaster --target claude + ``` + + + ```bash + npx skills add Varnan-Tech/opendirectory --skill dx-roaster + ``` + + + ```bash + /plugin marketplace add Varnan-Tech/opendirectory + /plugin install opendirectory-gtm-skills@opendirectory-marketplace + ``` + + + 1. Copy `https://github.com/Varnan-Tech/opendirectory/tree/main/skills/dx-roaster` into [download-directory.github.io](https://download-directory.github.io/) to download the ZIP. + 2. Open **Claude Desktop** -> **Customize** -> **Skills** -> **+** -> **Upload a skill** and drop the folder containing `SKILL.md`. + + + [**Install dx-roaster in Manus AI**](https://manus.im/import-skills?githubUrl=https%3A%2F%2Fgithub.com%2FVarnan-Tech%2Fopendirectory%2Ftree%2Fmain%2Fskills%2Fdx-roaster&utm_source=opendirectory) + + + + +## How It Works + +1. You point the skill at a repo (local path or GitHub URL) and pick a tone. +2. The agent scans the README, install steps, code samples, docs, examples, badges, community files, license, and recent activity. +3. It scores 10 DX dimensions on a 0–10 scale. +4. It writes four files: a shareable roast, a prioritized fix list, an ideal-README sketch, and raw scores. + +The whole thing runs in under a minute. No external services. Read-only on your repo. + +--- + +## The 10 Dimensions + +| Dimension | What it measures | +|---|---| +| Time-to-first-success | How fast a new user goes from landing to a working example | +| What-is-this clarity | Whether a stranger gets the value prop in 5 seconds | +| Visual proof | Gif/screenshot/video presence and position | +| Install simplicity | One-command vs. multi-step matrix | +| Runnable quick-start | Whether the example actually works | +| Documentation depth | README, docs/, external docs site | +| Examples | Number and quality of working examples | +| Community signals | CONTRIBUTING.md, CoC, templates, chat link | +| Trust signals | License, CI, recent commits, contributor count | +| Marketing signals | Tagline, homepage, social links, badges | + +Total: 100 points. Grades: A (90+), B (75–89), C (60–74), D (40–59), F (<40). + +--- + +## Input Parameters + +| Parameter | Required | Default | Description | +|---|---|---|---| +| `repo` | Yes | `.` (current dir) | Local path OR `https://github.com/owner/repo` URL | +| `tone` | | `honest` | `brutal` / `honest` / `kind` | +| `output_dir` | | `dx-roast/` | Where to write the 4 output files | +| `compare_to` | | | Optional second repo URL for benchmark comparison | + +--- + +## Tone Reference + +| Tone | Voice | Best for | +|---|---|---| +| `brutal` | Battle-scarred CTO. Cutting, dryly funny. Punches the work, not the person. | Shareable Twitter post. Last-resort wake-up call. | +| `honest` | Senior engineer code review. Direct, kind, specific. (default) | Most cases. Internal sharing with the team. | +| `kind` | Encouraging mentor. Specific issues framed as opportunities. | Solo maintainers. First-time OSS authors. | + +--- + +## Output + +``` +dx-roast/ +├── roast.md # 3–5 paragraph review in your tone +├── action-plan.md # 5–10 prioritized fixes +├── ideal-readme.md # Sketch of what your README could be +└── score.json # Raw scores per dimension +``` + +The roast is built to be shareable. Tweet an excerpt. Paste in Slack. Forward to your co-founder. + +--- + +## Prompt Examples + +Good: +``` +Roast my repo. Tone: brutal. +``` + +Good: +``` +DX audit on https://github.com/myorg/mytool. Compare to https://github.com/vercel/next.js. +``` + +Good: +``` +Run dx-roaster on the current directory with tone=kind. Save outputs to ./pre-launch/. +``` + +Bad: +``` +Tell me if my repo is good. +``` + +(Too vague. The skill needs at minimum a repo path; everything else has good defaults.) + +--- + +## Prompt Tips + +Be brave. The brutal tone is funny, but it cuts deep. If you're not ready to read what's wrong with your repo, use `honest` or `kind`. + +Share the output. Roasts are designed to be shareable. A grade-D roast posted with the eventual fix is great open-build content. + +Run it before launch, not after. The action plan items are typically 5 minutes to 2 hours. Most are doable the night before Show HN. + +Compare to one repo, not five. The benchmark feature works best when you pick a single repo whose DX you envy. + +--- + +## Requirements + +- Claude Code, Gemini CLI, or GitHub Copilot +- `gh` CLI (only needed if the input is a GitHub URL; not needed for local paths) +- Read access to the target repo (local file system or public GitHub repo) diff --git a/docs/skills/developer-tools/explain-this-pr.mdx b/docs/skills/developer-tools/explain-this-pr.mdx new file mode 100644 index 0000000..5a853e2 --- /dev/null +++ b/docs/skills/developer-tools/explain-this-pr.mdx @@ -0,0 +1,110 @@ +--- +title: "explain-this-pr" +description: "Point this skill at any GitHub PR and it writes a plain-English explanation of what changed and why, then posts it as a PR comment." +--- + + + **Category:** Developer Tools · **Version:** `1.0.0` · **Author:** `OpenDirectory` · **Compatibility:** All targets (claude, codex, opencode, gemini, anti-gravity, openclaw, hermes) + + +explain-this-pr + + +Point this skill at any GitHub PR and it writes a plain-English explanation of what changed and why, then posts it as a PR comment. + +## Install + + + + ```bash + npx "@opendirectory.dev/skills" install explain-this-pr --target claude + ``` + + + ```bash + npx skills add Varnan-Tech/opendirectory --skill explain-this-pr + ``` + + + ```bash + /plugin marketplace add Varnan-Tech/opendirectory + /plugin install opendirectory-gtm-skills@opendirectory-marketplace + ``` + + + 1. Copy `https://github.com/Varnan-Tech/opendirectory/tree/main/skills/explain-this-pr` into [download-directory.github.io](https://download-directory.github.io/) to download the ZIP. + 2. Open **Claude Desktop** -> **Customize** -> **Skills** -> **+** -> **Upload a skill** and drop the folder containing `SKILL.md`. + + + [**Install explain-this-pr in Manus AI**](https://manus.im/import-skills?githubUrl=https%3A%2F%2Fgithub.com%2FVarnan-Tech%2Fopendirectory%2Ftree%2Fmain%2Fskills%2Fexplain-this-pr&utm_source=opendirectory) + + + + +## What It Does + +- Fetches the PR diff and metadata via `gh` +- Writes two paragraphs: what changed (technical) and why it matters (impact) +- Posts the explanation as a PR comment with `gh pr comment` +- Works with any public or private repo you have access to via `gh` + +## Requirements + +| Requirement | Purpose | How to Set Up | +|------------|---------|--------------| +| `gh` CLI | Fetching PR data and posting comments | https://cli.github.com, then run `gh auth login` | + +No API keys needed. + +## How to Use + +Explain a PR by URL: + +``` +"Explain this PR: https://github.com/owner/repo/pull/123" +"What does this PR do? https://github.com/owner/repo/pull/456" +"Summarize this pull request: [URL]" +``` + +Explain by PR number (in the current repo): + +``` +"Explain PR #42" +"Add a summary comment to PR #99" +``` + +Explain the current branch PR: + +``` +"Explain the current branch PR" +"Add a plain-English comment to my PR" +``` + +Output without posting: + +``` +"Explain this PR but don't post the comment: [URL]" +"What does this PR change? Just give me the text." +``` + +## Output Format + +Two paragraphs, under 150 words total. + +Paragraph 1: What it does (technical). Names the specific files, functions, or systems that changed. States the before/after if visible in the diff. + +Paragraph 2: Why it matters (impact). Explains who benefits and what problem is solved. Omitted if there is no clear "why" in the diff or commits. The skill never guesses at impact. + +## Project Structure + +``` +explain-this-pr/ +├── SKILL.md +├── README.md +└── evals/ + └── evals.json +``` + +## License + +MIT diff --git a/docs/skills/developer-tools/kill-the-standup.mdx b/docs/skills/developer-tools/kill-the-standup.mdx new file mode 100644 index 0000000..b43fe03 --- /dev/null +++ b/docs/skills/developer-tools/kill-the-standup.mdx @@ -0,0 +1,120 @@ +--- +title: "kill-the-standup" +description: "Write your daily standup in seconds. The skill reads yesterday's Linear issues and GitHub commits, formats a done/doing/blockers update, and posts it to Slack." +--- + + + **Category:** Developer Tools · **Version:** `1.0.0` · **Author:** `OpenDirectory` · **Compatibility:** All targets (claude, codex, opencode, gemini, anti-gravity, openclaw, hermes) + + +kill-the-standup + + +Write your daily standup in seconds. The skill reads yesterday's Linear issues and GitHub commits, formats a done/doing/blockers update, and posts it to Slack. + +## Install + + + + ```bash + npx "@opendirectory.dev/skills" install kill-the-standup --target claude + ``` + + + ```bash + npx skills add Varnan-Tech/opendirectory --skill kill-the-standup + ``` + + + ```bash + /plugin marketplace add Varnan-Tech/opendirectory + /plugin install opendirectory-gtm-skills@opendirectory-marketplace + ``` + + + 1. Copy `https://github.com/Varnan-Tech/opendirectory/tree/main/skills/kill-the-standup` into [download-directory.github.io](https://download-directory.github.io/) to download the ZIP. + 2. Open **Claude Desktop** -> **Customize** -> **Skills** -> **+** -> **Upload a skill** and drop the folder containing `SKILL.md`. + + + [**Install kill-the-standup in Manus AI**](https://manus.im/import-skills?githubUrl=https%3A%2F%2Fgithub.com%2FVarnan-Tech%2Fopendirectory%2Ftree%2Fmain%2Fskills%2Fkill-the-standup&utm_source=opendirectory) + + + + +## What It Does + +- Fetches yesterday's Linear issues assigned to you (completed and in-progress) +- Fetches yesterday's GitHub commits from your configured repo +- Formats a three-section standup: Done, Doing, Blockers +- Posts to your Slack channel via Incoming Webhook + +## Requirements + +| Requirement | Purpose | How to Set Up | +|------------|---------|--------------| +| Linear API key | Fetching your issues | Linear, Settings, API, Personal API keys | +| Slack Incoming Webhook | Posting the standup | api.slack.com/apps, Your App, Incoming Webhooks | +| `gh` CLI (optional) | Fetching GitHub commits | https://cli.github.com, then run `gh auth login` | + +No LLM API key needed. The agent reads your activity directly. + +## Setup + +```bash +cp .env.example .env +``` + +Edit `.env` and fill in: +- `LINEAR_API_KEY` (required) +- `SLACK_WEBHOOK_URL` (required) +- `GITHUB_REPO` (optional, format: `owner/repo`) +- `GITHUB_USERNAME` (optional, defaults to your gh auth username) + +## How to Use + +Write and post standup: + +``` +"Write my standup" +"Post my standup to Slack" +"Generate standup update" +``` + +Output only, no Slack post: + +``` +"Write my standup but don't post it" +"What did I do yesterday?" +"Give me my standup text" +``` + +## Output Format + +``` +Done +- [ENG-123] Fix session timeout bug +- fix: remove duplicate middleware registration + +Doing +- [ENG-124] Migrate auth to OAuth2 + +Blockers +No blockers. +``` + +## Project Structure + +``` +kill-the-standup/ +├── SKILL.md +├── README.md +├── .env.example +├── evals/ +│ └── evals.json +└── references/ + └── standup-format.md +``` + +## License + +MIT diff --git a/docs/skills/developer-tools/llms-txt-generator.mdx b/docs/skills/developer-tools/llms-txt-generator.mdx new file mode 100644 index 0000000..877c9ca --- /dev/null +++ b/docs/skills/developer-tools/llms-txt-generator.mdx @@ -0,0 +1,178 @@ +--- +title: "llms-txt-generator" +description: "Generate a standards-compliant llms.txt file for any website. Makes your site fully readable and citable by AI agents the GEO (Generative Engine Optimization..." +--- + + + **Category:** Developer Tools · **Version:** `1.0.0` · **Author:** `OpenDirectory` · **Compatibility:** All targets (claude, codex, opencode, gemini, anti-gravity, openclaw, hermes) + + +llms-txt-generator + +Generate a standards-compliant `llms.txt` file for any website. Makes your site fully readable and citable by AI agents the GEO (Generative Engine Optimization) equivalent of having a great sitemap. + +## Install + + + + ```bash + npx "@opendirectory.dev/skills" install llms-txt-generator --target claude + ``` + + + ```bash + npx skills add Varnan-Tech/opendirectory --skill llms-txt-generator + ``` + + + ```bash + /plugin marketplace add Varnan-Tech/opendirectory + /plugin install opendirectory-gtm-skills@opendirectory-marketplace + ``` + + + 1. Copy `https://github.com/Varnan-Tech/opendirectory/tree/main/skills/llms-txt-generator` into [download-directory.github.io](https://download-directory.github.io/) to download the ZIP. + 2. Open **Claude Desktop** -> **Customize** -> **Skills** -> **+** -> **Upload a skill** and drop the folder containing `SKILL.md`. + + + [**Install llms-txt-generator in Manus AI**](https://manus.im/import-skills?githubUrl=https%3A%2F%2Fgithub.com%2FVarnan-Tech%2Fopendirectory%2Ftree%2Fmain%2Fskills%2Fllms-txt-generator&utm_source=opendirectory) + + + + +## What It Does + +The skill crawls your website using Chrome DevTools, reads your actual pages, and produces a clean `llms.txt` file in the format specified by [Jeremy Howard's llms.txt standard](https://llmstxt.org). When AI agents (Claude, ChatGPT, Gemini) visit your site, they read `llms.txt` first to understand what you are and where to find authoritative content. + +**Without llms.txt:** AI agents guess, hallucinate, or cite competitors instead. +**With llms.txt:** AI agents cite your product correctly and know exactly where your docs, blog, and key pages live. + +## Two Modes + +### Codebase Mode (no Chrome needed) +If you're inside a website's repo, the skill reads your source files directly pages, routes, blog posts, frontmatter, site config. It writes `llms.txt` straight to `public/` when you approve. No browser required. + +Supported frameworks: **Next.js** (pages + app router), **Astro**, **Nuxt**, **Gatsby**, **SvelteKit**, **Hugo**, **Jekyll** + +### Live Site Mode (Chrome or fetch fallback) +If you only have the URL, the skill crawls the live site using Chrome DevTools MCP. Falls back to standard web fetch if Chrome isn't available. + +--- + +## Requirements + +**Codebase Mode:** No extra setup. Just be inside the repo directory. + +**Live Site Mode:** +- Chrome with remote debugging enabled (or any live URL skill will fall back to web fetch) +- Chrome DevTools MCP server configured in your agent (optional, improves JS-rendered sites) + +## Setup + +### For Live Site Mode: Start Chrome with Remote Debugging + +**Mac:** +```bash +open -a "Google Chrome" --args --remote-debugging-port=9222 +``` + +**Linux:** +```bash +google-chrome --remote-debugging-port=9222 +``` + +**Windows:** +```bash +chrome.exe --remote-debugging-port=9222 +``` + +### 2. Set up Chrome DevTools MCP Server + +Follow the setup at: https://github.com/ChromeDevTools/chrome-devtools-mcp + +Add to your agent's MCP configuration: +```json +{ + "mcpServers": { + "chrome-devtools": { + "command": "npx", + "args": ["-y", "@chrome-devtools/mcp-server"], + "env": { + "CHROME_DEBUGGING_PORT": "9222" + } + } + } +} +``` + +### 3. Configure Environment (Optional) + +Copy `.env.example` to `.env` and fill in: +```bash +cp .env.example .env +``` + +`GITHUB_TOKEN` and `GITHUB_REPO` are only needed if you want the agent to automatically open a GitHub PR with the generated file. + +## How to Use + +**Codebase Mode** just be inside your project and ask: +``` +"Generate an llms.txt for this site" +"Add llms.txt to this project" +"Make this site readable by AI agents" +``` + +The agent will detect your framework, read your pages and blog posts from source, generate `llms.txt`, and write it to the right directory (e.g. `public/llms.txt`) after you confirm. + +**Live Site Mode** provide a URL: +``` +"Generate an llms.txt for https://yoursite.com" +"Does https://yoursite.com have an llms.txt? If not, create one." +``` + +The agent will: +1. Check if `llms.txt` already exists at the domain +2. Crawl homepage, docs, blog, about, pricing, and API pages +3. Generate `llms.txt` following the official spec +4. Optionally generate `llms-full.txt` with full page content +5. Save the file locally and give you deployment instructions +6. Optionally open a GitHub PR if configured + +## Where to Deploy the File + +Place `llms.txt` at your web root so it's accessible at `https://yourdomain.com/llms.txt`: + +| Platform | File Location | +|----------|--------------| +| Next.js / Vercel | `/public/llms.txt` | +| Astro | `/public/llms.txt` | +| Nuxt | `/public/llms.txt` | +| GitHub Pages | Repository root | +| Hugo | `/static/llms.txt` | +| WordPress | Upload via FTP to web root | + +## Output Files + +| File | Description | +|------|-------------| +| `llms.txt` | Structured link map. LLMs follow links to find content | +| `llms-full.txt` | Full prose content of key pages. LLMs ingest everything at once | + +## Project Structure + +``` +llms-txt-generator/ +├── SKILL.md # Agent instructions +├── README.md # This file +├── .env.example # Environment variables template +├── evals/ +│ └── evals.json # Test prompts for skill evaluation +└── references/ + ├── llms-txt-spec.md # The llms.txt format specification + └── output-template.md # Exact output template with example +``` + +## License + +MIT diff --git a/docs/skills/developer-tools/pr-description-writer.mdx b/docs/skills/developer-tools/pr-description-writer.mdx new file mode 100644 index 0000000..2b0a7dc --- /dev/null +++ b/docs/skills/developer-tools/pr-description-writer.mdx @@ -0,0 +1,117 @@ +--- +title: "pr-description-writer" +description: "Read your current git branch diff and generate a complete GitHub pull request description: summary, specific change bullets, and testing steps. Create or upd..." +--- + + + **Category:** Developer Tools · **Version:** `1.0.0` · **Author:** `OpenDirectory` · **Compatibility:** All targets (claude, codex, opencode, gemini, anti-gravity, openclaw, hermes) + + +pr-description-writer + + +Read your current git branch diff and generate a complete GitHub pull request description: summary, specific change bullets, and testing steps. Create or update the PR in one step. + +## Install + + + + ```bash + npx "@opendirectory.dev/skills" install pr-description-writer --target claude + ``` + + + ```bash + npx skills add Varnan-Tech/opendirectory --skill pr-description-writer + ``` + + + ```bash + /plugin marketplace add Varnan-Tech/opendirectory + /plugin install opendirectory-gtm-skills@opendirectory-marketplace + ``` + + + 1. Copy `https://github.com/Varnan-Tech/opendirectory/tree/main/skills/pr-description-writer` into [download-directory.github.io](https://download-directory.github.io/) to download the ZIP. + 2. Open **Claude Desktop** -> **Customize** -> **Skills** -> **+** -> **Upload a skill** and drop the folder containing `SKILL.md`. + + + [**Install pr-description-writer in Manus AI**](https://manus.im/import-skills?githubUrl=https%3A%2F%2Fgithub.com%2FVarnan-Tech%2Fopendirectory%2Ftree%2Fmain%2Fskills%2Fpr-description-writer&utm_source=opendirectory) + + + + +## What It Does + +- Reads `git diff main...HEAD` to understand what changed +- Reads commit messages for context on why it changed +- Generates a structured PR description following a consistent format +- Creates a new PR with `gh pr create` or updates an existing one with `gh pr edit` + +## Requirements + +| Requirement | Purpose | How to Set Up | +|------------|---------|--------------| +| `gh` CLI | Creating and updating PRs | https://cli.github.com, then run `gh auth login` | +| Git repo with a branch | Source diff | Run from inside the repo | + +No API keys needed. The agent reads the diff directly and writes the description. + +## How to Use + +Write a description for the current branch: + +``` +"Write a PR description for my current branch" +"Draft my PR" +"Generate a PR description" +``` + +Create the PR at the same time: + +``` +"Create a PR for this branch with a good description" +"Open a PR and write the description" +``` + +Update an existing PR's description: + +``` +"Update my PR description" +"Rewrite the PR body based on the latest changes" +``` + +Output only, no gh commands: + +``` +"Write a PR description but just give me the text" +"Draft the PR description, I'll paste it myself" +``` + +## Output Format + +Every generated description includes: + +| Section | Content | +|---------|---------| +| Summary | 1-2 sentences on what this PR does and why | +| Changes | Specific bullets, one per logical change, starting with a verb | +| Testing | Actionable steps to verify the change works | +| Screenshots | Only for UI changes | +| Linked Issues | Only if the branch fixes a tracked issue | + +## Project Structure + +``` +pr-description-writer/ +├── SKILL.md +├── README.md +├── evals/ +│ └── evals.json +└── references/ + └── pr-format-guide.md +``` + +## License + +MIT diff --git a/docs/skills/developer-tools/schema-markup-generator.mdx b/docs/skills/developer-tools/schema-markup-generator.mdx new file mode 100644 index 0000000..171b4e9 --- /dev/null +++ b/docs/skills/developer-tools/schema-markup-generator.mdx @@ -0,0 +1,150 @@ +--- +title: "schema-markup-generator" +description: "Generate valid JSON-LD structured data for any webpage. The agent crawls the page, detects which schema types apply, and outputs a script tag ready to paste..." +--- + + + **Category:** Developer Tools · **Version:** `1.0.0` · **Author:** `OpenDirectory` · **Compatibility:** All targets (claude, codex, opencode, gemini, anti-gravity, openclaw, hermes) + + +![schema-markup-generator](https://github.com/user-attachments/assets/4b5e5bfb-3c33-4a20-afff-59fda19196b4) + + +Generate valid JSON-LD structured data for any webpage. The agent crawls the page, detects which schema types apply, and outputs a script tag ready to paste into your HTML. Optionally opens a GitHub PR with the markup injected. + +## Install + + + + ```bash + npx "@opendirectory.dev/skills" install schema-markup-generator --target claude + ``` + + + ```bash + npx skills add Varnan-Tech/opendirectory --skill schema-markup-generator + ``` + + + ```bash + /plugin marketplace add Varnan-Tech/opendirectory + /plugin install opendirectory-gtm-skills@opendirectory-marketplace + ``` + + + 1. Copy `https://github.com/Varnan-Tech/opendirectory/tree/main/skills/schema-markup-generator` into [download-directory.github.io](https://download-directory.github.io/) to download the ZIP. + 2. Open **Claude Desktop** -> **Customize** -> **Skills** -> **+** -> **Upload a skill** and drop the folder containing `SKILL.md`. + + + [**Install schema-markup-generator in Manus AI**](https://manus.im/import-skills?githubUrl=https%3A%2F%2Fgithub.com%2FVarnan-Tech%2Fopendirectory%2Ftree%2Fmain%2Fskills%2Fschema-markup-generator&utm_source=opendirectory) + + + + +## Schema Types Supported + +| Type | Use When | +|------|----------| +| FAQPage | Page has 2 or more visible question/answer pairs | +| Article / BlogPosting | Page is a blog post or editorial article | +| Organization | Page represents a company or institution | +| Product | Page sells or describes a product with pricing | +| WebSite | Homepage schema with optional sitelinks search | +| HowTo | Page is a step-by-step guide with numbered steps | +| BreadcrumbList | Page has visible breadcrumb navigation | +| SoftwareApplication | Page describes a software tool or app | +| LocalBusiness | Page represents a physical business location | + +The agent detects the right type automatically. A single page often gets multiple types (a blog post gets Article and BreadcrumbList, a homepage gets WebSite and Organization). + +## Requirements + +No LLM API key needed. The agent reads the page and generates the markup. + +Chrome is needed for JavaScript-rendered pages. For static HTML pages or when you paste HTML directly, Chrome is not required. + +A GitHub token is optional. Without it, the agent outputs the markup as text for you to paste manually. + +## Setup + +### 1. Start Chrome with remote debugging (for live URLs) + +```bash +# macOS +open -a "Google Chrome" --args --remote-debugging-port=9222 + +# Linux +google-chrome --remote-debugging-port=9222 +``` + +### 2. Configure environment variables (optional) + +```bash +cp .env.example .env +# Add GITHUB_TOKEN if you want auto-PR support +``` + +## How to Use + +From a live URL: + +``` +"Generate schema markup for https://example.com/faq" +"Add structured data to https://example.com/blog/my-post" +"What schema markup does this page need? https://example.com/about" +``` + +From pasted HTML: + +``` +"Generate schema markup for this page: [paste HTML]" +"Add JSON-LD to this HTML: [paste HTML]" +``` + +Targeting a specific type: + +``` +"Generate FAQPage schema for https://example.com/support" +"Add Organization schema to our about page: https://example.com/about" +"Generate Product schema for this page: https://example.com/products/pro" +``` + +With auto-PR: + +``` +"Generate schema markup for https://example.com/blog/post and open a GitHub PR" +``` + +## Output + +| Output | Description | +|--------|-------------| +| JSON-LD script block | One `