# Renma Authoring Guide

This is the canonical guide for placing, authoring, and improving Skills,
Context Assets, Context Lenses, and Skill-local support in a Renma repository.
It is authoritative for Renma's authoring boundaries, evidence rules, creation
gate, asset responsibilities, and handoff contract. Its interaction strategies
are guidance for satisfying those invariants, not an authoritative description
of the consuming LLM's internal reasoning algorithm.

## Responsibility Boundary

For a new Skill, or when intentionally redesigning asset boundaries, start with
`renma guide skill`. Renma first establishes:

- the smallest non-redundant asset graph;
- Skill, Context, Context Lens, Reference, Script, and Example responsibilities;
- canonical metadata and Agent Skills compatibility;
- Context placement and source-of-truth representation;
- file and resource boundaries;
- dependency and graph validation;
- ownership and lifecycle governance;
- security policy validation;
- workflow clarity diagnostics; and
- repository-wide scan and readiness evidence.

After those boundaries are established and the creation gate passes,
platform-native Skill authoring guidance may refine the name and trigger
description, usage and exclusion boundaries, instructions, workflow,
constraints, completion criteria, and examples that resolve real ambiguity. It
is not the authority for Renma metadata, Context placement, repository asset
boundaries, file count, source-of-truth representation, or whether scripts and
support files should exist.

A name change that affects the canonical Skill directory/name relationship is
an intentional path and identity change, not an ordinary semantic rewrite.
Review the move or rename and rerun Agent Skills and Renma validation. Ordinary
maintenance of an existing Skill starts with `renma scan . --fail-on high`.

Renma does not generate domain intent or automatically improve a Skill body.
Human judgment remains required for semantics, ownership, policy, dependencies,
and source authority. The central principle is:

> Create the smallest non-redundant Renma asset graph that preserves execution
> clarity and traceability.

Write canonical governance and security wording in English when you need the
strongest bounded natural-language diagnostics. Multilingual and non-English
Skill and Context content is supported and is not invalid merely because of
its language. Renma does not translate security vocabulary or emit a generic
non-English warning; documented language-independent evidence such as URLs,
commands, paths, executable references, Markdown structure, and hidden Unicode
continues to be inspected. Keep operational instructions visible in Markdown.
HTML comments are hidden by renderers but readable in raw source by an agent,
so security-sensitive instructions placed there receive a dedicated finding.

## Authoring Contract And Adaptive Clarification

`renma guide skill` remains deterministic and non-interactive. It prints the
authoring contract; the consuming LLM conducts any needed conversation and
investigates applicable evidence, the user supplies domain and governance truth,
Renma supplies deterministic rules and repository evidence, and a human approves
meaningful decisions. The external LLM investigates and proposes, Renma
validates supplied structure and deterministic repository evidence, and the
human reviews meaningful decisions. Renma does not accept task text, ask
questions, retain conversation state, interpret answers, or create assets from
the guide. It does not certify that a handoff's conversation, human review,
source authority, blocker completeness, or domain facts are true.

When the user asks to create a Skill, the consuming LLM evaluates the creation
gate before file creation. It may organize its work in any way that preserves
the contract:

```text
understand and investigate applicable evidence
  -> evaluate creation-gate requirements
  -> if needed, ask only about unresolved Blocking authoring decisions
  -> establish the smallest justified asset structure
  -> pass the gate when every gate requirement is established and no blocker remains
  -> write a renma.skill-authoring-handoff.v1 exchange artifact
  -> scaffold and author
  -> validate
  -> repair, investigate, ask again, or justify no change
  -> re-enter the creation gate if asset boundaries may change
  -> human review
```

The arrows show dependencies and externally observable transitions, not a
required internal reasoning algorithm. The consuming LLM may combine and revisit
activities in any useful order, and may skip one only when its required outcome
is already established or its condition does not apply. In particular,
clarification is not mandatory when every creation-gate requirement is already
established.

Evidence, authority, ownership, security, asset responsibilities, completion,
and the handoff contract are requirements. Decision tables, question themes,
and progress-summary formats are optional working aids. Preserve the factual
and progression distinctions they explain; neither their presentation nor an
internal reasoning sequence is an additional gate requirement. The structured
handoff still uses its defined fields.

The user does not need to supply a plan-quality specification. When a decision
summary helps the interaction, keep the working state compact:

```text
Current understanding

Confirmed
- Facts supported by an applicable truth source.

Proposed
- Reversible structural defaults or justified design suggestions.

Unresolved
- Human truth or missing applicable evidence that must not be invented.

Question, when needed
- The smallest effective clarification of unresolved Blocking authoring decisions.
```

A proposal never silently becomes confirmed. Explicit user delegation can
confirm authority to choose one reversible default, but it does not establish
unrelated domain facts.

### Unknown scope

Before applying progression, classify the unknown's scope:

- An **authoring decision** defines the Skill contract: its workflow, output,
  usage boundary, required inputs, completion or failure behavior, source
  authority, Skill-versus-Context placement, runtime access or security policy,
  repository structure, or authored behavior. An unresolved authoring decision
  may be Blocking.
- A **runtime task unknown** is expected to vary or be missing in material the
  finished Skill processes. It may be an ambiguous specification rule, timeout,
  retry or rollback behavior, permission, acceptance criterion, expected result,
  or current schema. It does not automatically block creation. Define how the
  Skill reports it with evidence and impact, continues independent work, asks
  the runtime user only when the current execution stage depends on it, or stops
  safely without inventing truth.

Do not ask the author to resolve task-instance unknowns merely because the
finished Skill may encounter them.

A runtime-stage blocker is execution behavior that the authored Skill must
handle. It does not enter the authoring creation-gate blocker set merely because
a future task instance may encounter it. Only an unresolved authoring decision
about whether the Skill should ask, report, defer, or stop in that situation may
block Skill creation.

```text
Runtime task unknown:
- The reviewed specification does not define the expected result.

Runtime-stage behavior:
- Specification review reports it as a finding.
- Test-case generation asks for clarification or stops before inventing an
  expected result.

Possible authoring blocker:
- It is not yet decided whether the Skill should ask, report, defer, or stop in
  that situation.
```

### Progression and adaptive questioning

Confirmed, Proposed, and Unresolved describe epistemic support. A separate
progression classification determines whether authoring can proceed:

| Progression | Meaning | Examples |
| --- | --- | --- |
| Blocking | Must be resolved before the current creation gate passes | Unclear task or result, required source authority or product behavior, material security permission, unsafe failure behavior, unjustified Skill-versus-Context boundary, or a missing file-mode owner |
| Reversible default | A safe, easily changed Proposed decision that invents no domain or governance truth and broadens no security permission | No script or Context Lens by default, a tentative directory name, or another minimal choice delegated by the user |
| Deferred | Proposed or Unresolved but not needed at the current stage | Wording, optional examples, final tags, non-blocking edge cases, future reuse, or speculative features |

Keep disposition separate from epistemic support, scope, and progression:

| Disposition | Action |
| --- | --- |
| Ask now | Ask an answerable Blocking authoring decision that still requires human truth |
| Queue as blocker | Retain a Blocking decision that is not yet appropriate to ask or resolve |
| Proceed with reversible default | Use a safe Proposed choice that invents no truth or permission |
| Defer | Keep an item visible when the current stage does not depend on it |
| Report as finding | Preserve an evidence-backed runtime unknown in the Skill's output with impact or risk |

