|
| 1 | +--- |
| 2 | +name: dig |
| 3 | +description: >- |
| 4 | + Explore, analyze, plan, or spec features for the Apify MCP server. Adapts to |
| 5 | + what the user asks — from quick code exploration to full GitHub issue specs. |
| 6 | + Use when the user asks to explore code, understand behavior, plan a change, |
| 7 | + design a feature, or create an issue spec. |
| 8 | +argument-hint: "<your request> [--sdk <path>] [--ext-apps <path>] [--internal <path>]" |
| 9 | +allowed-tools: [Read, Glob, Grep, Bash, WebFetch, WebSearch, Agent] |
| 10 | +--- |
| 11 | + |
| 12 | +# Dig |
| 13 | + |
| 14 | +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. |
| 15 | + |
| 16 | +## Step 0: Parse arguments and determine intent |
| 17 | + |
| 18 | +`$ARGUMENTS` contains the user's request and optional repo path overrides. |
| 19 | + |
| 20 | +**Flags** (optional): |
| 21 | + |
| 22 | +| Flag | Default | Purpose | |
| 23 | +|----------------|----------------------------------|--------------------------------| |
| 24 | +| `--sdk` | `../typescript-sdk` | MCP SDK source repo path | |
| 25 | +| `--ext-apps` | `../ext-apps` | MCP Apps SDK source repo path | |
| 26 | +| `--internal` | `../apify-mcp-server-internal` | Internal server repo path | |
| 27 | + |
| 28 | +Everything not matching a flag is the **user's request**. |
| 29 | + |
| 30 | +**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. |
| 31 | + |
| 32 | +### Determine the intent |
| 33 | + |
| 34 | +Infer the intent from the user's natural language. There are three modes: |
| 35 | + |
| 36 | +| Intent | What you do | Examples | |
| 37 | +|--------|-------------|---------| |
| 38 | +| **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" | |
| 39 | +| **Plan** | Enter plan mode, design the approach, assess impact | "plan implementing resource links", "figure out how to refactor metadata", "design the simplification" | |
| 40 | +| **Spec** | Plan + create GitHub issues | "write an issue for X", "create a spec for Y", "spec out resource links" | |
| 41 | + |
| 42 | +**Rules:** |
| 43 | +- Default to **Explore**. When in doubt, do less — the user can always ask for more. |
| 44 | +- Only enter plan mode for **Plan** and **Spec**. |
| 45 | +- Only create GitHub issues for **Spec**. |
| 46 | + |
| 47 | +## Step 1: Explore |
| 48 | + |
| 49 | +Read the relevant source files and explain your findings. This is the baseline for all intents. |
| 50 | + |
| 51 | +**What to do:** |
| 52 | +1. Read the relevant source files in this repo |
| 53 | +2. Check similar existing features as reference |
| 54 | +3. Only check the internal repo, MCP SDK/spec, or MCP Apps SDK/spec if the user's question touches those areas |
| 55 | +4. If you spot a related open issue, mention it casually — but don't go searching for issues unless it's relevant |
| 56 | + |
| 57 | +**Stop here if the intent is Explore.** |
| 58 | + |
| 59 | +## Step 2: Plan (Plan and Spec only) |
| 60 | + |
| 61 | +Use the `EnterPlanMode` tool, then design the approach. |
| 62 | + |
| 63 | +**What to do:** |
| 64 | +1. Assess internal repo impact (check `../apify-mcp-server-internal` if available) |
| 65 | +2. Check MCP spec/SDK if the feature involves protocol behavior |
| 66 | +3. Check MCP Apps spec/SDK if the feature involves widgets or interactive UIs |
| 67 | +4. Use `mcpc @stdio tools-call` to probe current behavior if useful (requires `npm run build`) |
| 68 | +5. Follow key conventions (see below) |
| 69 | +6. Ask clarifying questions if ambiguous — prefer narrowing scope over guessing intent |
| 70 | + |
| 71 | +**Key conventions:** |
| 72 | +- **Simple > complex, ruthlessly minimal** — only what's explicitly in scope |
| 73 | +- **Reuse before creating.** Search for existing helpers and patterns. Extend what exists. |
| 74 | +- **Smallest possible change.** Ask: is there a simpler way using what's already there? |
| 75 | +- **Zod** for input validation, **HelperTools enum** for tool names |
| 76 | +- Integration tests go in `tests/integration/suite.ts` |
| 77 | +- Changes may affect `apify-mcp-server-internal` — always assess impact |
| 78 | +- **Public/internal repo separation**: See `CLAUDE.md § Public/internal repo separation` |
| 79 | +- See `CLAUDE.md`, `CONTRIBUTING.md`, and `DEVELOPMENT.md` for full conventions |
| 80 | + |
| 81 | +**Stop here if the intent is Plan.** Exit plan mode with `ExitPlanMode`. |
| 82 | + |
| 83 | +## Step 3: Spec (Spec only) |
| 84 | + |
| 85 | +Create GitHub issues. First exit plan mode with `ExitPlanMode`. |
| 86 | + |
| 87 | +### Check existing issues |
| 88 | + |
| 89 | +Search for duplicates and related issues: |
| 90 | + |
| 91 | +``` |
| 92 | +gh issue list -R apify/apify-mcp-server --search "<keywords>" --json number,title,state |
| 93 | +gh issue list -R apify/ai-team --search "<keywords>" --json number,title,state |
| 94 | +gh issue list -R apify/apify-mcp-server-internal --search "<keywords>" --json number,title,state |
| 95 | +``` |
| 96 | + |
| 97 | +If a matching issue exists, update it with `gh issue edit` instead of creating a new one. |
| 98 | + |
| 99 | +### Create issues |
| 100 | + |
| 101 | +**One issue per implementation phase.** A phase = one PR-sized unit of work (~50-200 lines changed). Each issue should be independently implementable. |
| 102 | + |
| 103 | +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. |
| 104 | + |
| 105 | +```markdown |
| 106 | +## Problem |
| 107 | +[Concrete evidence: error messages, user reports, issue links. Not "users are confused" — instead "3 users reported X in #channel".] |
| 108 | + |
| 109 | +## Proposed solution |
| 110 | +[Short. Reference existing code paths. List files inline if needed.] |
| 111 | + |
| 112 | +## Plan |
| 113 | +- [ ] Step 1 |
| 114 | +- [ ] Step 2 |
| 115 | + |
| 116 | +## Alternatives considered |
| 117 | +[Only if you actually evaluated other approaches.] |
| 118 | +``` |
| 119 | + |
| 120 | +**Style** (applies to issues AND all dig output — explanations, plans, specs): |
| 121 | +- Plain language, no fluff — see `CLAUDE.md § Communication style` |
| 122 | +- Skip any section that would be empty or generic |
| 123 | +- 10-30 lines, not 100 |
| 124 | +- Concrete steps > prose |
| 125 | + |
| 126 | +**Self-review before presenting:** |
| 127 | +- Is this the minimal design? Could scope be smaller? |
| 128 | +- Am I reusing existing patterns or reinventing? |
| 129 | +- Could this adjust existing code rather than add new code? |
| 130 | +- Does it require refactoring first? If so, that's a separate issue. |
| 131 | + |
| 132 | +Present issue content to the user for review before creating. Use `gh issue create` with `t-ai` label. |
| 133 | + |
| 134 | +## Available resources |
| 135 | + |
| 136 | +| Resource | Path / URL | Use for | |
| 137 | +|------------------------|---------------------------------------------------------------------|-------------------------------------------------------------| |
| 138 | +| **Public repo** | `.` (this repo root) | Main codebase — tools, widgets, tests | |
| 139 | +| **Internal repo** | `../apify-mcp-server-internal` (if available) | Hosted server — assess impact of changes | |
| 140 | +| **MCP SDK (types)** | `node_modules/@modelcontextprotocol/sdk` | Protocol types, server/client APIs (compiled only) | |
| 141 | +| **MCP SDK (source)** | `../typescript-sdk` (if available) | Examples, tests, full source — faster than GitHub | |
| 142 | +| **MCP spec** | `https://modelcontextprotocol.io/specification/2025-11-25` | Protocol-level features | |
| 143 | +| **MCP Apps SDK (types)** | `node_modules/@modelcontextprotocol/ext-apps` | MCP Apps types, React hooks, server helpers (compiled only) | |
| 144 | +| **MCP Apps SDK (source)** | `../ext-apps` (if available) | Examples, tests, spec, full source — faster than GitHub | |
| 145 | +| **MCP Apps spec** | `https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx` | MCP Apps extension specification | |
| 146 | +| **Dev server (no UI)** | `http://localhost:3001/` / tools: `mcp__apify-dev__*` | Test tools without widgets | |
| 147 | +| **Dev server (UI)** | `http://localhost:3001/?ui=true` / tools: `mcp__apify-dev-ui__*` | Test tools with widget rendering | |
| 148 | +| **mcpc stdio** | `mcpc @stdio tools-call ...` (requires `npm run build`) | Test tools — no running server needed | |
0 commit comments