skills-lint: check skill tool names against PipefyClient, and fix wrong examples

[mocha06]

Problem

skills-lint.yml runs lint_skill_refs.py, which checks tool names in skills against the MCP registry only. A skill can therefore name an operation that the SDK does not have. See the name-parity issue in this milestone.

A review of the skills against the SDK also found content errors. Some of them are wrong on MCP too (all lines refer to origin/dev adf67c3a):

• skills/observability/pipefy-observability/SKILL.md:56 uses page=1. The real parameters are first and after.
• skills/observability/pipefy-observability/SKILL.md:66 uses agent_id=. The real parameters are uuid / agent_uuid and active.
• skills/process-intelligence/pipefy-process-intelligence/SKILL.md:89 shows create_automation ... trigger_event=... actions=[...]. The real signature takes trigger_id and action_id.
• skills/process-intelligence/pipefy-process-intelligence/SKILL.md:98 shows create_field_condition ... when/fields. The real signature takes phase_id, condition and actions.
• skills/process-design/pipefy-process-design/SKILL.md:41 uses name="". The parameter is pipe_name.
• skills/automations/pipefy-automations/SKILL.md:69,77: the example uses the same field id as prompt input and output. The validator rejects this (pipefy_sdk/ai_preflight.py:89-94). Line 77 also uses trigger_event= where the parameter is event_id.

Proposal

• Extend lint_skill_refs.py so that a tool name in a skill body must resolve to a PipefyClient method, an MCP tool, or both. Once the surface-neutral issue lands, names in references/mcp.md must resolve to MCP tools only.
• Fix the lines above.

[mocha06]

One more example that is wrong on every surface (origin/dev 7aa32b6d):

• skills/ai-agents/pipefy-ai-agents/SKILL.md:140: the move_card metadata example sends "pipeId": "". The API rejects an AI agent update with that metadata: The agent references a pipe or table you do not have access to. The message is about access, not about the field, so the cause is hard to find.

I checked it with update_ai_agent (SDK 0.5.0b1) on one agent, with one card_moved behavior and one move_card action. Only pipeId changed between the calls:

move_card metadata	Result
{"destinationPhaseId": "<phase_id>", "fieldsAttributes": []}	Updated
{"destinationPhaseId": "<phase_id>", "pipeId": "", "fieldsAttributes": []}	Rejected
{"destinationPhaseId": "<phase_id>", "pipeId": "<the agent's pipe id>", "fieldsAttributes": []}	Updated

The MCP update_ai_agent docstring already documents move_card as {"destinationPhaseId": "<phase_id>"}, and _validate_move_card_metadata requires only destinationPhaseId. So the fix is in the skill: remove "pipeId": "" from line 140.

Optional: AiBehaviorMetadataInput could reject an empty pipeId with a message that names the field.

A verified version of this fix already exists internally. Ask the maintainers' squad for the reference before you write your own.

[mocha06]

More skill text that is wrong on every surface (origin/dev 7aa32b6d, checked against pipefy 0.5.0b1 and the API):

Skill line	What it says	What is true
skills/reports/pipefy-reports/SKILL.md:70-76, :99	Poll the export until finished, then read fileUrl	Report exports use processing, done and failed, and the key is fileURL (queries/report_queries.py:129, :147). The toolkit's own MCP docstring (report_tools.py:333) says done and fileURL. The automation-jobs export is different: it does use finished and fileUrl.
skills/automations/pipefy-automations/SKILL.md:169, :278	Re-invoke simulate_automation to see the result	Each call runs createAutomationSimulation again and reads the new simulation once (services/automation_service.py:587-608). No client method reads a simulation by id, although AUTOMATION_SIMULATION_QUERY exists. get_automation_logs needs an automation_id, which a dry run does not have.
skills/database-tables/pipefy-database-tables/SKILL.md:102	Show the record count before delete_table	No table query selects a count (queries/table_queries.py). The API has table_records_count (camelize: false) on Table, so only raw GraphQL reads it today.
skills/api-troubleshoot/pipefy-api-fallback/SKILL.md:162-163	Use createCard with throughConnectors instead of a create_card automation	That call creates one card now. It is not a rule, so it does not replace the automation.
skills/api-troubleshoot/pipefy-api-fallback/SKILL.md:19-27 vs :143-152	The tiers run in order, and the re-read rule comes later	The re-read rule sits in this skill, which loads only after tier 2 (:15). A write that failed but happened is re-run through execute_graphql before the rule applies, and the data is duplicated. The rule must come before tier 2 for writes.
skills/introspection/pipefy-introspection/SKILL.md:84, :152	CreatePhaseFieldInput.type is an enum; introspect it	The argument is an ID scalar, with the valid values listed in its description. Introspection returns no enum values.
skills/observability/pipefy-observability/SKILL.md:74	Shows period="current_month"	That value is for the exports. get_automation_execution_metrics takes only FIFTEEN_MINUTES, SIXTY_MINUTES, TWELVE_HOURS or TWENTY_FOUR_HOURS (queries/observability_queries.py:242-247), and neither the skill nor the SDK docstring lists them.

Optional SDK change for the simulation line: a get_automation_simulation(simulation_id) method over AUTOMATION_SIMULATION_QUERY, or a poll inside simulate_automation until the status leaves processing.

A verified version of these fixes already exists internally. Ask the maintainers' squad for the reference before you write your own.

[adriannoes]

Fixed on dev by #719. Closing by hand, since Closes only fires on merge into main.