feat(skill-authoring): refine skill authoring guidance

[alwaysmavs]

Summary

This PR modernizes the bundled oo-create-skill guidance while preserving its core behavior: the authoring agent decides whether the generated skill is standard or OO-powered from the intended runtime dependency, rather than from whether oo was used during authoring.

The previous refactor split the creator into a compact router plus focused references, but several parts of the guidance still assumed a narrower skill model. In particular, review and improvement requests were not explicit trigger cases, optional Agent Skills frontmatter was not described, all generated prose was forced to English, imported workflows were not treated as potentially untrusted, and forward testing did not explicitly cover activation boundaries. Some embedded-asset tests also continued to look for content in the root SKILL.md after that content had moved into references, and several assertions depended on physical Markdown line wrapping.

The updated guidance:

• expands the creator trigger contract to include reviewing and improving existing skills;
• documents current Agent Skills naming, description, optional frontmatter, progressive-disclosure, and host-metadata boundaries;
• chooses the generated skill language from its intended audience and runtime instead of requiring English universally;
• adds supply-chain, secret-handling, destructive-operation, and prompt-injection review for imported skills, scripts, and workflows;
• adds positive, negative, and runtime evaluation cases so descriptions are tested for both under-triggering and collisions with neighboring skills;
• preserves the standard versus OO-powered classification and the requirement to prove concrete OO capability contracts before writing runtime instructions; and
• updates embedded-asset tests to read the correct reference files and normalize Markdown wrapping before semantic assertions.

For users, this makes oo-create-skill a more portable and standards-aligned creator while retaining the safety and evidence requirements around OOMOL capabilities. Standard skills remain free of an unnecessary OO runtime declaration, and OO-powered skills still receive concrete service/action, payload, result, artifact, and failure guidance.

Validation

• bun run lint:fix
• bun run ts-check
• bun run test src/application/commands/skills/embedded-assets.test.ts
• bun run test — 1533 passed, 9 skipped, 0 failed

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 9af65d0f-9dda-414b-b901-4e9de8a87474

📥 Commits

Reviewing files that changed from the base of the PR and between ad5d588 and a184e7d.

📒 Files selected for processing (2)

• src/application/commands/skills/embedded-assets.test.ts
• src/application/commands/skills/embedded-assets.ts

🚧 Files skipped from review as they are similar to previous changes (2)

• src/application/commands/skills/embedded-assets.ts
• src/application/commands/skills/embedded-assets.test.ts

---

Summary by CodeRabbit

• New Features

  • Expanded the skill-creation guidance with workflows for standard, existing, and OO-powered skills.
  • Added reusable references covering authoring, adoption, runtime capabilities, validation, and acceptance checks.
  • Bundled the new reference materials across supported skill hosts.

• Tests

  • Updated coverage to verify bundled references, host-specific rendering, routing, validation guidance, and runtime requirements.

Walkthrough

The oo-create-skill workflow is shortened and now classifies standard versus OO-powered skills. Three reference documents provide shared authoring, existing-workflow adoption, and OO-powered runtime guidance. The bundled-skill registry now materializes these references for all supported agents. Embedded-asset tests were updated to verify the expanded bundle, reference content, host-specific rendering, and required-file loading.

Possibly related PRs

• oomol-lab/oo-cli#61: Refactors the bundled-skill registry and agent-name mapping used by the updated asset wiring.
• oomol-lab/oo-cli#141: Updates embedded asset expectations for oo-create-skill guidance.
• oomol-lab/oo-cli#258: Revises oo-create-skill prompt content and corresponding embedded-asset tests.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title matches the required format and accurately summarizes the skill authoring guidance update.
Description check	✅ Passed	The description is directly related to the bundled oo-create-skill refactor and its tests and references.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch agreed-vicuna

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@contrib/skills/shared/oo-create-skill/references/oo-powered.md`:
- Around line 12-23: Align the “Authoring State Machine” table of contents with
the actual section order in oo-powered.md: ensure the section 7 heading,
“Validate Before Finishing,” appears before “Final Acceptance Check,” or adjust
the heading hierarchy and TOC nesting so the documented workflow order is
unambiguous.

In `@src/application/commands/skills/embedded-assets.test.ts`:
- Around line 183-193: Update the path expectations in the
availableBundledSkillAgentNames test to avoid hardcoded "/" separators. Use the
repository’s node:path helper or normalize the actual and expected paths
consistently with the bundle’s logical-path contract, while preserving the
asserted file order and names.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 4cd8b4ec-6fc4-41b8-9c6f-e5695eab9fc8

📥 Commits

Reviewing files that changed from the base of the PR and between cecfa31 and 797ba26.

📒 Files selected for processing (6)

• contrib/skills/shared/oo-create-skill/SKILL.md
• contrib/skills/shared/oo-create-skill/references/existing-workflow.md
• contrib/skills/shared/oo-create-skill/references/oo-powered.md
• contrib/skills/shared/oo-create-skill/references/skill-authoring.md
• src/application/commands/skills/embedded-assets.test.ts
• src/application/commands/skills/embedded-assets.ts