Skip to content

refactor(skills): within-skill dedup, planning-arch split, cross-skill link CI gate (T2) - #1457

Closed
RaduAna-Maria wants to merge 1 commit into
fix/skill-efficiency-p0from
fix/skill-dedup-t2
Closed

RaduAna-Maria wants to merge 1 commit into
fix/skill-efficiency-p0from
fix/skill-dedup-t2

Conversation

@RaduAna-Maria

Copy link
Copy Markdown
Collaborator

Summary

Tranche 2 of the efficiency work, stacked on #1456. Within-skill deduplication (one home per fact), structural splits of the two most bloated reading paths, and a CI ratchet that prevents cross-skill link regressions.

Metrics

Change Before After
maestro-flow planning-arch.md (loaded on every build path) 6,227 words 4,345 (−30%); plan-document machinery → plan-document-guide.md, loaded only when a plan artifact is produced
review SKILL.md (loaded on every activation) 6,591 words 5,106 (−23%)
maestro-flow resource-discovery ladder restated 5× 1 home + 4 pointers
maestro-flow validate-once rule restated 6× 1 home (CAPABILITY rule #8) + 5 pointers
agents module-level-LLM-client rule 4× 1 (quickstart Critical Rules)
agents evaluator/smoke-set JSON 2 full copies 1 (evaluate.md)
coded-apps npm-registry explanation 3× 1 (debug.md)
Broken cross-skill links 3 (found by new lint) 0
Drifted copies eliminated review-workflow-guide.md report format (stale, 3 sections behind); maestro-flow gate vs worked-example contradiction reconciled

Net diff: 646 insertions / 617 deletions across 26 files — moves and pointers, not growth.

Correctness fixes folded in

  • Agent-node input wiring: maestro-flow's agent plugin never showed how a flow wires input into a published agent. Added the worked example — and in writing it, surfaced that node-output-wiring.md (self-declared single source of truth for =js: rules) had no row for uipath.core.agent.* nodes. Added the row: agent input slots take bare $vars references, never =js: (matches uipath-agents embedding-in-flows contract and the passing coded_in_flow e2e tasks). Rule-of-thumb sentence updated with the exception.
  • maestro-flow frontmatter rewritten brand-first (was TRIGGER for..., explicitly forbidden by skill-structure.md); trigger phrasing moved to when_to_use. Passes the description hook (608 chars; combined ≈818 of 1536).
  • "Is Maestro the Right Home" gate no longer tells a strict reader to abandon Maestro for the exact approval-gate scenario the worked example presents as canonical — scoped to single-wait-only lifecycles.

New CI gate

scripts/check-cross-skill-links.py + validate-cross-skill-links.yml:

  1. every cross-skill relative link must resolve (broken → fail);
  2. every (source→target) skill edge must be in the frozen ALLOWED_EDGES ratchet — new edges fail CI, shrinking the list is encouraged. Current edge set documented in-script with justifications; the agents↔maestro-flow cycle is marked for consolidation (tranche 4).

It caught 3 broken links the manual audit missed on its first run (wrong references/plugins/ path in agents' embedding-in-flows.md / flow-integration.md) — fixed here.

Validation

  • python3 scripts/check-cross-skill-links.py — OK
  • hooks/validate-skill-descriptions.sh skills/*/SKILL.md — all pass
  • scripts/check-skill-status.py — OK, 22 skills
  • All md links (intra- and cross-skill) in changed files verified to resolve
  • Every deduplicated fact verified to remain stated exactly once

🤖 Generated with Claude Code

…d cross-skill link CI gate

Dedup (one home per fact, pointers elsewhere):
- maestro-flow: resource-discovery ladder 5→1 (planning-arch §Capability
  Discovery), validate-once 6→1 (CAPABILITY rule #8), Edit-anchoring
  mechanics greenfield→editing-operations, agent-vs-script table →
  agent/planning.md
- agents: module-level-LLM rule 4→1 (quickstart Critical Rules), evaluator
  JSON 2→1 (evaluate.md), auth rules trimmed to authentication.md +
  two hard one-liners in Critical Rules
- coded-apps: npm registry explanation 3→1 (debug.md)
- review: stale drifted report-format copy in review-workflow-guide.md
  replaced with pointer to new canonical template (three-way drift removed)

Structure:
- maestro-flow planning-arch.md 6,227→4,345 words: plan-document machinery
  (gate, .arch.plan.md format, mermaid rules) → new plan-document-guide.md,
  loaded only when producing a plan artifact; Maestro-vs-queue gate
  reconciled with the orchestration worked example
- review SKILL.md 6,591→5,106 words (−23%): report contract → new
  references/review-report-template.md; Step 2.5 deduped against
  rule-catalog-workflow.md; anti-patterns compressed in place
- maestro-flow SKILL.md frontmatter: brand-first description (was
  'TRIGGER for...', forbidden by skill-structure.md), trigger phrasing
  moved to when_to_use

New content:
- maestro-flow agent/impl.md: published-agent input-wiring example (was
  documented only in uipath-agents); agent resource-node inputs take bare
   references — added the missing uipath.core.agent.* row to
  node-output-wiring.md's per-node-type table so the single source of
  truth actually covers agent nodes

CI gate:
- scripts/check-cross-skill-links.py + validate-cross-skill-links.yml:
  every cross-skill relative link must resolve and its (source, target)
  edge must be in the frozen allowlist — new edges fail CI, shrinking the
  list is encouraged. Caught 3 more broken links on arrival
  (agents embedding-in-flows/flow-integration → wrong maestro-flow plugin
  path), fixed here

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Jun 12, 2026 •

Copy link
Copy Markdown
Contributor

Claude finished @RaduAna-Maria's task in 3m 37s —— View job


Review: refactor(skills) — within-skill dedup, planning-arch split, cross-skill link CI gate (T2)

  • Gather context — read diff, existing comments, review guidelines
  • Review new CI gate (check-cross-skill-links.py + workflow)
  • Review maestro-flow dedup and planning-arch split
  • Review uipath-review SKILL.md restructure
  • Review uipath-agents dedup changes
  • Review uipath-coded-apps changes
  • Verify all relative links resolve
  • Check repo hygiene (CODEOWNERS, secrets, cross-skill refs)
  • Post final review

Summary

Tranche 2 of the efficiency initiative. Three main changes: (1) within-skill deduplication — facts that were restated 3-6x across files are collapsed to one canonical location with pointers; (2) structural splits — planning-arch.md loses its plan-document machinery to a new plan-document-guide.md, and review SKILL.md loses its inline report template to a new review-report-template.md; (3) a new CI ratchet (check-cross-skill-links.py + workflow) that prevents cross-skill link regressions and caught 3 broken paths.

Change-by-Change Review

1. scripts/check-cross-skill-links.py — new CI lint

Severity: OK

Well-structured ratchet script. The ALLOWED_EDGES set is justified per-edge with comments, the known agents↔maestro-flow cycle is documented for future consolidation, and the --list / --json output modes are useful for maintenance. The regex LINK_RE correctly handles #fragment suffixes and skips HTTP URLs. skill_of() correctly resolves relative to SKILLS_DIR.

One minor observation: the list_edges() function re-reads all markdown files and applies LINK_RE.finditer(text) on the full text rather than per-line (unlike find_findings()). This means line-number tracking isn't available in --list mode, but that's fine since --list is informational only.

2. .github/workflows/validate-cross-skill-links.yml — new workflow

Severity: OK

Minimal, correct: triggers on skills/**/*.md and the script/workflow files, contents: read permissions, Python 3.13, single run step. No issues.

3. skills/uipath-agents/references/coded/embedding-in-flows.md — cross-skill link fix

Severity: OK

Path updated from ../../../uipath-maestro-flow/references/plugins/agent/impl.md to ../../../uipath-maestro-flow/references/author/references/plugins/agent/impl.md. Target file verified to exist at the corrected path.

4. skills/uipath-agents/references/coded/flow-integration.md — cross-skill link fix (×2)

Severity: OK

Same path correction applied to both the in-solution and published variant links. Both target anchors (#node-instance-inside-nodes--in-solution-variant, #node-instance-inside-nodes--published-variant) match headings in the target file.

5. skills/uipath-agents/references/coded/frameworks/langgraph-integration.md — module-level client dedup

Severity: OK

Collapses the full "BAD / GOOD" code example (7 lines) into a one-line pointer to quickstart.md § Critical Rules plus a minimal "GOOD" snippet (3 lines). The canonical location (quickstart Critical Rules) retains the full explanation. Clean dedup.

6. skills/uipath-agents/references/coded/lifecycle/build.md — module-level client dedup

Severity: OK

Replaces 3 bullet points (scaffold cleanup, module-level prohibition, SDK import) with a single pointer to quickstart.md § Critical Rules. The canonical rule lives in quickstart and is the correct single home.

7. skills/uipath-agents/references/coded/lifecycle/evaluate.md — smoke-set JSON example added

Severity: OK

Adds the canonical smoke-test.json example that was previously duplicated in quickstart.md. Now quickstart.md points here for the JSON shape. The example is well-annotated (version string "1.0", required id/name, evaluations array).

8. skills/uipath-agents/references/coded/quickstart.md — major dedup

Severity: OK

The largest within-skill dedup: Step 7 (Evaluate) drops the inline evaluator and smoke-set JSON blocks (~42 lines) and replaces with a pointer to evaluate.md. The module-level-client prohibition is consolidated into Critical Rules (one canonical statement) and the auth flow is compressed. No information lost — every fact is still stated once.

9-10. skills/uipath-coded-apps/references/create-action-app.md + create-web-app.md — npm-registry dedup

Severity: OK

Both files replace the inline "Why the registry flag?" explanation with a pointer to debug.md § npm install fails with 401. The pointer is concise (--@uipath:registry rationale: [debug.md § ...]). Target file verified to exist.

11. skills/uipath-maestro-flow/SKILL.md — frontmatter rewrite + rule #3 dedup

Severity: OK

Frontmatter description rewritten brand-first ("UiPath Maestro Flow (.flow) — ...") per skill-structure.md rules — was previously "TRIGGER for...", which is explicitly forbidden. Trigger phrasing moved to when_to_use. The description field appears to be within the 1024-char limit based on the PR's claim of 608 chars, and combined with when_to_use at ~818, well under the 1536 combined limit.

Critical Rule #3 (resource discovery) is compressed from a 4-line sub-enumeration into an inline summary plus pointer to planning-arch.md § Capability Discovery. The full ladder still lives in planning-arch.

12. skills/uipath-maestro-flow/references/author/CAPABILITY.md — navigation table + anti-pattern updates

Severity: OK

Adds navigation entries for the new plan-document-guide.md. The "Never validate after every individual edit" anti-pattern now cross-references "rule #8" instead of restating the rationale. Clean.

13-14. brownfield.md + editing-operations-cli.md — validate-once pointers

Severity: OK

Both replace inline "do not validate after each individual edit — intermediate states are expected to be invalid" with a pointer to CAPABILITY.md rule #8. The brownfield.md file also updates the "Is Maestro the Right Home?" link from planning-arch.md to plan-document-guide.md (correct, since the gate moved).

15. editing-operations.md — parallel-Edit anchor table moved IN

Severity: OK

The anchor table, head-insertion rationale, disjointness rule, and pre-flight uniqueness check were previously in greenfield.md and are now the canonical home in editing-operations.md. This is the right move — the content applies to brownfield equally, and editing-operations.md is the strategy-selection document loaded for both greenfield and brownfield paths.

16. greenfield.md — parallel-Edit anchor table replaced with pointer

Severity: OK

The ~20-line anchor table section is replaced with a 2-line pointer to editing-operations.md § Anchoring parallel .flow Edits. The in-solution discovery ladder is similarly compressed with a pointer to planning-arch.md § Capability Discovery. The validate-once anti-pattern points to CAPABILITY.md rule #8.

17. plan-document-guide.md — new file (200 lines)

Severity: OK

Extracted from planning-arch.md. Contains: the "Is Maestro the Right Home?" gate (with the improved rule-of-thumb that scopes the single-wait exception and explicitly notes an approval gate inside a multi-resource flow is NOT a reason to leave), the .arch.plan.md output format, and the mermaid validation rules. All internal cross-references point back to planning-arch.md for topology-specific content (port reference, plugin index, wiring rules).

The correctness fix mentioned in the PR description is verified: the decision table column now says "The lifecycle's only content is a single human-wait or external-wait" (was "A single human-wait or external-wait" which a strict reader could interpret as forbidding any approval gate in a flow).

18. planning-arch.md — plan-document machinery extracted

Severity: OK

The "Before You Build" gate, "Output Format", and "Mermaid Validation Rules" sections (~190 lines) are replaced with pointers to plan-document-guide.md. The process list is updated with step 0 ("Gate first") and steps 6-7 now point to the new file. The "Producing the Plan Artifact" section at the end is a clean one-line pointer.

19. planning-impl.md — discovery ladder and agent-vs-workflow dedup

Severity: OK

The in-solution/tenant discovery steps (14 lines) and mock-replacement steps (5 lines) are compressed to pointers to planning-arch.md § Capability Discovery. The "Agent Nodes vs Workflow Logic" section (8 lines) is compressed to a one-line pointer to agent/planning.md § Agent vs Script/Decision Decision Table. All canonical locations verified.

20. plugins/agent/impl.md — discovery dedup + input wiring example added

Severity: OK

Discovery section compressed from 16 lines to 1 (pointer to canonical ladder). The new "Wiring input from an upstream node" section (23 lines) is new content, not moved — it fills a gap the PR description identifies: the agent plugin never showed how to wire flow input into a published agent. The example correctly uses bare $vars references (not =js:) matching the new node-output-wiring.md row.

21. plugins/agent/planning.md — discovery dedup

Severity: OK

Same pattern as impl.md: 16-line discovery section → 1-line pointer to planning-arch.md § Capability Discovery.

22. shared/file-format.md — anchor reference updated

Severity: OK

Link target for parallel-Edit anchoring updated from greenfield.md to editing-operations.md (the new canonical home). Correct.

23. shared/node-output-wiring.md — agent resource-node row added

Severity: OK

New row for uipath.core.agent.* nodes: bare $vars reference only, never =js:. The rule-of-thumb sentence is updated to list agent resource-node inputs as an exception. This is a correctness fix — the table previously had no row for agent nodes, so an agent following the generic rule of thumb would incorrectly wrap inputs in =js:.

24. skills/uipath-review/SKILL.md — major dedup (−177/+24)

Severity: OK

The inline report template (~118 lines: full markdown report structure, structural metrics, severity labels, quality thresholds) and the Step 2.5 expanded procedure (~35 lines: CLI command table, judgment catalog detection table) are extracted to review-report-template.md and compressed to pointers + inline summaries. The anti-patterns section is compressed from verbose prose to terse references back to Critical Rules. No information lost — the new review-report-template.md contains the exact same report structure, updated with the improved format from the PR description (includes review-report-template.md's extended sections like PDD Alignment, Rule Findings, Transaction Shape). The Step 5 pointer correctly names all required sections.

25. review-report-template.md — new file (125 lines)

Severity: OK

Canonical home for the review report format. Contains: report rules (4), structural metrics table, full markdown report template with all sections, finding severity labels, and quality determination thresholds. This is the reconciled version — the previous state had the report format duplicated in SKILL.md and review-workflow-guide.md with the workflow-guide copy being 3 sections behind (missing PDD Alignment, Rule Findings, Transaction Shape, Per-Project Summary). Now there's one source of truth.

26. review-workflow-guide.md — stale report format removed

Severity: OK

The 57-line inline report format (which was stale — missing sections the SKILL.md copy had) is replaced with a 1-line pointer to review-report-template.md. This eliminates the drift vector.

What's Missing

  • No CODEOWNERS entry for /scripts/: The scripts/ directory has no specific CODEOWNERS entry, but the default * wildcard covers it and there are other existing scripts (check-skill-status.py, check-cli-verbs.py, check-skill-verbs.py) without specific entries either. Consistent with current convention — not a gap.
  • Nothing else identified. All links verified to resolve. No new skills added (no test requirement). No secrets or personal paths.

Area Ratings

Area Status Notes
Frontmatter OK maestro-flow rewritten brand-first per skill-structure.md; description within limits
E2E Tests N/A No new skills added; existing skill changes don't alter CLI workflows
Skill Body OK All dedup preserves information; pointers are precise with section anchors
References & Assets OK Two new reference files (plan-document-guide.md, review-report-template.md) are clean extractions; one new input-wiring example fills a real gap
Repo Hygiene OK No secrets, no unrelated changes, 3 broken cross-skill links fixed, new CI gate prevents regressions

Issues for Manual Review

  • Agent input wiring correctness: The new node-output-wiring.md row and impl.md example assert that uipath.core.agent.* input slots take bare $vars references and reject =js:. This matches the PR description's claim and is consistent with the uipath-agents embedding-in-flows contract — but the reviewer cannot verify this against the actual UiPath runtime. Domain expert confirmation that =js: truly fails on agent inputs would be valuable.
  • Maestro gate scoping: The "Is Maestro the Right Home?" gate now explicitly notes that an approval gate inside a multi-wait/mixed-resource flow is normal Maestro design. This is a subtle correctness change to avoid agents incorrectly abandoning Maestro for the very scenario the worked examples present as canonical. Domain review of the scoping is recommended.

Conclusion

Clean, well-structured deduplication PR. Every fact remains stated exactly once, pointers are precise (section-anchored), and the three correctness fixes (broken cross-skill links, agent input wiring, Maestro gate scoping) are well-motivated. The new CI ratchet is a strong addition — it formalizes the "no cross-skill references" rule with a shrink-only allowlist. The net diff (+646/−617) is essentially moves and pointers, not growth.

No blocking issues found. This PR is ready for domain-expert approval on the two manual-review items above.


Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant