feat: improve dumplingai skill discovery

Author: yangpten

AGENTS.md

@@ -0,0 +1,45 @@
+# AGENTS.md
+
+Guidelines for contributors working on the DumplingAI CLI skills in this repository.
+
+## Repository Focus
+
+This repo ships:
+
+- the `dumplingai-cli` npm package under `packages/cli/`
+- bundled agent skills under `skills/`
+- install-time copies of those skills embedded in `packages/cli/src/commands/setup-skill.ts`
+
+## Skill Discovery Rule
+
+For skill triggerability, the frontmatter `description` is retrieval copy, not just documentation.
+
+Every skill description should cover:
+
+1. What the skill helps the user accomplish
+2. The phrases a user is likely to say
+3. When to use this skill instead of a nearby one
+
+Prefer multiple narrow, job-shaped skills over one generic integration skill when users commonly ask for the workflows in different language. Broad umbrella skills are still useful, but they should be backed by more specific entry points like search, scraping, transcripts, and SEO data.
+
+Prefer:
+
+```yaml
+description: When the user wants to find the right API for scraping or search. Also use when the user mentions Firecrawl, Serper, transcripts, or SEO APIs. For executing the chosen endpoint, see dumplingai-cli.
+```
+
+Avoid descriptions that only describe the underlying tool, such as "CLI for DumplingAI" with no user-intent language.
+
+## Keep Sources in Sync
+
+When editing a bundled skill:
+
+1. Update `skills/<name>/SKILL.md`
+2. Update the matching embedded string in `packages/cli/src/commands/setup-skill.ts`
+3. If trigger guidance changes, update `README.md`
+
+## Validation
+
+- Keep skill names aligned with directory names
+- Keep descriptions concise but rich in trigger phrases
+- Prefer concrete user intents and vendor/task synonyms over internal product terminology

README.md

@@ -24,7 +24,7 @@ Get your API key at https://app.dumplingai.com/settings/api-keys
 | `dumplingai logout` | Remove stored credentials |
 | `dumplingai status` | Show CLI version, auth status, and v2 balance context |
 | `dumplingai view-config` | Display current configuration |
-| `dumplingai catalog search <prompt>` | Search v2 capabilities, providers, and endpoints |
+| `dumplingai catalog search <prompt>` | Search v2 capabilities, providers, and endpoints with short keyword queries |
 | `dumplingai catalog details <type> <id>` | Inspect a specific catalog object |
 | `dumplingai run <type> <id> --input '<json>'` | Execute a capability or endpoint |
 | `dumplingai balance` | Show balance and budget information |
@@ -37,7 +37,7 @@ Get your API key at https://app.dumplingai.com/settings/api-keys
 
 ```bash
 # Discover available capabilities
-dumplingai catalog search "google search capability"
+dumplingai catalog search "google search"
 
 # Inspect a capability before running it
 dumplingai catalog details capability google_search
@@ -60,16 +60,39 @@ dumplingai run capability scrape_page --input '{"url":"https://example.com"}' >
 head -40 .dumplingai/page.json
 ```
 
+## Catalog Search Tips
+
+`dumplingai catalog search` behaves more like keyword search than semantic search. Use short phrases such as `google search`, `scrape page`, `youtube transcript`, `keyword ideas`, or `firecrawl scrape`.
+
+Avoid long natural-language prompts and avoid appending generic words like `capability` or `endpoint` unless they are actually part of the object name. If results are empty or weak, shorten the query first.
+
 ## Skill Installation
 
 Packaged skills from this repo can be installed with the `skills` CLI:
 
 ```bash
 npx skills add dumplingai/cli
 npx skills add dumplingai/cli --list
-npx skills add dumplingai/cli --skill discovering-dumplingai-apis --skill dumplingai-cli --skill youtube-to-blog-post --skill social-media-post
+npx skills add dumplingai/cli --skill discovering-dumplingai-apis --skill dumplingai-cli --skill dumplingai-web-research --skill dumplingai-scraping-extraction --skill dumplingai-transcripts-media --skill dumplingai-seo-data --skill youtube-to-blog-post --skill social-media-post
 ```
 