A reversible default remains Proposed when used. A Deferred decision remains
visible rather than becoming forgotten or implicitly resolved. If later
evidence makes a Deferred decision material to correctness, security,
completion, or asset boundaries, move it to Blocking and re-enter clarification.

Keep the complete current set of unresolved and Blocking decisions in temporary
authoring state. Never hide an unasked blocker or relabel it Deferred merely
because it is not part of the current interaction. Present enough state for the
user to understand material blockers and progress; the full set need not be
repeated mechanically in every response.

Do not ask for a downstream authoring decision when a meaningful answer depends
on an unresolved upstream authoring decision. Resolve or investigate the
prerequisite first. This is a dependency invariant, not a required decision-tree,
frontier, round-based, or persisted-state implementation.

Use the smallest effective interaction. A focused batch—often one to three
closely related questions—is a useful default when several answerable Blocking
decisions can be resolved together. The consuming LLM may instead ask one
question, ask a larger coherent set, or use another interaction strategy when
that better satisfies the contract. Question count and turn structure are not
correctness invariants. A compact progression summary can help when several
material decisions remain. For example:

```text
Current progression

Blocking decisions: 4
- Failure and recovery contract
- Required input boundary
- Runtime source-access policy
- Context owner
- Asking now: the answerable highest-impact questions below

Queued from the complete blocker list above (not additional): 4

Proposed reversible defaults
- No script by default
- No Context Lens by default

Deferred
- Final tags
- Additional examples unless real ambiguity emerges
```

> Declare the gate passed and proceed only after every gate requirement is
> established, including the smallest justified asset structure, and no
> Blocking decision remains. Reversible defaults and Deferred decisions may
> remain, provided they are visible, safe, and do not conceal missing domain or
> governance truth.

Do not guess does not mean stop and ask about every unknown. Never present
missing truth as Confirmed; continue work that does not depend on it; preserve
it with evidence; report assumptions and uncertainty; ask only when it blocks
the current stage; and never manufacture expected behavior merely to finish an
output. Continue independent investigation and preparation while a question is
pending. File creation still waits until every creation-gate requirement is
established and no Blocking decision remains.

Preserve the raw evidence. When grouping helps resolve related unknowns, group
them by the decision they depend on. Timeout, retry count, partial success, and
rollback usually form one **Failure and recovery behavior** theme rather than
four questions. Prioritize themes by risk and downstream impact, and expand an
item only when its distinction changes the result. There is no fixed maximum
for raw unknowns or themes.

When a workflow has meaningful stages, reassess themes at each transition. A
specification ambiguity can be Report as finding during review and remain
non-blocking while designing coverage for unaffected behavior. Treat it as a
runtime-stage blocker when concrete expected-result generation depends on it,
then follow the Skill's authored ask, report, defer, or stop policy. Do not add
the task-instance fact to the authoring creation-gate blocker set. Re-enter
authoring clarification only when the Skill's handling policy or asset boundary
itself is unresolved; return the fact to Report as finding when a later requested
output does not require resolution.

When proceeding, identify the defaults and meaningful deferred items, do not
present either as Confirmed, and do not ask for redundant confirmation after
the user has authorized progress. “Use your judgment” delegates only identified
reversible choices; explain the selected default and do not infer product
behavior, source authority, ownership, security permission, or unrelated facts.

Many raw unknowns may be the expected output of a review Skill. Reconsider the
Skill boundary only when Blocking themes reveal materially independent tasks,
inputs, outputs, users, security contracts, completion criteria, or workflows.
Propose a split or narrower first Skill, explain the responsibilities, keep the
boundary Proposed, ask only if evidence cannot resolve it, and re-enter the gate
after the decision. Do not split automatically because the count is high.

Concrete demonstrations are intentionally separated into the non-normative
illustration section below. They do not define request categories or add rules
to this protocol.

### Truth sources

| Evidence source | May confirm | Required qualification |
| --- | --- | --- |
| Explicit user statements | Intent, governance decisions, source designation, fallback, and other decisions the user has authority to make | Designating a specification does not prove its contents |
| User-provided artifacts | Facts in supplied documents, specifications, examples, logs, or schemas | Provenance and applicability must be clear; identify the artifact |
| Generated and derived artifacts | Bounded observations made by an identified producer in Renma reports, test results, logs, diagnostics, machine-generated review summaries or comments, external-review artifacts, and other derived output | Provenance, subject, scope, applicability, and currentness must be clear; apply this qualification together with any user-provided, repository, or external-source classification because delivery or location does not broaden the supported evidence boundary; evidentiary value does not make the artifact governing authority for domain behavior, policy, completeness, or safety |
| Repository evidence | Applicable and effective repository facts | Evidence must be unambiguous; revoked, deprecated, archived, stale, conflicting, unresolved, or diagnostic-blocked evidence is not Confirmed merely because it exists; identify the file, metadata, lifecycle evidence, or command result |
| Reviewed authoritative external source content | Domain facts governed by a user-designated source | The authoring environment must be permitted and able to consult it successfully; identify the source and relevant section or evidence |
| Renma structural rules | Structural constraints and proposed defaults | They do not establish product or domain truth |

Generation, detail, prior use, or a favorable result alone does not make derived
claims authoritative. Confirm claims beyond the artifact's supported evidence
boundary through the applicable truth source. When generated or derived
material conflicts with applicable evidence, preserve the conflict and
determine the governing authority. Do not choose a winner by recency, detail,
or model confidence alone. An authorized human's explicit decision retains the
semantics of an explicit user statement regardless of medium.

A user can confirm that a URL is intended to be authoritative. Its schema,
fields, constraints, and behavior become Confirmed only after the source content
is successfully consulted or supplied through another approved process. A known
URL and model memory are not source-content evidence.

Authoring-time access is separate from finished-Skill runtime access.
Authoring-time consultation depends on the current request, tools, and
environment. Future runtime access instructions must agree with the finished
Skill's effective Renma security policy. Future metadata never retroactively
authorizes the authoring agent. If authoring-time access is unavailable, ask
for the relevant content through an approved process or keep source-dependent
facts Unresolved; do not fill them from memory or plausible assumptions.

Before asking the user, inspect applicable evidence that can answer the current
question and consider safe structural defaults within the user's authorization.
Use existing decisions and authorizations only while they remain applicable to
the same scope and action; preserve requirements for separate or immediate
approval. Ask only when a Blocking authoring decision still requires human truth
or unavailable source content. Use only the relevant commands rather than
treating every view as ceremony:

```bash
renma scan . --fail-on high --format json
renma catalog . --format json
renma inspect <relevant-file> --format json
renma graph . --focus <relevant-id-or-path> --format json
```

Ask only about decisions that materially affect the task, inputs, output,
completion or failure behavior, usage boundaries, placement, source authority,
Context necessity, external access, security policy, or support-file
justification. Do not ask the user to choose metadata syntax, repeat known
facts, complete a large questionnaire, or define speculative future features.
Wording, tags, examples, and formatting can be refined later.

### Creation gate

Before creating files, establish the focused recurring task, expected result,
meaningful completion or failure behavior, smallest justified asset structure,
source authority, authoring-time consultation, finished-Skill runtime access,
blocking security and domain decisions, and the owner required by file-mode
scaffold. Pause while a blocking human decision remains unresolved.

Do not block creation on runtime task unknowns when the Skill contract can
detect and report them with evidence, continue unaffected work, request runtime
input only when needed, and stop safely if the requested output would otherwise
require invented truth.

