Dig

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):

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:

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.

What to do: 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 the feature involves widgets or interactive UIs 4. Use mcpc @stdio tools-call to probe current behavior if useful (requires pnpm run build) 5. Follow key conventions (see below) 6. Ask clarifying questions if ambiguous — prefer narrowing scope over guessing intent

Key conventions:

• Simple > complex, ruthlessly minimal — only what's explicitly in scope
• Reuse before creating. Search for existing helpers and patterns. Extend what exists.
• Smallest possible change. Ask: is there a simpler way using what's already there?
• Zod for input validation, HelperTools enum for tool names
• Integration tests go in tests/integration/suite.ts
• Changes may affect apify-mcp-server-internal — always assess impact
• Public/internal repo separation: See CLAUDE.md § Public/internal repo separation
• See CLAUDE.md, CONTRIBUTING.md, and DEVELOPMENT.md for full conventions

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 (applies to issues AND all dig output — explanations, plans, specs):

• 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

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