Skip to content

Latest commit

 

History

History
75 lines (58 loc) · 9.76 KB

CLAUDE.md

File metadata and controls

75 lines (58 loc) · 9.76 KB

UiPath Agent Skills — Project Rules

This repository contains self-contained AI agent skills for UiPath automation development. Skills are installed as a Claude Code plugin and teach AI agents how to build, run, test, and deploy UiPath automations.

Architecture

  • Skills are self-contained. Each skill under skills/ must function on its own: it MUST NOT import, inline, or read another skill's files, and MUST still deliver its core value if sibling skills are absent. A skill MAY delegate a task to a sibling skill in this same plugin at runtime (e.g., spawn a subagent that hands an artifact edit to the artifact's owning domain skill) when that work is the sibling's domain — provided the delegation degrades gracefully (the skill still presents an actionable result when the sibling is unavailable).
  • SKILL.md is the canonical default contract. Every skill folder must have a complete SKILL.md with valid YAML frontmatter. Local/default consumers can understand it without a flavor manifest or runtime resolver. Shared guidance stays there; only genuinely different passages may be enclosed by named flavor-block comments.
  • Custom flavors inherit the complete catalog and contain only sparse exceptions. Every flavor ships every canonical skill. Files under skill-flavors/<flavor>/<skill>/ mirror canonical skill paths and contain only complete replacement blocks. If no override exists, the canonical file is intentionally reused unchanged. Do not duplicate a whole skill merely to change a few paragraphs.
  • Build files before packages. Build complete default and custom-flavor skill trees, validate those final files, and only then stage packages. Consumers must copy a finished tree; they must not interpret flavor markers or compose Markdown at runtime.
  • Session hooks are Node scripts or direct uip ingestion — never shell scripts. Telemetry ships NO script: hooks/hooks.json pipes the raw hook payload to uip track --hook, and the field derivation lives in the CLI (UiPath/cli track-hook.ts, guarded by its vitest suite). The remaining session hooks are each one hooks/<name>.mjs run by node. Both node and uip are native-executable entry points, so no shell dialect and no PowerShell execution policy applies, and both are present wherever the skills were installed through the Node-based uip CLI. Each hooks.json entry is a bash/PowerShell polyglot command whose both branches guard for the missing binary (silent exit 0) — telemetry's PowerShell branch resolves uip.cmd explicitly, never the bare uip (PowerShell would prefer npm's uip.ps1 shim, which execution policy can block). Do not add a shell field to these entries; the polyglot depends on Claude Code's default shell selection. Do NOT reintroduce .sh/.ps1 hook implementations: the retired PowerShell twins required an Authenticode signing gate at publish and still failed under Group-Policy execution policy.

Contribution Rules

