Refresh skill authoring guidance: progressive disclosure, proactive use, portability, and scoped authorization

[tkstang]

Problem

create-agnostic-skill has a sound authoring foundation, but its current guidance mixes portable skill requirements, editorial preferences, provider-specific claims, OAT repository machinery, and approval/delegation policy. Applying it literally can produce unnecessary approval pauses and ceremony, teach stale provider behavior, and mistake template completeness for a working skill.

This is a focused baseline/documentation refresh proposal, checked against main at 1bef28fa1fb95e1473872ff9a511a6b42fa37889 on 2026-09-07. The skill is still version 1.4.1 there. It does not propose weakening authorization boundaries or replacing the authoring workflow.

Current surfaces

• create-agnostic-skill/SKILL.md
• Annotated skill template
• Canonical skills guide, plus its bundled references/docs/skills-guide.md view

Keep the core principles

Retain trigger-focused descriptions, progressive disclosure, imperative instructions, explicit inputs/defaults/outcomes, meaningful examples, resource containment, capability-based provider wording, source ownership, and honest fallback/verification reporting.

Proposed revisions

1. Distinguish requirements, recommendations, and repository policy

The main skill says to adjust structure by complexity, but also makes particular Step naming and example labels key requirements. Keep examples of explicit invocation and natural language where useful, while allowing a small helper to have a compact execution/result shape. Exact heading capitalization, fixed section lists, success-criteria headings, and [N/N] markers should be useful defaults rather than universal conformance gates.

Keep concise progress updates for sustained work. Do not require progress ceremony for a one-step lookup.

2. Apply progressive disclosure to the authoring skill itself

Keep its durable authoring workflow in SKILL.md. Move the full starter template into an asset, provider compatibility details into a dated reference, detailed delegation patterns into a conditional reference, and OAT-specific distribution recipes into an OAT reference. Link directly to each supporting file with a loading condition. Avoid repeating the same guidance in the main body, template, and guide.

Do not require empty references/ directories or mechanically split material every invocation needs. Keep essential authorization/privacy constraints visible in the main body; extract conditional or supplementary detail.

3. Correct budget terminology and scope

The current Step 2 says <5k words, while Best Practices says ~5,000 tokens. Use tokens consistently. The current specification recommends a main body below 5,000 tokens and 500 lines; distinguish authoring guidance from mandatory frontmatter validation and avoid treating a size threshold as proof of quality.

The Agent Skills description limit is 1,024 characters. Keeping a single-line, 500-character description is a reasonable house policy, but the statement that Codex currently enforces that limit needs current evidence; the current Codex skills documentation does not substantiate it. Also avoid claiming all descriptions are always loaded identically across providers and invocation policies.

Source: Agent Skills specification, checked 2026-09-07.

4. Refresh provider facts and permission semantics

Replace blanket claims that all providers safely ignore every unknown field with tested or documented behavior for the specific extension and provider. Keep the compatibility reference date-stamped and recheck affected claims when correctness depends on them; avoid a large unsourced matrix in the main workflow.

Clarify allowed-tools: the specification marks it experimental and uses space-separated values. Claude Code distinguishes allowed-tools grants from disallowed-tools restrictions. Do not describe this field as a portable sandbox or imply an omitted tool is unavailable.

Document explicit invocation per provider. Current Codex documentation describes $skill in CLI/IDE and optional agents/openai.yaml invocation policy; Claude documents /skill-name and its own frontmatter controls. Keep the portable workflow usable without assuming provider-specific argument substitution, question tools, or dispatch names.

Sources: Claude Code skills, Codex skills, checked 2026-09-07. This proposal does not claim an exhaustive live-provider compatibility test.

5. Preserve authorization without unconditional pauses

The current line 194 requires approval before creating files. Replace it with scoped guidance:

• Reuse authorization already provided for the same task and scope.
• Proceed with ordinary authorized scaffolding/edits; ask for unresolved consequential choices or authority.
• Make consequential actions concrete and reviewable before requesting any required final approval.
• Ask optional questions without blocking independent authorized work.
• Do not let skill prose grant authority beyond the user/repository/host contract.

6. Make delegation assurance proportional and recoverable

Retain capability detection, the distinction between unavailable and authorization-required, one approval covering the stated run/roles, explicit worker ownership, and truthful fallback limitations.

Probe required capabilities before dependent writes or side effects. Allow unrelated read-only preparation to continue. State the selected mode and reason when it affects assurance or deliverables; numeric tiers and exact status strings need not be mandatory for every optional helper.

A fallback must still satisfy correctness. If required independent review cannot happen, stop dependent work rather than silently downgrading. Keep the agreed mode stable, but allow explicit reassessment on capability failure or changed scope instead of requiring a known-invalid mode to remain locked until the user intervenes. Seek new authorization only when the revised scope requires it.

7. Separate portable authoring from OAT installation/distribution

Keep .agents/skills/, provider synchronization, and shared-reference materialization as OAT conventions. The baseline should first resolve the repository's actual authoring root and build/distribution process. An authored source tree can differ from the installed skill tree.

Remove unscoped oat sync as an unconditional creation step/success condition. Where OAT synchronization is appropriate, inspect the intended scope and changes and use that scope. The shared-doc symlink plus cp -RL recipe is one build implementation; the portable requirement is that installed references resolve and required resources travel with the skill, or are explicit external prerequisites.

Related: #203 covers explicit and narrowly scoped sync behavior.

8. Prefer behavior-oriented verification over checklist completeness

Extend verification beyond frontmatter and section presence:

• Representative requests that should trigger the skill, plus nearby requests that should not.
• Normal, missing-input, ambiguous-input, and authorization-boundary cases as applicable.
• Meaningful outcome checks and focused deterministic helper regressions.
• Packaged-resource resolution and execution from outside the source checkout when packaging changes.
• Separate static parsing, written walkthroughs, helper tests, provider discovery, and live invocation in the evidence report.

Do not require a new eval framework for every skill or prose edit. Use bounded walkthroughs/manual cases for simple skills, and invest in measured routing/behavior evaluations when failures justify them. Do not run real external writes or replace active installations merely to validate packaging.

9. Make invocation policy intentional; support proactive authoring

The current authoring skill and template default to disable-model-invocation: true. Skill authoring/review should be able to activate automatically when a task clearly involves creating, editing, migrating, auditing, or reviewing a skill, including its references/assets/helpers/tests. Use trigger-led metadata and project instruction routing, with the applicable provider's implicit-invocation settings.

Do not copy manual-only flags into every generated skill. Choose invocation policy based on the workflow and user expectations; retain appropriate controls for consequential operations. Automatic invocation never substitutes for action authorization.

10. Coordinate the version convention with the existing issue

#258 already owns the metadata.version reader/writer migration. Do not duplicate that implementation here. Update this authoring skill, its examples, and template in coordination with that issue, distinguishing specification-compatible string metadata from OAT's chosen SemVer policy. Remove contradictory root-version instructions when the migration supports it.

Acceptance criteria

• Main skill, starter template, canonical guide, and bundled view agree on terminology and policy boundaries.
• Durable authoring principles remain concise; detailed provider/delegation/OAT recipes load conditionally.
• Existing authorization is preserved; ordinary authorized creation does not require an extra approval pause.
• Delegation preflight/fallback rules protect required assurance without mandatory ceremony for optional helpers.
• Provider claims are sourced and dated; unverified compatibility is identified honestly.
• Invocation policy is chosen deliberately, with proactive authoring supported.
• Verification includes representative behavior and clearly separates static evidence from live-provider results.
• Version examples coordinate with Skill versioning should honor the Agent Skills spec's metadata.version (top-level version is non-standard) #258; sync guidance coordinates with Detect stale provider skill views and offer safe sync #203.

A bounded review using a simple helper, a multi-step research skill, a review-only request, and a task with required independent review should be sufficient initial validation. No broad runtime/tooling redesign is requested by this issue.

[tkstang]

Triaged in PR #282 (record). Verified against create-agnostic-skill 1.4.3 on main bb93ad233: seven of the nine proposals hold (the words/tokens mismatch, the unsourced 'Codex enforces single-line ≤ 500 chars' claim whose cited URL now redirects to a page stating no such limit, one blanket unknown-field sentence, the unconditional oat sync step, the comma-vs-space allowed-tools separator, the approval-before-creating-files sentence, and the three divergent frontmatter matrices). Two are not substantiated on the current tree: allowed-tools is already scoped to Claude Code (proposal 5), and no surface requires empty references/ directories (proposal 8). The version-convention proposal already landed (DR-260908-bundled-skills-declare). Tracked as two items: BL-260908-correct-the-factual-skill (medium, M: the factual corrections and consolidation, both skills bumped once) and BL-260908-restructure-the-authoring (low, M: the progressive-disclosure restructure and the proactive-invocation policy, which needs a decision record).

[tkstang]

Triaged in #330 (record).

Progress: the factual corrections shipped in #286. Conditional references, a deliberate invocation policy, and sourced, dated provider claims remain open in BL-260908-restructure-the-authoring (Restructure the authoring skills for progressive disclosure and decide proactive invocation) and BL-260909-re-source-the-surviving-codex (Re-source the surviving Codex provider claims and repair the dead provider-reference URLs). Keeping this open.