+## When Skills Should Trigger
+
+The main lesson from high-performing skill repos is that discovery copy should describe user intent, not just implementation details. These are the bundled skills and the kinds of requests they should catch:
+
+| Skill | Trigger this when the user says things like |
+|-------|---------------------------------------------|
+| `discovering-dumplingai-apis` | "Find the best API for scraping/search/transcripts", "Can DumplingAI do this instead of Firecrawl/Serper/DataForSEO?", "I want one API key across providers" |
+| `dumplingai-cli` | "Run this through DumplingAI", "search the DumplingAI catalog", "inspect this capability", "check DumplingAI balance/usage", "test this endpoint from the terminal" |
+| `dumplingai-web-research` | "Search the web for this", "find sources on this topic", "run Google/Serper/Perplexity-style search through DumplingAI", "do competitor/topic research first" |
+| `dumplingai-scraping-extraction` | "Scrape this page", "crawl this site", "extract content from this URL", "pull structured content with Firecrawl-style tooling" |
+| `dumplingai-transcripts-media` | "Get the YouTube transcript", "transcribe this video", "extract captions from this media URL", "turn video/audio into text" |
+| `dumplingai-seo-data` | "Get keyword ideas", "pull SEO data", "use DataForSEO through DumplingAI", "find ranking/search-volume endpoints" |
+| `youtube-to-blog-post` | "Turn this YouTube video into a post", "extract the transcript and draft an article", "repurpose this creator video into a newsletter/blog" |
+| `social-media-post` | "Turn this topic/page/transcript into LinkedIn or X posts", "write thread variants", "give me channel-specific social copy" |
+
+If a skill description only says what the tool is, it tends to under-trigger. If it says what the user is trying to accomplish and includes the phrases they are likely to use, it triggers more reliably.
+
 ## Development
 
 ```bash
@@ -80,3 +103,5 @@ pnpm --filter dumplingai-cli typecheck
 ```
 
 Local agent/runtime folders such as `.claude/`, `.agents/`, `.cursor/`, `.codex/`, and `.dumplingai/` are intentionally ignored. Keep checked-in skill sources under `skills/`.
+
+Stored credentials are written to a local config file. Prefer `DUMPLINGAI_API_KEY` in CI or shared environments.

packages/cli/README.md

@@ -16,7 +16,7 @@ npm install -g dumplingai-cli
 
 ```bash
 dumplingai login --api-key sk_yourkey
-dumplingai catalog search "google search capability"
+dumplingai catalog search "google search"
 dumplingai run capability google_search --input '{"query":"latest TypeScript release"}'
 ```
 
@@ -27,7 +27,7 @@ dumplingai run capability google_search --input '{"query":"latest TypeScript rel
 - `dumplingai logout`
 - `dumplingai status`
 - `dumplingai view-config`
-- `dumplingai catalog search <prompt>`
+- `dumplingai catalog search <prompt>`  # use short keyword queries like "google search"
 - `dumplingai catalog details <type> <id>`
 - `dumplingai run <type> <id> --input '<json>'`
 - `dumplingai balance`

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dumplingai-cli",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "DumplingAI CLI — discover and execute Unified API Platform capabilities from the terminal",
   "license": "MIT",
   "type": "module",

packages/cli/src/commands/catalog.ts

@@ -31,23 +31,51 @@ function parseOptionalInt(value?: string, flagName?: string): number | undefined
   return parsed;
 }
 
+function getCatalogResultCount(result: Record<string, unknown>): number | undefined {
+  const candidates = ['items', 'results', 'data', 'matches'];
+
+  for (const key of candidates) {
+    const value = result[key];
+    if (Array.isArray(value)) {
+      return value.length;
+    }
+  }
+
+  return undefined;
+}
+
 export function makeCatalogCommand(): Command {
   const command = new Command('catalog')
     .description('Search and inspect the DumplingAI v2 catalog');
 
   command.addCommand(
     new Command('search')
-      .description('Search capabilities, providers, and endpoints')
-      .argument('<prompt>', 'Prompt describing the API need')
+      .description('Search capabilities, providers, and endpoints with short keyword queries')
+      .argument(
+        '<prompt>',
+        'Short keyword query, e.g. "google search" or "scrape page" rather than a long sentence',
+      )
       .option('--type <type>', 'Filter to capability, provider, or endpoint')
       .option('--limit <n>', 'Maximum number of results to return')
       .option('--api-key <key>', 'Override API key for this request')
       .action(async (prompt: string, opts: { type?: string; limit?: string; apiKey?: string }) => {
+        if (prompt.trim().split(/\s+/).length > 5) {
+          process.stderr.write(
+            'Tip: `catalog search` works best with short keyword queries. If results are weak, shorten the query and remove extra words like "capability" or "endpoint".\n',
+          );
+        }
         const client = await getClient(opts.apiKey);
         const result = await client.searchCatalog(prompt, {
           type: parseCatalogType(opts.type),
           limit: parseOptionalInt(opts.limit, '--limit'),
         });
+
+        if (getCatalogResultCount(result) === 0) {
+          process.stderr.write(
+            'No catalog results found. Retry with a shorter keyword query like "google search", "scrape page", or "keyword ideas", and remove extra words like "capability" or "endpoint".\n',
+          );
+        }
+
         printResult(result);
       }),
   );