See CONTRIBUTING.md for the full guide. Key rules:

  1. Skill folder naming: uipath-<kebab-case> under skills/

  2. SKILL.md frontmatter is required: must include name (matching folder name) and description (with TRIGGER/DO NOT TRIGGER conditions)

  3. References use kebab-case filenames with -guide.md and -template.md suffixes

  4. Update CODEOWNERS when adding or modifying skill ownership

  5. Update the two skill registries in the SAME PR that adds, renames, or removes a skill folder. Adding or renaming skills/<name>/ requires the matching edit to assets/skill-status.json (lifecycle status) AND to skills.sh.json (display grouping); removing a skill requires deleting its entry from both. Neither file is discovered from disk, so nothing else in the build notices when they drift. Verify both before opening the PR:

    python3 scripts/check-skill-status.py --write-readme   # regenerates the README table
    python3 scripts/check-skills-sh.py                     # add/rename/remove: must print OK

    Full change→edit table, the --fix limits, and how pre-existing drift is reported: .claude/rules/skill-structure.md § skills.sh Grouping.

  6. No structural cross-skill dependencies — a skill must work in isolation (never import or read another skill's files); runtime delegation to a same-plugin sibling skill is allowed when it degrades gracefully

  7. No secrets or personal paths in committed files

  8. CLI commands must use --output json when output is parsed programmatically

  9. Review new skills for every custom flavor. They are included automatically; add the smallest sparse override wherever canonical guidance is not safe for a target environment

  10. Never rename a job that produces a required status check, and never narrow its trigger. A required context is a literal string GitHub waits for. Rename the job and the context stops reporting; add paths:, paths-ignore:, branches:, branches-ignore: or a types: list without synchronize and the workflow won't run on excluded PRs. Either way the check never arrives and every open PR blocks, not just yours. Short-circuit inside the job instead — a skipped job counts as a pass. The set lives in docs/REQUIRED-CHECKS.md § Current target set and is not discovered from disk; edit it in the same PR as the workflow:

    python3 -m pytest tests/scripts/test_required_checks_contract.py -q   # must pass
    ./scripts/apply-required-checks.sh --dry-run                          # preview the ruleset
    ./scripts/apply-required-checks.sh --check                            # doc vs live ruleset (needs repo admin)

File Conventions

File Convention
SKILL.md Required. Uppercase. YAML frontmatter + markdown body.
references/*.md Kebab-case. Guides end with -guide.md.
skill-flavors/<flavor>/<skill>/**/*.md Optional sparse overrides at paths relative to skills/; contain only named replacement blocks.
<!--skill-flavor:<name>:start|end--> Compact, whitespace-free column-one boundary around the smallest canonical passage that differs by flavor. Names are lowercase kebab-case and unique within a file; indent the enclosed Markdown, never the boundary.
assets/templates/* Templates end with -template.md or -template.<ext>.
skills.sh.json Display grouping for the repo's skills.sh page. Every skills/<name>/ appears in exactly one grouping. Edit it in the same PR that adds, renames, or removes a skill folder — validate with python3 scripts/check-skills-sh.py.
assets/skill-status.json Lifecycle status (stable / preview / in-development) for every skill — the single source of truth. Edit in the same PR as the skill folder; regenerate the README table with python3 scripts/check-skill-status.py --write-readme.
docs/REQUIRED-CHECKS.md The required-status-check set, plus the rules that keep a context reportable. Machine-read: scripts/parse-required-checks.py is its only parser, shared by scripts/apply-required-checks.sh and the contract guard. Edit § Current target set in the same PR that renames a required job or changes its trigger.
.skill-lint.yaml Severities and options of the skill-lint PR check (.github/workflows/skill-lint.yml). Read from the base branch, so an edit applies once merged. See CONTRIBUTING.md § skill-lint PR check.
hooks/*.mjs Non-telemetry session hooks are single Node.js (>= 20) scripts, spawned by the polyglot commands in hooks/hooks.json. Telemetry has no script — its hooks.json entries pipe the raw payload to uip track --hook. Everything is never-fail by contract (exit 0); the polyglot guards for a missing node/uip and silently no-ops.

When Reviewing or Editing Skills

  • Before changing flavor markers, overrides, discovery, package construction, publishing, or flavor CI, read .claude/skills/manage-skill-flavors/SKILL.md completely and follow its reference-routing instructions
  • Read the existing SKILL.md before making changes
  • Read every matching flavor override before changing a canonical marked passage; prefer an empty additive extension block over replacing a shared table, list, or navigation section
  • Preserve the Critical Rules section — these prevent expensive agent mistakes
  • Validate YAML frontmatter — broken frontmatter breaks skill discovery
  • Ensure description field has both TRIGGER and DO NOT TRIGGER conditions
  • When canonical flavor blocks or custom overrides change, run npm run skills:validate, npm run skills:build, and npm run skills:pack; inspect the actual generated tarballs before publishing
  • Preserve normal root npm pack and npm publish as backward-compatible default-only commands: they must compose marker-free skills transactionally and restore canonical sources. Keep npm run skills:pack as the all-flavor build/verification command used by CI and isolated flavor publishers, not as the default release path

When Writing or Modifying Tests

Tests live in tests/tasks/<skill-name>/ as coder_eval task YAMLs. Before authoring or editing a task, read tests/README.md for the full framework: tag taxonomy, experiment configs, success-criteria types, weight guidance, and the /generate-task and /test-coverage slash commands. Repo-specific authoring constraints (workflow, required tags, sandbox rules, anti-patterns) are in .claude/rules/test-writing.md.

Codereval Blob Results

  • Codereval dashboard results are stored in Azure Blob Storage account coderevaltests, container runs.
  • Run IDs are timestamped like YYYY-MM-DD_HH-MM-SS; list today's runs with prefix YYYY-MM-DD.
  • The run summary is <run-id>/run.json; per-task results live under <run-id>/<variant>/<task-id>/<replicate>/task.json.