Dig

Flexible skill for exploring, planning, and speccing work on the Apify MCP server. Do NOT edit source files — this skill is for understanding and planning only.

Step 0: Parse arguments and determine intent

$ARGUMENTS contains the user's request and optional repo path overrides.

Flags (optional):

Flag	Default	Purpose
--sdk	../typescript-sdk	MCP SDK source repo path
--ext-apps	../ext-apps	MCP Apps SDK source repo path
--internal	../apify-mcp-server-internal	Internal server repo path

Everything not matching a flag is the user's request.

Resolution order for source repos: flag path → default sibling path → node_modules/ (compiled types only) → GitHub URL (last resort). Always verify the path exists before using it.

Determine the intent

Infer the intent from the user's natural language. There are three modes:

Intent	What you do	Examples
Explore	Read code, explain findings, answer questions	"how does tool naming work", "look at the widget code", "why is this broken", "what would break if we change X"
Plan	Enter plan mode, design the approach, assess impact	"plan implementing resource links", "figure out how to refactor metadata", "design the simplification"
Spec	Plan + create GitHub issues	"write an issue for X", "create a spec for Y", "spec out resource links"

Rules:

• Default to Explore. When in doubt, do less — the user can always ask for more.
• Only enter plan mode for Plan and Spec.
• Only create GitHub issues for Spec.

Step 1: Explore

Read the relevant source files and explain your findings. This is the baseline for all intents.

What to do:

1. Read the relevant source files in this repo
2. Check similar existing features as reference
3. Only check the internal repo, MCP SDK/spec, or MCP Apps SDK/spec if the user's question touches those areas
4. If you spot a related open issue, mention it casually — but don't go searching for issues unless it's relevant

Stop here if the intent is Explore.

Step 2: Plan (Plan and Spec only)

Use the EnterPlanMode tool, then design the approach — and commit to one. If the request is genuinely ambiguous (e.g. it maps to two different existing knobs), surface the fork up front and ask; otherwise pick the most defensible design and commit rather than listing options.

Investigate first:

1. Assess internal repo impact (check ../apify-mcp-server-internal if available)
2. Check MCP spec/SDK if the feature involves protocol behavior
3. Check MCP Apps spec/SDK if it involves widgets or interactive UIs
4. Use mcpc @stdio tools-call to probe current behavior if useful (requires pnpm run build)
5. Read the repo's convention docs — follow them, don't reinvent

Conventions live in the repo, not here. AGENTS.md, CONTRIBUTING.md, and DEVELOPMENT.md hold the naming, validation, test-layout, and public/internal-separation rules — read them. Design minimally: reuse and adjust before adding.

Design output — required sections. A plan has to be implementable by someone else, so produce:

1. Approach — the chosen design in a few sentences and the main trade-off you accepted.
2. Files to change — each file to create or modify with a one-line note on what changes (path + change; no line numbers needed).
3. Interfaces — the key function/type signatures you add or change (names, params, returns), so the implementer and reviewers know the contract.
4. Test strategy (the oracle) — which unit/integration tests prove it, where they live, and what each asserts. This is how "done" is judged — never leave it implicit.
5. Risks & impact — edge cases, and apify-mcp-server-internal impact.
6. Data flow — only when non-trivial: entry → transforms → output.

Sections 2–4 must be concrete (real files, signatures, and tests — no "TBD", no "add error handling"). Sections 1, 5, 6 stay brief. This structure is for Plan; Explore and Spec stay lean.

Stop here if the intent is Plan. Exit plan mode with ExitPlanMode.

Step 3: Spec (Spec only)

Create GitHub issues. First exit plan mode with ExitPlanMode.

Check existing issues

Search for duplicates and related issues:

gh issue list -R apify/apify-mcp-server --search "<keywords>" --json number,title,state
gh issue list -R apify/ai-team --search "<keywords>" --json number,title,state
gh issue list -R apify/apify-mcp-server-internal --search "<keywords>" --json number,title,state

If a matching issue exists, update it with gh issue edit instead of creating a new one.

Create issues

One issue per implementation phase. A phase = one PR-sized unit of work (~50-200 lines changed). Each issue should be independently implementable.

Use the repo's feature_spec.yml template. Only the Problem and Proposed solution fields are required. Include Plan and Alternatives considered only when they add real value. No fluff, no filler — straight to the point.

## Problem
[Concrete evidence: error messages, user reports, issue links. Not "users are confused" — instead "3 users reported X in #channel".]

## Proposed solution
[Short. Reference existing code paths. List files inline if needed.]

## Plan
- [ ] Step 1
- [ ] Step 2

## Alternatives considered
[Only if you actually evaluated other approaches.]

Style (Explore explanations and Spec issues):

• Plain language, no fluff — see CLAUDE.md § Communication style
• Skip any section that would be empty or generic
• 10-30 lines, not 100
• Concrete steps > prose

(A Plan's design follows its required-sections structure above — keep each section tight, but don't truncate files / interfaces / test strategy to hit a line count.)

Self-review before presenting:

• Is this the minimal design? Could scope be smaller?
• Am I reusing existing patterns or reinventing?
• Could this adjust existing code rather than add new code?
• Does it require refactoring first? If so, that's a separate issue.

Present issue content to the user for review before creating. Use gh issue create with t-ai label.

Available resources

Resource	Path / URL	Use for
Public repo	. (this repo root)	Main codebase — tools, widgets, tests
Internal repo	../apify-mcp-server-internal (if available)	Hosted server — assess impact of changes
MCP SDK (types)	node_modules/@modelcontextprotocol/sdk	Protocol types, server/client APIs (compiled only)
MCP SDK (source)	../typescript-sdk (if available)	Examples, tests, full source — faster than GitHub
MCP spec	https://modelcontextprotocol.io/specification/2025-11-25	Protocol-level features
MCP Apps SDK (types)	node_modules/@modelcontextprotocol/ext-apps	MCP Apps types, React hooks, server helpers (compiled only)
MCP Apps SDK (source)	../ext-apps (if available)	Examples, tests, spec, full source — faster than GitHub
MCP Apps spec	https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx	MCP Apps extension specification
Dev server (no UI)	http://localhost:3001/ / tools: mcp__apify-dev__*	Test tools without widgets
Dev server (UI)	http://localhost:3001/?ui=true / tools: mcp__apify-dev-ui__*	Test tools with widget rendering
mcpc stdio	mcpc @stdio tools-call ... (requires pnpm run build)	Test tools — no running server needed