| name | dig |
| description | Explore, analyze, plan, or spec features for the Apify MCP server. Adapts to what the user asks — from quick code exploration to full GitHub issue specs. Use when the user asks to explore code, understand behavior, plan a change, design a feature, or create an issue spec. |
| argument-hint | <your request> [--sdk <path>] [--ext-apps <path>] [--internal <path>] |
| allowed-tools | ["Read","Glob","Grep","Bash","WebFetch","WebSearch","Agent"] |
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:
- Read the relevant source files in this repo
- Check similar existing features as reference
- Only check the internal repo, MCP SDK/spec, or MCP Apps SDK/spec if the user's question touches those areas
- 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:
- Assess internal repo impact (check
../apify-mcp-server-internal if available)
- Check MCP spec/SDK if the feature involves protocol behavior
- Check MCP Apps spec/SDK if it involves widgets or interactive UIs
- Use
mcpc @stdio tools-call to probe current behavior if useful (requires pnpm run build)
- 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:
- Approach — the chosen design in a few sentences and the main trade-off you accepted.
- Files to change — each file to create or modify with a one-line note on what changes (path + change; no line numbers needed).
- Interfaces — the key function/type signatures you add or change (names, params, returns), so the implementer and reviewers know the contract.
- 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.
- Risks & impact — edge cases, and
apify-mcp-server-internal impact.
- 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 |
