Advanced Skill Authoring

Use this guide when one broad Skill has grown into several distinct workflows that should remain focused, reviewable, and backed by appropriate local resources or shared Context Assets.

Run renma guide skill before generating new files. A focused Skill owns the workflow it needs to execute well; it is not required to be a thin router. Renma validates repository structure and declared Context relationships but does not select a Skill at runtime.

Skill Discovery provides explicit canonical continuation metadata, published entrypoints, repository-wide adoption, reachability and coverage, route-cycle review diagnostics, a static graph projection, and the versioned Skill Index. These remain separate from repository file and Skill-local support-resource discovery and from runtime Skill selection. See the Skill Discovery Graph and Index contract.

Derive A Focused Skill From An Existing Skill

A repository may begin with a broad workflow such as setup, specification review, regression planning, or test generation. As responsibilities diverge, prefer separate Skills with explicit selection boundaries over one large Skill that embeds every variant.

Because deriving focused Skills intentionally reconsiders asset boundaries, start by establishing the proposed structure and inspecting the existing Skill and its repository relationships:

renma guide skill
renma inspect skills/setup/appium/SKILL.md
renma graph . --focus skill.setup.appium --format mermaid
renma catalog . --format json

Use the evidence to answer:

• Which trigger and exclusion boundaries are genuinely different?
• Which instructions and completion criteria are shared?
• Which knowledge should remain in independently owned Context Assets?
• Which owner, policy, dependency, or domain decisions require human input?
• Can the original Skill stay focused, or should its responsibility narrow?

Do not invent a hierarchy merely to make the repository look organized. Create a new Skill only when its usage boundary and workflow are independently useful.

Keep Derived Skills Focused

A derived Skill should own:

• when its workflow should and should not be selected;
• required inputs and preflight checks;
• ordered instructions and decision points;
• safety and policy constraints;
• Context relationships; and
• completion and verification criteria.

Domain, product, testing, platform, and tool knowledge should remain in Context Assets when it is reused across Skills or has an independent owner, lifecycle, maintenance boundary, source-of-truth role, or another explicit reason for independent review and governance. Correctness importance alone is not an independent Context boundary.

Skill-specific detailed procedures and variants belong in local references; deterministic implementation belongs in scripts; output resources belong in assets. Ordered workflow steps, read conditions, constraints, and completion criteria remain in SKILL.md.

skills/setup/appium-ios-simulator/SKILL.md
skills/setup/appium-android-emulator/SKILL.md
skills/setup/appium-real-device/SKILL.md

contexts/tools/appium/setup-basics.md
contexts/tools/appium/capabilities.md
contexts/platform/ios/simulator-setup.md
contexts/platform/android/emulator-setup.md
contexts/mobile/real-device-risk.md

Use renma guide skill to define the smallest graph, then generate each new target once:

renma scaffold skill skills/setup/appium-ios-simulator/SKILL.md \
  --owner mobile-platform

Then review and complete its semantics using platform-native Skill authoring guidance within the established Renma boundaries. Do not run another independent generator against the same file.

Declare Current Repository Relationships

For the complete metadata mapping, value formats, applicability, and compatibility status, see the User Manual's Authoritative Metadata Reference. This section focuses on choosing and using relationship declarations during advanced Skill authoring.

Use the shipped Context and Context Lens relationship fields. For example:

---
name: appium-ios-simulator
description: Prepare Appium for an iOS Simulator. Use for simulator-based iOS setup; do not use for physical-device provisioning.
metadata:
  renma.id: skill.setup.appium-ios-simulator
  renma.title: Appium iOS Simulator Setup
  renma.owner: mobile-platform
  renma.status: experimental
  renma.tags: '["setup","appium","ios"]'
  renma.requires-context: '["context.tools.appium.setup-basics","context.platform.ios.simulator-setup"]'
  renma.optional-context: '["context.tools.appium.capabilities"]'
---

renma.requires-context records knowledge the workflow normally depends on. renma.optional-context records knowledge needed only for some cases. These are static repository relationships; they do not load or inject Context at runtime.

When this Skill itself owns a reviewed continuation decision, it may add renma.continues-with as a JSON-array string of exact Skill IDs or repository-relative SKILL.md paths. Keep the conditions and no-match behavior in the source body; the declaration does not make Renma select or execute the next Skill. See the Skill Discovery Graph and Index contract.

Use renma.conflicts only when two declared assets should not be used together without review. Do not use it as a substitute for a clear trigger description.

Suspend And Restore A Skill

Use suspended when a Skill must remain inventoried but must temporarily stop participating in active dependency and Discovery flows. Record the reviewed transition with flat string metadata:

metadata:
  renma.status: suspended
  renma.status-reason: Temporarily disabled while issue QE-1234 is corrected.
  renma.status-changed-at: "2026-08-03"

A suspended Skill cannot be an effective published entrypoint or route target. Required active dependencies to it block Readiness; optional dependencies warn and remain visible for review. Renma does not restore a Skill on a timer. After the underlying issue is reviewed and verified, change all three values in one reviewed commit or pull request, for example:

metadata:
  renma.status: stable
  renma.status-reason: Restored after QE-1234 was corrected and verified.
  renma.status-changed-at: "2026-08-06"

renma diff and CI compare status, reason, and transition date independently; Git and pull-request history retain the full audit trail. Do not use last-reviewed-at as the lifecycle transition date, and do not infer or backfill either date from filesystem timestamps.

Router, Workflow, And Operational Responsibilities

A normal Skill may act as a published entrypoint, a broad router, an intermediate router, a workflow/orchestration Skill, a specialized operational Skill, or more than one of these roles. These are responsibilities, not new Renma asset kinds. Every node remains a focused Agent Skill with a meaningful bounded responsibility.

skill.a
  -> skill.b
      -> skill.c

skill.a
  broad entrypoint or router

skill.b
  narrower router or workflow coordinator

skill.c
  specialized operational Skill, often owning detailed Context,
  references, scripts, or assets

A router still owns a real decision, prerequisite check, classification, no-match result, or evidence handoff; it is not merely a directory listing. An intermediate Skill may own Context when routing itself requires durable domain knowledge. An operational Skill may also be published when it is a genuine independent first hop, and a workflow Skill may perform operational work before continuing.

The recommended workflow composition model is:

Workflow Skill
  owns overall orchestration policy

Child Skills
  own individual operational responsibilities

The workflow Skill body may define ordering, branching conditions, all-of versus one-of intent, parallel review, approval gates, stop and retry conditions, evidence passed between steps, and completion conditions. Child Skill bodies own their individual triggers, inputs, work, constraints, evidence, and completion rules.

renma.continues-with declares only possible authoritative continuation edges. It does not define execution order, priority, automatic invocation, all-of, one-of, parallel execution, retries, approval gates, or input/output handoff schemas. Declaration order has no priority meaning. Renma does not parse the workflow prose or execute child Skills; workflow semantics remain in the body of the owning workflow Skill.

Use renma skill-index . to review the compact static first-hop and continuation evidence. Open the source Skills to decide whether their authored conditions apply to a request.

Continuation cycles are not automatically invalid. A review, retry, cross-check, or refinement workflow may intentionally return to an earlier Skill. DISCOVERY-ROUTE-CYCLE records the exact usable internal declarations; it does not prove runtime recursion or instruct an author to remove the first edge. Review every internal continuation and make stop, ask, retry, handoff, and completion conditions explicit in the owning Skill bodies. Remove or redirect an edge only when repository evidence shows that continuation is stale or accidental. An intentional bounded cycle may remain.

Review Selection Boundaries

Renma does not choose among related Skills, so their portable descriptions must make the distinction reviewable to the consuming platform.

Situation	Prefer Skill	Boundary
iOS Simulator setup	skill.setup.appium-ios-simulator	Simulator workflow; excludes physical devices
Android Emulator setup	skill.setup.appium-android-emulator	Emulator workflow; excludes physical devices
Real-device setup	skill.setup.appium-real-device	Provisioning and device-risk workflow
General Appium capability review	A focused capability Skill or Context lookup	Not a platform setup workflow

For each related Skill, confirm:

• the description states both the positive trigger and important exclusions;
• required inputs distinguish it from nearby workflows;
• shared knowledge is referenced instead of copied;
• completion criteria are specific to the workflow; and
• a human has confirmed ownership, policy, dependencies, and domain behavior.

Validate And Review

Run the focused and repository-wide checks after authoring:

renma inspect skills/setup/appium-ios-simulator/SKILL.md
renma graph . --focus skill.setup.appium-ios-simulator --format mermaid
renma catalog . --format markdown
renma scan . --fail-on high

Fix relevant diagnostics and rerun the scan. Do not weaken security policy or add a suppression merely to pass. Have a human review meaningful semantic changes before merging.

This workflow creates and governs current Agent Skills-compatible repository assets. It does not automatically add continuation declarations or published entrypoints, assemble prompts, select Skills, or execute workflows. Reachability and coverage are static reports over declarations, not runtime behavior.