The gate does not require a complete plan, every edge case, final prose, all
examples, finalized tags, future capabilities, or perfect certainty about
non-blocking details. Before declaring the gate passed, establish and present
the smallest proposed structure. The gate may be declared passed only after
every gate requirement is established, including that structure, and no
Blocking decision remains. Identify remaining non-blocking proposals and ask
for confirmation only when a meaningful discretionary boundary remains
uncertain. Do not add a redundant confirmation after the user has already
authorized creation.

### Post-validation decisions

Classify each relevant finding before acting:

- **Deterministic repair:** make a bounded correction supported by the
  diagnostic and evidence only when the constraints uniquely determine the
  patch, then rerun relevant validation. Deterministic detection alone is not
  enough.
- **Repository investigation:** inspect ambiguous targets, parents, owners,
  possible Context reuse, or conflicting conventions before asking the user.
- **Human decision required:** ask a focused question when ownership, source
  authority, behavior, permissions, fallback semantics, Context necessity, or
  deliberate script use depends on human truth.
- **No change justified:** explain why the evidence does not support a repair
  or why an advisory reflects reviewed intentional design.

An invalid encoding is deterministic only when its intended supported value is
explicit and unambiguous. A path or ID typo is deterministic only when exactly
one intended existing target is proven. Remove an unsupported field
automatically only when doing so provably loses no intended meaning; otherwise
investigate whether the information belongs in the Skill body, supported
metadata, a Context Asset, or nowhere.

Repeated-context findings are evidence, not automatic consolidation patches.
Do not delete or rewrite content solely because a repeated section, code block,
or context pattern exists. Inspect all occurrences, determine ownership and the
source-of-truth boundary, prepare a consolidation proposal, and require human
review before choosing an authoritative copy, owning asset, Context placement,
or replacement references.

Follow Diagnostics v2 repair constraints and verification steps. Preserve any
explicit prohibition on automatic semantic changes.

If semantic refinement, source review, real usage, or validation reveals a
possible asset-boundary change, stop the structural edit. Record the need as
Proposed or Unresolved, inspect relevant evidence, ask only when human truth
remains necessary, and re-enter the creation gate. Change the agreed files,
metadata, Context relationships, scripts, examples, or support assets only
after the gate passes, then continue authoring and validation.

Never add a suppression automatically, weaken security policy, manufacture
metadata, rewrite semantics merely to clear a finding, or turn a human decision
into a model assumption.

### Reviewed-decision persistence

Persist durable reviewed workflow, boundary, input, output, completion,
Context, authority, fallback, metadata, and security decisions. Do not persist
the conversation transcript, private reasoning, temporary Confirmed / Proposed
/ Unresolved headings, rejected proposals, unanswered questions, speculative
work, or invented decision-state metadata. Report non-blocking uncertainty to
the user instead of hiding it in authoritative prose.

Before human approval, present a compact review summary. For each material
non-obvious decision, state its governing evidence or authority and any
evidence-backed consequence of changing it. When the consequence is not
established, explicitly label the potential impact Proposed or Unresolved and
state remaining non-blocking uncertainty. This summary is a review surface, not
proof that the reviewer understood, approved, or independently verified the
proposal. Persist only the durable reviewed rationale that belongs in the asset
owning the decision; do not store the temporary summary as conversation-state
metadata.

## Focused Workflow Model

A Skill is a focused workflow entrypoint, not a thin router. `SKILL.md` may own
positive and negative selection boundaries, required inputs, preflight checks,
ordered instructions, decisions, short Skill-specific commands, examples,
edge cases, safety constraints, completion criteria, and verification. Renma
does not warn merely because a Skill is procedural or includes an executable
command.

Use Agent Skills progressive disclosure deliberately:

1. Metadata: `name` and `description` let a client decide whether to activate
   the Skill.
2. Instructions: the activated `SKILL.md` carries the focused workflow and
   explicit read or execution conditions.
3. Resources: local files are read or executed only when the workflow calls
   for them.

Choose placement by responsibility, ownership, and reuse—not size alone:

| Content or responsibility | Correct placement | Ownership or reuse test | Common misuse |
| --- | --- | --- | --- |
| Review supplied test code and produce prioritized findings; define selection boundaries, inputs, ordered steps, decisions, constraints, verification, output, and completion | Skill in `SKILL.md` | Required to perform one focused workflow | Reducing the Skill to a thin redirect or moving its task contract into Context |
| Shared rules for reliable automated tests or other durable, source-backed knowledge | Context Asset under `contexts/` | May serve multiple Skills or has an independent owner, lifecycle, separate maintenance, source-of-truth role, or another explicit reason for independent review and governance; source-of-truth status alone is sufficient | Extracting task-specific knowledge merely because it matters to correctness, storing one workflow's transient state as Context, or duplicating independently maintained Context in a local Reference |
| Emphasize determinism, isolation, and false-confidence risk while interpreting declared test-quality Context | Context Lens under `lenses/` | The same Context benefits from reusable purpose-specific interpretation | Creating a Lens with no Context target, copying Context, or storing only a persona or runtime route |
| A stricter review variant for one Skill | Skill-local Profile under `profiles/`, if current Profile semantics fit | An overlay or variant owned and loaded by one Skill | Treating Profiles as generic global personas or a substitute for shared Context |
| Detailed framework-specific review notes used only by one Skill | Skill-local Reference under `references/` | Supporting detail owned and loaded by one Skill | Promoting local detail without evidence of independent reuse or ownership |
| A representative good or bad test implementation | Skill-local Example under `examples/` | A fixture or demonstration owned by one Skill | Hiding required workflow instructions only in an example |
| Deterministic, repeatedly executed implementation | Script under Skill-local `scripts/`, or shared helper under `tools/` | Code is safer and more repeatable than prose; use `tools/` when implementation is shared | Embedding a large executable implementation in prose or treating a script as knowledge |
| Templates, images, data, fonts, PDFs, or output resources | Asset under Skill-local `assets/` | Consumed, copied, or transformed as material rather than read as instructions | Putting workflow or reusable knowledge in an opaque asset |
| Provider-specific UI or presentation metadata | Provider-owned metadata such as `agents/openai.yaml` | Optional interface behavior owned by the consuming provider | Adding provider fields to Renma core metadata |
| Dynamically select a Lens, load or inject Context, assemble prompts, execute tools, or apply the workflow | External agent or runtime | Depends on the live request or execution environment | Encoding runtime behavior in a Lens or claiming Renma performs it |
| “Act as a senior QA engineer” with no concrete criteria | Usually keep as brief local framing; create no asset solely for it | Persona or tone alone has no reusable interpretation contract | Treating generic role wording as a Context Lens |

The canonical defaults and their Agent Skills/Renma provenance are in the
[Quality Profile](quality-profile.md).

## New Skill Workflow

Use these externally observable dependencies for a new Skill; they do not
prescribe the consuming LLM's internal reasoning sequence:

```text
renma guide skill
  -> investigate applicable evidence and clarify human truth only if needed
  -> establish the smallest intended asset structure as a gate requirement
  -> pass the creation gate when every requirement is established and no blocker remains
  -> external LLM writes renma.skill-authoring-handoff.v1
  -> renma scaffold skill <agreed-path> --handoff <handoff.json>
  -> scaffold or reuse justified Context Assets
  -> complete the focused workflow
  -> renma scan . --fail-on high
  -> classify findings and inspect relevant evidence
  -> re-enter the creation gate if asset boundaries may change
  -> apply uniquely supported repairs and rerun
  -> human review
```

### 1. Establish the authoring contract

Before generating files, run:

```bash
renma guide skill
```

The complete JSON reference uses
`schemaVersion: "renma.skill-authoring-guide.v2"`. Consumers must branch on
`schemaVersion`; v2 does not preserve v1 assumptions that phases are ordered,
clarification is mandatory, question batches are fixed, or the last phase owns
human-review semantics. Human review is explicit in
`interaction.humanReviewRules`. The compact prompt includes a conditional
pointer to the complete JSON `externalTraversalRules` when the finished Skill
may recursively follow references discovered inside an external source.
Disposition and platform-handoff reference tables remain in JSON; the default
prompt states their required outcomes in the questioning, gate, repair, and
handoff sections without repeating those tables.

Use its deterministic prompt to define:

- the recurring task or decision;
- the trigger and nearby cases that should not use the Skill;
- required inputs and evidence;
- the ordered workflow and decision points;
- safety and repository constraints; and
- the output and completion criteria;
- every independently maintained Context dependency; and
- the smallest set of files with distinct responsibilities.

The consuming LLM develops this understanding progressively; the user does not
need to supply every section, field, edge case, or file up front. Define the
expected output and completion criteria early. Trigger wording and examples can
be refined after the creation gate unless a usage boundary is itself blocking.
Match implementation freedom to fragility: use prose when judgment is central,
a parameterized script when a stable operation needs flexible inputs, and a
fixed script when ordering or exact behavior is safety-critical.

Do not guess missing owners, policies, dependencies, product behavior, domain
rules, or source-of-truth documents. Record gaps for a human to resolve.

“Improve with Renma” does not mean adding metadata, files, scripts, copied
specifications, or every recommendation from a generic Skill system. Do not
create a generic Skill first and enrich it afterward with Renma-like metadata.
Construct the Skill and related assets directly within the Renma authoring
contract.

Apply the truth-source and access distinctions above whenever a Skill depends
on an external authoritative URL. The user-designated source-of-truth role
normally justifies a concise Context Asset even if no other Skill reuses it,
but source-dependent domain facts stay Unresolved until content is successfully
consulted or supplied. Record what the source governs, its URL, when it must be
consulted, and necessary scope or fallback behavior. Do not copy the full
external document unless an intentional reviewed snapshot is required. Declare
the Context as required when the workflow cannot validly complete without it;
use optional Context only when it truly can.

The source-of-truth role supplies the independent authority and maintenance
boundary; correctness dependency by itself would not. Task-specific knowledge
with no independent maintenance or governance reason stays in `SKILL.md` or
justified Skill-local support. After a Context Asset is independently justified,
correctness dependency determines `requires-context` versus `optional-context`.

Separately decide whether the finished Skill reads the URL during execution or
expects source content from the user or another approved process. A Markdown
URL does not grant runtime network permission. When runtime access is intended,
review the supported effective policy for allowed data, network allowance,
approved destinations, external upload, secrets, and human approval.

Do not manufacture permissive policy values. Ensure the Skill body, Context
instructions, and effective policy agree, and preserve unresolved access intent
for human review.

Scaffold generation performs no network operations. The finished Skill may
access the reviewed external source only when its authored workflow and the
effective security policy permit that access.

Do not create a Context Lens merely because the Context exists. Do not create a
script merely because the output is JSON, YAML, XML, or another structured
format. Add a script only when exact repeated behavior, material safety,
safety-critical ordering, meaningful tests, or an explicit executable request
justifies it. Add examples only when they resolve real ambiguity. Every file
must have a distinct, reviewable responsibility.

Write only information that changes execution, interpretation, validation, or
review. State each requirement once in the asset that owns it, preserve required
inputs, exceptions, failure behavior, safety constraints, completion criteria,
and unresolved uncertainty, and remove generic introductions, conclusions, and
boilerplate. Concise does not mean omitting important decisions.

### 2. Record the structured authoring handoff

After every creation-gate requirement is established, including the smallest
justified asset structure, and no Blocking authoring decision remains, the
external LLM or coding agent records the current decisions in
`renma.skill-authoring-handoff.v1`. The guide's JSON output exposes construction
rules and a template; the default prompt gives a concise version. Renma does
not create or fill the exchange file.

The handoff keeps these layers separate:

- Confirmed, Proposed, and Unresolved current understanding;
- Blocking, Reversible default, and Deferred progression;
- the recurring task, expected result, required inputs, completion criteria,
  failure behavior, and positive/negative usage boundaries;
- the canonical Skill path, identity, owner, tags, local resources, and
  required/optional Context and Lens relationships;
- planned supporting Context or Context Lens assets and each independent
  maintenance or governance justification; and
- declared source-authority status, security decisions, and runtime ask,
  report, defer, or stop behavior.

The handoff is intentionally not a complete Skill AST, a second metadata
system, a conversation transcript, finished Markdown, or a complete
implementation plan. Proposed reversible defaults and Unresolved Deferred
items may remain. Only `progression.blocking` must be empty.

This is caller-declared authoring evidence. Renma validates its bounded shape
and internal consistency but does not prove that the clarification happened,
the human reviewed every decision, the blocker set is complete, an external
source is authoritative or was consulted, or the domain facts are true. The
source states `provided`, `consulted`, and `designated_unconsulted` preserve the
difference between supplied or reviewed content and authority designation.

A structurally valid handoff does not prove that its supporting evidence remains
applicable. When current applicability cannot be established, recheck only the
evidence supporting material handoff decisions that scaffolding or semantic
authoring will rely on. Re-enter the creation gate when the result changes the
Skill contract, source authority, security decisions, runtime-unknown handling,
or asset boundaries.

### 3. Generate one repository-compatible starting point

Run the Renma generator once:

```bash
renma scaffold skill skills/testing/spec-review/SKILL.md \
  --handoff /tmp/spec-review-handoff.json
```

The target must be a canonical `SKILL.md` under `skills/**` or
`.agents/skills/**` and must match `assetGraph.skill.path` after safe
normalization. File mode refuses to overwrite an existing file. The handoff
must supply a non-empty explicit owner other than `unowned`. The output is a
deterministic starting point, not a finished Skill.

The handoff is optional: existing direct scaffolding with `--owner` and
optional `--id`, `--title`, `--tags`, and `--resources` remains supported.
When `--handoff` is present, those five structural options are forbidden so
there is no dual authority.

Use `--resources` only for directories with a current, justified responsibility.
It creates requested empty directories and no placeholder files. In the
completed Skill, state when each reference should be read, each script should be
run, and each asset should be used.

Do not run two independent generators against the same target file. Some tools
that provide platform-native Skill authoring guidance create files themselves,
so choose one of these safe approaches after the creation gate passes:

1. Run `renma scaffold skill`, then ask the platform tool to review and refine
   that existing file.
2. Ask the platform tool to use `renma scaffold skill` as the starting point
   instead of independently generating the same target.

Use Renma as the one generator, then use platform-native Skill authoring
guidance only to refine semantics inside the established asset and metadata
boundaries. It must work from the Renma scaffold and agreed structure, must not
add metadata or assets outside that structure, and must not create a second
target.

`--format prompt` prints the deterministic scaffold and constraints without
writing the file. `--format json` prints the existing structured bundle. These
modes do not reserve or create the target path.

Before file mode calls `mkdir` or `writeFile`, Renma parses the handoff and
validates its schema version, zero declared blockers, target agreement,
canonical identity and Agent Skills name, Context/Lens set uniqueness and
required/optional separation, supporting graph consistency, Context placement
justification, and supported local resource kinds. Any failure exits `2` and
creates no Skill file or resource directories. A planned supporting asset is
never automatically created; one scaffold invocation owns one explicit target
file side effect.

For a valid handoff, file mode writes exact `id`, `title`, `owner`, `tags`,
`resources`, `requiresContext`, `optionalContext`, `requiresLens`, and
`optionalLens` structural values. It does not write temporary authoring-state
headings or synthesize polished prose from the Skill contract. Prompt mode
passes the decision state, contract, graph, sources, security decisions, and
runtime-unknown handling to the consuming LLM. JSON mode adds the handoff as a
structured projection rather than flattening it into prose.

The published [Skill Authoring Handoff v1 JSON
Schema](schemas/skill-authoring-handoff-v1.schema.json) documents the bounded
exchange shape. Semantic cross-field validation remains in Renma's TypeScript
implementation.

### 4. Review and complete the scaffold

Renma treats its own exact generated Skill and Context starter strings as
unfinished scaffold residue. Each remaining marker emits the High
`QUAL-RENMA-SCAFFOLD-PLACEHOLDER` finding with evidence on the exact
frontmatter description or body line, so `renma scan . --fail-on high
--strict` blocks an untouched or partially edited scaffold. The boundary is
deliberately narrow: this rule does not flag general words such as
“placeholder,” “describe,” “input,” or “output,” and clearing it does not prove
semantic completeness.

Within the Renma boundaries, use platform-native Skill authoring guidance to
complete:

- `description`, including positive and negative trigger boundaries;
- required inputs and preflight evidence;
- instructions, decisions, and workflow;
- constraints and security behavior;
- completion criteria and validation; and
- the Skill semantics that rely on intended Renma metadata and Context
  relationships without changing those boundaries independently.

If refinement or real usage reveals a justified boundary change, stop and
return that need to the creation-gate contract as Proposed or Unresolved.
Inspect evidence and re-enter the creation gate before changing the agreed
structure.

Preserve the repository's intended behavior. Use a Context Asset when knowledge
is reusable across Skills, has independent ownership or lifecycle, is maintained
separately, is an authoritative source of truth, or has another explicit reason
for independent review and governance. Correctness importance alone is not
sufficient; keep task-specific knowledge in the Skill or justified local
support.

Preserve Agent Skills optional fields, unknown `metadata.renma.*` values, and
other vendors' string metadata. Provider-specific `agents/openai.yaml` is
permitted but is not required by Renma core.

Verify new or changed scripts and existing executable behavior affected by the
change with relevant tests or observable checks. Do not execute unrelated or
unchanged scripts solely because they exist. Report unavailable required
validation and its impact; do not claim an unrun check passed.

Use external runtime evaluation for complex Skill behavior when the change,
unresolved execution evidence, or repository requirements call for it. Use
representative raw user prompts, outputs, and execution logs without leaking
expected answers, diagnoses, or intended fixes to evaluation agents. Renma
remains deterministic; runtime evaluation stays external.

### 4. Validate, fix, and rerun

After authoring or changes, run the relevant validation and all
repository-required checks for the current change and stage. The usual release
gate is:

```bash
renma scan . --fail-on high
```

Review every relevant diagnostic and use the normative post-validation rules
above. Apply a repair only when evidence uniquely determines it, investigate
repeated-context or boundary evidence before semantic change, ask the human
when truth is missing, or explain why no change is justified. Follow
Diagnostics v2 constraints and verification steps, rerun after repairs, and do
not weaken security policy or add a suppression merely to pass.

After relevant checks pass, repeat or broaden validation only for further
changes, failed checks, or unresolved concerns. Reuse existing evidence only
while it remains applicable to the current content, environment, and required
scope. Required CI and release checks still apply.

Use other deterministic views only when they answer a specific structural or
governance question; do not run every command as ceremony:

```bash
renma inspect skills/testing/spec-review/SKILL.md
renma catalog . --format markdown
renma graph . --focus skill.testing.spec-review --format mermaid
renma ownership . --format markdown
renma readiness . --format markdown
```

Inspect every created or reused asset and relationship. When optional Context,
Lens, source, script, or security structures exist, perform the additional
verification appropriate to them. The final step is human review of semantic
correctness and material non-obvious decisions, including their governing
evidence or authority and any evidence-backed consequence of changing them.
When a consequence is not established, explicitly label the potential impact
Proposed or Unresolved and state remaining uncertainty. Clean deterministic
output does not prove semantic correctness, reviewer understanding, or approval.

### Conditional external reference traversal rules

Named external source reading means the finished Skill reads one or more
explicitly named sources. Recursive external source traversal means it follows
references discovered inside a source and may discover further sources. Named
reading alone does not require a recursive traversal contract.

When recursion is possible, persist an explicit contract in the Skill body or
justified Skill-local support owned by that Skill. Define:

- the approved source boundary and relevance criteria;
- the strongest available logical-source identity and a visited-source
  registry;
- repeated-source, cycle, ambiguous-identity, and inaccessible-source behavior;
- a termination condition plus explicit page-count and depth safety caps; and
- unresolved-reference, limit-reached, remaining-scope, and provenance
  reporting.

Prefer identity in this order: provider-specific immutable resource ID,
provider-returned canonical URL, normalized URL without fragments and tracking
parameters, then exact URL. The authored Skill and its permitted runtime own
this behavior; Renma does not compute identities, fetch pages, open URLs,
normalize external sources, or crawl reference graphs.

Process each logical source once per traversal when possible. If another
reference reaches an already visited source, retain the additional path as
provenance without reopening or reprocessing it by default. A justified
incomplete prior read, content change, or precise evidence check may require a
reread; do not encode an absolute never-reread rule.

Follow only relevant in-boundary references and stop when no new relevant
source remains. Safety caps are visible Reversible defaults, not silent claims
of completeness. Renma defines no universal page or depth value. A human should
review limits that materially affect completeness or safety.

On a cycle, ambiguous identity, access failure, unresolved reference, or safety
limit, stop and report the unresolved boundary and remaining scope rather than
continuing or guessing. Traversal order defines no authority or override;
report contradictory sources with evidence instead of resolving them by visit
order.

Do not create hidden runtime prompt packages, live repository visited
registries, or metadata solely for traversal state. Recursive traversal safety
is conditional normative authoring guidance, not repository composition or a
new illustration category.

### How to use non-normative illustrations

Renma does not classify a Skill request by matching it to a built-in example.
The consuming LLM applies the normative protocol to the current request and
evidence. Illustrations may clarify individual decisions, but may be ignored
and must not be copied as templates.

Do not copy an illustration's workflow, asset structure, questions, completion
criteria, security policy, unresolved items, or domain assumptions. Reuse a
decision pattern only when its conditions are independently present. Multiple
illustrations may inform different decisions, and none needs to match the whole
Skill. The normative protocol and current evidence always control.

### Illustration: Minimal blocking clarification

For “I want to create a Skill with `renma guide skill`,” no asset structure is
yet justified. Confirm only the request to create a Skill, leave the recurring
task and expected result unresolved, and ask for that smallest Blocking
information without demanding a complete plan. This is an optional decision
pattern, not a required first-turn template.

### Illustration: Report-first progression with runtime findings

For “Create a Skill that reviews whether repository documentation still matches
the implementation,” the recurring task is review and the intended output may
be an evidence-backed report rather than a patch. Only the recurring task is
Confirmed by that request. Using current repository implementation and tests as
evidence when applicable and unambiguous, producing a report without automatic
patching, and starting with one Skill are safe Proposed reversible defaults. No
Context Asset, Context Lens, script, support file, or external source is
required by default.

With that one-Skill structure and the other gate requirements established, the
initial creation gate can pass with no blockers and no mandatory questions:
compare the named artifacts, report evidence, mismatches, risks, and unresolved
questions, do not decide intended behavior without authority, and do not modify
documentation or implementation automatically. Future repository mismatches,
missing tests, unresolved authority, and other reportable findings are runtime
task unknowns. Their number does not imply a Skill split, and the author should
not be asked to resolve them in advance. Authority or completion policy becomes
Blocking only if later evidence shows that the Skill must adjudicate mismatches
rather than safely report them.

### Illustration: Source-backed authority and access boundary

Example Product API is a fictional external API used only to illustrate
authoritative-source handling. It is not a Renma concept or a real product.

This fictional API example illustrates one source-backed workflow. Its API,
schema, timeout, retry, and response-behavior details are example-specific and
are not default requirements for unrelated Skills.

General authoring lessons are the separation of source designation from source
content, authoring-time from runtime access, authoring blockers from runtime
findings, and reviewed durable decisions from temporary conversation state.
Example-specific domain details include JSON construction, API fields,
operation behavior, and source-unavailability handling.

For this request:

```text
Create a Skill that builds a JSON request body for the fictional Example Product
API.
The Example Product API documentation URL is the source of truth.
Improve the Skill with Renma.
```

the consuming LLM first reports:

```text
Current understanding

Confirmed
- The workflow builds a JSON request body for the fictional Example Product API.
- The user designates the Example Product API documentation URL as the intended
  authoritative external source.
- The request expresses authoring-time intent to consult that URL, subject to
  the current tools and authoring environment permitting access.

Proposed
- One focused Skill.
- One concise source-of-truth Context Asset.
- The Context is likely required.
- No script or Context Lens by default.

Unresolved
- Whether the finished Skill accesses the URL at execution time.
- What happens when the source cannot be accessed.
- Whether the Example Product API Context is required or optional for correct
  execution.
- The Context owner, unless repository evidence resolves it.
- Whether source-specific instructions, transformations, examples, or validation
  behavior must be authored now.
- Whether authoring-time consultation is needed for a source-specific authoring
  decision.

Epistemically unresolved runtime task knowledge handled by the finished Skill
- The current Example Product API schema.
- The current documented fields and constraints.
- Operation-specific behavior read from the authoritative source.

Current progression

Blocking decisions: 5
- Finished-Skill runtime source-access intent.
- Safe fallback behavior when the source is unavailable.
- Whether the Example Product API Context is required or optional for correct
  execution.
- The Context owner when applicable repository evidence does not supply one.
- Any source-specific instructions, transformations, examples, or validation
  behavior that must be embedded during authoring.
- Asking now: 3 highest-impact questions below.

Queued from the complete blocker list above (not additional): 3, 4.

Proposed reversible defaults
- No script by default.
- No Context Lens by default.

Deferred
- Authoring-time source consultation when no source-specific authoring decision
  depends on it.
- Final wording and tags.
- Additional examples unless real ambiguity emerges.

Questions
1. Should the finished Skill access the URL during execution, or should its
   runtime consumer provide the documentation through another approved process?
2. When the source is unavailable, should the Skill stop or request approved
   supplied content rather than infer the JSON schema?
3. Must the Skill embed any source-specific instructions, transformations,
   examples, or validation behavior now, or can it consult the current source
   during execution?
```

This illustration uses a three-question batch while retaining two dependent
blockers. That is one valid interaction strategy, not a required batch size or
presentation format. The reversible defaults remain Proposed.

Current schema, fields, constraints, and operation-specific behavior are
epistemically unresolved, source-dependent runtime knowledge. They are listed
only in the runtime task-unknown section rather than repeated in generic
Unresolved. The safe contract is to consult the declared Context, use only
documented fields, request missing task inputs, report ambiguity, and stop or
request approved supplied content when the source is unavailable. They become
authoring blockers only when source-specific instructions, transformations,
embedded examples, or validation behavior must be defined in the Skill. Do not
require the user to paste the full specification when those current facts can
safely remain runtime-scoped. Authoring-time consultation remains useful and may
be required for source-specific authoring; it is not universally a creation-gate
blocker.

The LLM does not confirm source-dependent facts from memory, use future Skill
metadata as authoring-time permission, or hard-code a fictional approved domain
or permissive security metadata.

As part of the creation-gate state, the smallest proposed Renma asset structure
is:

```text
skills/build-example-product-json/SKILL.md
  -> requires
contexts/example-product-api.md
```

The external source reference is separate from that structure:

```text
contexts/example-product-api.md contains the reviewed Example Product API
documentation URL
```

The URL is body content, not a Renma asset node or graph edge. Decide whether
the finished Skill fetches it at runtime or expects approved supplied content.
If it fetches at runtime, review the supported allowed-data, network,
destination, external-upload, secrets, and approval policy; do not hardcode an
unreviewed host or infer permissive values merely because the URL is public.
The Renma graph validates only the Skill-to-Context relationship. Neither a
clean scan nor a valid graph proves that the URL is authoritative or accessible
at runtime.

The Skill determines the requested operation, consults the declared Context,
collects missing required inputs, constructs only documented JSON fields,
reports assumptions or unresolved ambiguity, and defines output and completion
criteria. The Context identifies the governed specification and authoritative
URL, says when it must be consulted and what happens when unavailable, and does
not copy the full specification.

Do not create a JSON-generation script, second explanatory guide, Context Lens,
duplicated URL declarations, speculative metadata, or copied API documentation
by default.

## Existing Skill Workflow

Use this sequence for ordinary maintenance of an existing Skill:

```text
renma scan . --fail-on high
  -> inspect relevant diagnostics and repository evidence
  -> use suggest-metadata only for metadata or migration work
  -> prepare the smallest intended patch
  -> renma scan . --fail-on high
  -> fix relevant diagnostics
  -> rerun validation
  -> human review
```

Use `renma guide skill` only when the work intentionally reconsiders Skill and
Context boundaries, file or resource placement, source representation, scripts
or other support, or the asset graph. Platform-native authoring guidance may
refine Skill semantics within the resulting Renma boundaries;
`suggest-metadata` does not perform that review.

### 1. Scan and inspect repository evidence

```bash
renma scan . --fail-on high
renma inspect skills/testing/spec-review/SKILL.md
```

`scan` is the general deterministic starting point for an existing Skill. Use
`inspect`, `catalog`, `graph`, `ownership`, or `readiness` when one of those
commands answers a specific evidence question. Renma reports structural and
governance evidence; it does not perform the whole-Skill semantic review.

### 2. Generate a metadata or migration suggestion when needed

```bash
renma suggest-metadata skills/testing/spec-review/SKILL.md
```

Optionally provide an owner only when a human has explicitly confirmed it:

```bash
renma suggest-metadata skills/testing/spec-review/SKILL.md \
  --owner qa-platform \
  --format json
```

`suggest-metadata` reads one target and prints a deterministic prompt or JSON
payload to stdout. It does not edit, rename, or move the file. Its supported
responsibilities are:

- compact canonical metadata suggestions;
- explicit owner retrofit and one-way migration of recognized pre-0.16
  governance and security metadata;
- pre-0.16 to canonical Agent Skills migration candidates;
- conflict and unsafe-evidence detection; and
- validation of the rendered candidate.

It does not rewrite the body, infer ownership, choose between conflicting
semantic values, infer missing security policy, or propose reverse migration
for a canonical Skill. An owner candidate requires explicit human-provided
evidence. Security policy remains intentionally authored and deterministically
validated.

Do not route an already canonical Skill through `suggest-metadata` as ceremony.
Use it only for a metadata retrofit, explicit owner retrofit, recognized
pre-0.16 one-way migration, or blocked migration review.

### Evidence-first LLM preflight

When an LLM is asked to improve one existing Skill:

1. Run `renma scan . --fail-on high --format json`.
2. Run `renma inspect <SKILL.md> --format json`.
3. Inspect relevant local resources and referenced Context Assets.
4. Use `renma suggest-metadata` only when metadata retrofit or migration
   evidence exists.
5. When `suggest-metadata` reports `decisionStatus: "no-change-recommended"`
   with `suggestedMode: "no-proposal"`, do not manufacture a metadata or
   migration patch. Continue any separately requested Skill-body improvement;
   stop only when no other intended work remains.
6. Prepare the smallest intended patch.
7. After changes, rerun `renma scan . --fail-on high --format json` and the
   repository-required checks for the change and stage.
8. Report unresolved human decisions.

For a classification-only question, `renma inspect <target> --format json` may
be the first command. `scan` remains the normal repository-level starting
point.

### 3. Review before applying

Treat the output as a candidate. Compare it with the source and apply only the
intended metadata, path migration, or migration changes. Preserve the Markdown
body and unknown vendor metadata unless a separately reviewed semantic change
requires otherwise.

If migration is blocked:

1. Review the reported conflicts or invalid evidence.
2. Confirm the Skill's intent using platform-native Skill authoring guidance
   within the established Renma boundaries.
3. Do not apply a candidate while Renma cannot generate it safely.
4. Correct the source evidence.
5. Rerun `renma suggest-metadata <SKILL.md>`.
6. After intended corrections, run `renma scan . --fail-on high` and repeat the
   fix-and-rerun loop.

Renma never chooses a semantic winner automatically. The detailed one-way
migration and blocking contract is in
[Agent Skills Compatibility and Migration](agent-skills-compatibility.md).

## Canonical Skill Metadata

Agent Skills owns the standard Skill identity and body. Renma fields are flat,
string-valued `metadata.renma.*` entries. JSON-array strings encode lists:

```yaml
---
name: spec-review
description: Review specifications for ambiguity and missing boundaries. Use when requirements need evidence-backed review before implementation.
metadata:
  renma.id: skill.testing.spec-review
  renma.title: Spec Review
  renma.owner: qa-platform
  renma.status: stable
  renma.tags: '["testing","spec-review"]'
  renma.requires-context: '["context.testing.boundary-value-analysis"]'
  renma.optional-context: '[]'
---
```

Do not use a nested `metadata.renma` mapping, native YAML booleans for canonical
security fields, or comma-separated canonical lists. The User Manual's
[Authoritative Metadata Reference](user-manual.md#authoritative-metadata-reference)
owns the complete field inventory, Skill/non-Skill mappings, value formats,
applicability, and compatibility classification. The
[Agent Skills compatibility guide](agent-skills-compatibility.md) owns canonical
serialization and migration details, while the
[Security Policy guide](security-policy.md) owns effective-policy semantics and
security-specific examples.

Start from the installed Renma scaffold and use only fields defined by that
Renma version or the supported Agent Skills format. Do not infer future fields,
add every optional field, or invent `source_of_truth`, `trust_level`,
`refresh_policy`, `product`, or similar metadata. Represent external authority
through the supported Context relationship plus a normal Markdown link. Keep
metadata compact and put detailed instructions in the body. Preserve unknown
existing vendor metadata during review, but do not manufacture provider-specific
metadata without a requirement.

Treat the Agent Skill `description` as routing metadata, not only as a summary.
Use explicit selection language such as `Use when ...` when the activation
boundary fits there; Renma also accepts clear routing guidance in the Skill
body, including `When to use`, `Routing`, and trigger-oriented sections. A
description that only says what output the Skill produces does not establish
when or why it should be selected. Negative routing remains a separate evidence
dimension: `Do not use ...` does not replace positive selection guidance.

The canonical description is a discovery and routing surface, not an execution
surface. Describe capabilities and selection boundaries semantically. Do not
place literal executable or destructive commands, secret-disclosure requests,
safeguard-bypass instructions, credentials, or other high-risk operational
payloads there, even as quoted request examples. Route a Skill as reviewing
destructive-cleanup, attempted secret-disclosure, or approval-bypass requests
rather than embedding the exact requested operation. If exact dangerous
evidence is necessary, put it in the Skill body under a clearly non-operational
unsafe-example or review-evidence section. The scaffold, `renma guide skill`,
and `QUAL-SKILL-DESCRIPTION-HIGH-RISK-LITERAL` diagnostic reinforce this
boundary; the diagnostic recommends review and does not rewrite owner-authored
prose.

Keep recognizable result-checking guidance in the Markdown body. A concise
`Verification`, `Validation`, or `Testing` section is sufficient, and inline
instructions using forms such as `verify`, `validate`, or `expected result` are
also supported. A verification-related word in frontmatter alone does not
establish workflow verification. Nor does a test-related noun such as `test
fixture` or an instruction not to test, verify, or validate. These advisories
are deterministic authoring checks; they do not evaluate whether a stated test
is correct or exhaustive.

For a temporary lifecycle stop, preserve the asset and set
`renma.status: suspended` together with a reviewed, non-blank
`renma.status-reason` and real `YYYY-MM-DD` `renma.status-changed-at`. Non-Skill
assets use `status`, `status_reason`, and `status_changed_at` at the top level.
Suspension is static governance: it removes the asset from active dependency,
composition, publication, and routing use while keeping inventory evidence.
Required active declarations to the asset block; optional declarations warn.
Restoration requires another reviewed status/reason/date change. Renma does not
schedule, expire, or restore lifecycle state automatically, and
`last_reviewed_at` remains the separate freshness-review date. See
[Context Lifecycle Diagnostics](context-lifecycle-diagnostics.md) for the full
dependency and evidence policy.

For an explicit withdrawal of trust or authorization because of a known
problem, use `renma.status: revoked` with the same required canonical reason
and real transition-date fields. Revocation is stronger than suspension, is
not deprecation or archival, and does not require a replacement. Renma reports
active direct dependents for review but does not propagate the revoked status
or choose a remediation.

## Context Asset And Context Lens Authoring

Create a Context Asset when knowledge is reusable across Skills, has independent
ownership or lifecycle, is maintained separately, is an authoritative source
of truth, or has another explicit reason for independent review and governance.
Source-of-truth status alone is sufficient; importance to one Skill's
correctness is not. Cross-Skill reuse is not mandatory:

```bash
renma scaffold context contexts/testing/boundary-value-analysis.md \
  --owner qa-platform
```

A Context Asset should contain durable, source-backed domain knowledge,
testing heuristics, tool constraints, platform facts, reviewed policy, or a
concise external source-of-truth contract. Keep task-specific prompt
instructions and runtime selection rules out of Context.

Create a Context Lens when one purpose needs a focused interpretation of one or
more Context Assets:

```bash
renma scaffold context_lens \
  lenses/testing/spec-review-boundary-values.md \
  --owner qa-platform
```

The repository can represent both:

```text
Skill -> Context Lens -> Context Asset
Skill -> Context Asset
```

These metadata relationships are static governance evidence. Renma does not
select, load, or inject Context at runtime.

Use this placement sequence before creating an asset:

1. Is this the task, workflow, or completion contract? Put it in the Skill.
2. Is this durable, source-backed knowledge with reuse, independent ownership or
   lifecycle, separate maintenance, source-of-truth status, or another explicit
   independent governance boundary? Create or reuse a Context Asset. Any one of
   those independent reasons is enough; correctness importance alone is not.
   After Context is independently justified, use correctness dependency to
   select a required versus optional relationship.
3. Does declared Context need a reusable purpose-specific interpretation?
   Create a Context Lens. Do not create a Lens when there is no Context Asset to
   interpret.
4. Is this a Skill-local overlay or execution variant? Use a Profile only when
   the current Profile semantics fit.
5. Is this supporting detail used by only one Skill? Use a Reference.
6. Is this a local fixture or demonstration? Use an Example.
7. Is this only generic persona or tone framing? Usually keep it local and do
   not create an asset solely for the persona.

A Skill can reference a Context Asset directly when no separate interpretation
layer adds value. A Lens is justified only when it adds meaningful, reusable
structure to how declared Context is read for a purpose. See the
[Context Lens guide](context-lens.md) for field semantics, persona guidance,
examples, and a zero-context classification self-check.

Context and Context Lens scaffolds keep their top-level Renma metadata syntax;
the Agent Skills `metadata.renma.*` serialization boundary applies to Skills.

## Context Asset Discovery Boundary

The classification precedence is: explicit Skill entrypoint, explicit local
support inside a recognized Skill, recognized top-level asset root,
repository-level support or configuration, compatible generic nested rules,
then unknown. This makes the repository root authoritative:

```text
contexts/foo/references/policy.md
  -> independent Context Asset

skills/foo/references/policy.md
  -> Skill-local Reference

references/policy.md
  -> outside the Context root

tools/helper.mjs
  -> repository implementation

skills/foo/tools/helper.mjs
  -> not canonical Skill-local support
```

Use `contexts/**` for independent Context; move any historical `context/**`
content there after updating its references. Nested `references/`, `examples/`,
`profiles/`, `scripts/`, or `assets/` does not override that Context root. The same names are Skill-local
only inside `skills/**` or `.agents/skills/**`, where they establish a structural
parent candidate. Local metadata overrides remain supported where valid, but
are not required. `tools/**` is shared repository implementation, and a Skill
uses `scripts/`, not `tools/`, for canonical local executable support.

Do not author or scaffold a Skill entrypoint below one of those reserved
support segments. A Skill-looking filename there remains support content, even
at deeper nesting such as `references/vendor/SKILL.md`. Ordinary non-reserved
domain nesting remains valid. See the canonical
[entrypoint path contract](agent-skills-compatibility.md#entrypoint-paths).

The Skill-local path rule establishes only a structural parent candidate. The
catalog must resolve exactly one parent entrypoint before Renma reports
inherited governance. A missing or ambiguous parent remains structurally
Skill-local but unowned or unresolved; `suggest-metadata` blocks instead of
adding independent metadata automatically. Existing explicit local owner or
policy metadata is preserved and is not described as inherited.

Humans decide whether knowledge needs independent ownership, lifecycle, reuse,
and source-of-truth status. Renma classifies the resulting placement but never
promotes or moves content automatically. A `no-proposal` result is successful:
preserve the file and stop unless a separate intentional change is supported.

For current guidance on deriving several focused, bounded workflows from a broad
existing Skill—including focused `inspect`, graph, Context reuse, and Appium
examples—see [Advanced Skill Authoring](advanced-skill-authoring.md). That guide
keeps focused-workflow authoring separate from static Skill Discovery.
Repository and local support discovery, `renma.continues-with`, explicit
`renma.published-entrypoint`, adoption states, and the discovery graph view are
implemented together with reachability, coverage evaluation, route-cycle review,
and `skill-index`. See the
[Skill Discovery Graph and Index contract](skill-discovery.md) for the complete
static boundary.

## Optional Codex Example

Codex may activate `skill-creator` when asked to create a Skill. It is one
example of platform-native Skill authoring guidance, not a Renma dependency or
the authority for Renma metadata, Context placement, repository asset
boundaries, file count, source-of-truth representation, or scripts and support
files. The expected sequence is:

```text
run renma guide skill
  -> evaluate the Renma creation gate and clarify only if needed
  -> establish the smallest justified asset structure
  -> pass the creation gate
  -> write renma.skill-authoring-handoff.v1
  -> create the Renma scaffold with --handoff
  -> use skill-creator only for semantic refinement
```

If `skill-creator` is available or activates automatically, do not let it
independently create files before the Renma creation gate passes.
If semantic refinement reveals a justified asset-boundary change,
`skill-creator` must return that need to the Renma creation-gate contract rather
than silently changing the repository structure.

After passing the gate, a safe request is:

```text
First run `renma guide skill`, investigate applicable evidence, evaluate the
creation gate, and clarify only unresolved Blocking authoring decisions that
still require human truth. Establish the smallest justified asset structure as
a creation-gate requirement, and declare the gate passed only after every
requirement is established and no Blocking authoring decision remains. Create
the caller-declared `renma.skill-authoring-handoff.v1` exchange artifact and
create `skills/testing/spec-review/SKILL.md` with `renma scaffold skill
skills/testing/spec-review/SKILL.md --handoff <handoff.json>`. Then use
skill-creator only to refine its trigger description, ordered instructions,
usage boundaries, required inputs, constraints, completion criteria, and
ambiguity-resolving examples. Preserve its Renma metadata, Context placement,
file boundaries, and repository behavior. Do not independently generate a
second target file or invent owners, policy, dependencies, domain rules, or
source-of-truth claims. If refinement reveals that the agreed asset boundary
must change, stop, report it as Proposed or Unresolved, and re-enter the Renma
creation gate before changing structure. After the reviewed edits, run
`renma scan . --fail-on high`, fix relevant diagnostics, and rerun the scan.
```

Do not ask `skill-creator` to design a generic Skill first for later Renma
enrichment. The Renma scaffold and graph are the starting point.

## Review Checklist

Before human approval, confirm that:

- the description says when the Skill should and should not be selected;
- instructions, constraints, and completion criteria are explicit;
- owners, policies, dependencies, and domain claims are evidence-backed;
- reusable or independently maintained source-of-truth knowledge has an
  appropriate Context boundary;
- material non-obvious decisions identify their governing evidence or authority
  and any evidence-backed consequence of changing them, or explicitly label an
  unestablished potential impact Proposed or Unresolved;
- generated or suggested changes were reviewed rather than applied blindly;
- generated or derived artifacts establish only bounded producer-scoped
  observations unless an applicable truth source establishes broader claims or
  governing authority;
- blocked migration evidence was resolved instead of bypassed;
- `renma scan . --fail-on high` was rerun after fixes; and
- no policy weakening or new suppression was used merely to pass validation.

The operating principle remains:

```text
LLM investigates and proposes. Renma validates deterministic structure and repository evidence. Human reviews and approves.
```