# 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](skill-discovery.md). ## 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: ```bash 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`. ```text 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: ```bash 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](user-manual.md#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: ```yaml --- 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](skill-discovery.md). 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: ```yaml 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: ```yaml 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. Use `revoked` instead when trust or authorization for continued use has been explicitly withdrawn because of a known problem. Revocation is stronger than temporary suspension and also requires reviewed reason/date evidence: ```yaml metadata: renma.status: revoked renma.status-reason: Revoked because the documented procedure can cause unsafe destructive behavior. renma.status-changed-at: "2026-09-03" ``` A revoked Skill is unusable for active dependencies and Discovery. Renma emits review evidence for its active dependents but does not revoke them, choose a replacement, require `superseded-by`, or automatically restore or archive the target. ## 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. ```text 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: ```text 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 After authoring, run the scan and all repository-required checks for the current change and stage: ```bash renma scan . --fail-on high ``` Use additional views only when they answer a current structural or governance question: ```bash renma inspect skills/setup/appium-ios-simulator/SKILL.md renma graph . --focus skill.setup.appium-ios-simulator --format mermaid renma catalog . --format markdown ``` Fix relevant diagnostics and rerun affected checks. After relevant checks pass, repeat or broaden validation only for further changes, failed checks, or unresolved concerns. Required CI and release checks still apply. 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.