From 131b49bec29f705ddd6a6426746b7f33d4fbaa51 Mon Sep 17 00:00:00 2001
From: Karan Lokchandani <karanlokchandani@protonmail.com>
Date: Mon, 3 Aug 2026 00:25:29 +0530
Subject: [PATCH] feat(cli): add --skills-only to the developer command

The gateway accepts a `skills` query param on GET /v2/developer/search
(firecrawl/firecrawl#4194): `skills=only` limits the search to
agent-skill files. `--skills-only` maps to that value. The param is
absent from the request when the flag is omitted.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01C4vZ6XH65bUJDkLthyfmvC
---
 README.md                                |  1 +
 src/__tests__/cli-argv.test.ts           |  1 +
 src/__tests__/commands/developer.test.ts | 13 +++++++++++++
 src/commands/developer.ts                |  1 +
 src/index.ts                             |  2 ++
 src/types/developer.ts                   |  1 +
 6 files changed, 19 insertions(+)

diff --git a/README.md b/README.md
index 100ba8ef8d..45370e6fdc 100644
--- a/README.md
+++ b/README.md
@@ -365,6 +365,7 @@ firecrawl developer "axum middleware ordering"
 | Option                | Description                               |
 | --------------------- | ----------------------------------------- |
 | `--limit <n>`         | Number of results (default: 20, max: 100) |
+| `--skills-only`       | Search only agent-skill files             |
 | `-o, --output <path>` | Save to file                              |
 | `--json`              | Output as compact JSON                    |
 | `--pretty`            | Pretty print JSON output                  |
diff --git a/src/__tests__/cli-argv.test.ts b/src/__tests__/cli-argv.test.ts
index 511f7fe795..24f168d066 100644
--- a/src/__tests__/cli-argv.test.ts
+++ b/src/__tests__/cli-argv.test.ts
@@ -30,6 +30,7 @@ describe('CLI argv parsing', () => {
     expect(result.status).toBe(0);
     expect(result.stdout).toContain('Usage: firecrawl developer');
     expect(result.stdout).toContain('--limit');
+    expect(result.stdout).toContain('--skills-only');
     expect(result.stderr).not.toContain('unknown command');
   });
 
diff --git a/src/__tests__/commands/developer.test.ts b/src/__tests__/commands/developer.test.ts
index 8612a01635..c36d2d8fb6 100644
--- a/src/__tests__/commands/developer.test.ts
+++ b/src/__tests__/commands/developer.test.ts
@@ -67,6 +67,19 @@ describe('handleDeveloperSearchCommand', () => {
       );
     });
 
+    it('passes skills=only when skillsOnly is set', async () => {
+      mockHttpGet.mockResolvedValue(mockDeveloperResponse([sampleResult]));
+
+      await handleDeveloperSearchCommand({
+        query: 'tokio spawn_blocking',
+        skillsOnly: true,
+      });
+
+      expect(mockHttpGet).toHaveBeenCalledWith(
+        '/v2/developer/search?query=tokio+spawn_blocking&skills=only&integration=cli'
+      );
+    });
+
     it('passes k when a limit is provided', async () => {
       mockHttpGet.mockResolvedValue(mockDeveloperResponse([sampleResult]));
 
diff --git a/src/commands/developer.ts b/src/commands/developer.ts
index abfa80a2f6..ccdc2cffff 100644
--- a/src/commands/developer.ts
+++ b/src/commands/developer.ts
@@ -69,6 +69,7 @@ export async function handleDeveloperSearchCommand(
     const params = new URLSearchParams();
     params.append('query', options.query);
     if (options.k != null) params.append('k', String(options.k));
+    if (options.skillsOnly) params.append('skills', 'only');
     const data = await getDeveloper<{ results?: DeveloperItem[] }>(
       `${BASE}?${params.toString()}`,
       options
diff --git a/src/index.ts b/src/index.ts
index a7d12586bd..1f06323352 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1063,6 +1063,7 @@ function createDeveloperCommand(): Command {
       parseInt
     )
     .addOption(new Option('--k <number>').argParser(parseInt).hideHelp())
+    .option('--skills-only', 'Search only agent-skill files', false)
     .option(
       '-k, --api-key <key>',
       'Firecrawl API key (overrides global --api-key)'
@@ -1083,6 +1084,7 @@ Examples:
       await handleDeveloperSearchCommand({
         query,
         k: researchLimit(options),
+        skillsOnly: options.skillsOnly,
         apiKey: options.apiKey,
         apiUrl: options.apiUrl,
         output: options.output,
diff --git a/src/types/developer.ts b/src/types/developer.ts
index 0a3d8e8620..b1fd5b39b1 100644
--- a/src/types/developer.ts
+++ b/src/types/developer.ts
@@ -1,6 +1,7 @@
 export interface DeveloperSearchOptions {
   query: string;
   k?: number;
+  skillsOnly?: boolean;
   apiKey?: string;
   apiUrl?: string;
   output?: string;