feat(skills): improve skill descriptions and add per-profile agent guidance

[joeVenner]

Summary

• _build_description() now generates an action-oriented frontmatter description from actual properties — agents see concrete things like set temperature (16–30 C) and set mode (COOL/HEAT/DRY/FAN/…) instead of the generic "query status, turn on/off, set properties"
• Added _PROFILE_DESCRIPTION_NOTES — short per-profile clarifications appended to the description (e.g. petfeeder: "Use set portions=N to feed — on only triggers one quick portion")
• Added _PROFILE_PITFALLS — per-profile lists of common agent mistakes, surfaced in a new ## Agent Guidance section in SKILL.md
• Template updated: ## What This Skill Does is now a capability bullet list; ## Agent Guidance block appears when pitfalls exist

Key example — pet feeder

Before:

"Control the rojeco-pet-feeder (petfeeder) — a Tuya device at 192.168.1.4. Use this skill to query status, turn on/off, and set device-specific properties via the iotcli CLI."

After:

"Tuya 'rojeco-pet-feeder' at 192.168.1.4 — set portions (1–60); trigger quick_feed. Use set portions=N to feed — on only triggers one quick portion."

Plus an explicit Agent Guidance section explaining the on vs portions pitfall.

[greptile-apps]

Greptile Summary

This PR improves the AI agent skill system by replacing the generic "query status, turn on/off, set properties" description with a concrete, action-oriented one derived from real property metadata, and adds per-profile ## Agent Guidance sections listing common agent mistakes. The template is updated to render a capability bullet list and conditionally emit the new guidance block.

Key changes:

• _build_description() now inspects actual Property objects (enums, min/max ranges, units) to generate compact, machine-readable frontmatter descriptions
• _PROFILE_DESCRIPTION_NOTES adds one-line profile-specific clarifications appended to the description (petfeeder, light, bulb)
• _PROFILE_PITFALLS provides per-profile pitfall bullets rendered in a new ## Agent Guidance section (petfeeder, airfryer, light, bulb)
• Two concrete wrong property names remain in the pitfall data: food_level (should be food_empty, the actual boolean status field) in the petfeeder pitfall, and temperature/timer (should be target_temp/target_time) in the airfryer pitfall — both will silently mislead agents reading the generated skill files

Confidence Score: 3/5

• Two concrete wrong property names in the pitfall data will produce incorrect agent guidance; fix both before merging.
• The description-generation logic and template changes are solid. However, two property name mismatches in _PROFILE_PITFALLS will actively mislead agents: food_level (petfeeder, line 163) and temperature/timer (airfryer, line 166) don't match the actual property names exposed by the profiles. These are small targeted fixes, but since the primary purpose of this PR is accurate agent guidance, shipping with wrong property names in the guidance section undercuts the whole goal.
• src/iotcli/skills/generator.py — specifically the _PROFILE_PITFALLS dict entries for petfeeder (line 163) and airfryer (line 166)

Important Files Changed

Filename	Overview
src/iotcli/skills/generator.py	Adds _build_description (action-oriented frontmatter), _PROFILE_DESCRIPTION_NOTES, and _PROFILE_PITFALLS. Two concrete property-name bugs remain: food_level (should be food_empty) in the petfeeder pitfall, and temperature/timer (should be target_temp/target_time) in the airfryer pitfall — both will mislead agents.
src/iotcli/skills/templates/device_skill.md.j2	Template updated to render ## What This Skill Does as a capability bullet list and add a new ## Agent Guidance block when pitfalls are present. Conditional logic and Jinja2 syntax look correct.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Device + Profile] --> B[build_device_context]
    B --> C[properties / trigger_names / actions]
    C --> D[_build_description]
    C --> E[_build_pitfalls]
    D --> F[frontmatter description string]
    E --> G[pitfalls list]
    F & G --> H[Jinja2: device_skill.md.j2]
    H --> I[SKILL.md frontmatter\nname / description / metadata]
    H --> J[## What This Skill Does\nbullet list]
    H --> K{pitfalls?}
    K -- yes --> L[## Agent Guidance\nwarning bullets]
    K -- no --> M[skip section]
    L & J & I --> N[Written to skills/device-slug/SKILL.md]

Loading

_{Reviews (2): Last reviewed commit: "Update src/iotcli/skills/generator.py" | Re-trigger Greptile}

[joeVenner]

@greptile review