@sentry/warden 0.22.0 → 0.23.0

package/src/internal-skills/skill-writer/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: skill-writer
+description: Create, synthesize, and iteratively improve agent skills following the Agent Skills specification. Use when asked to "create a skill", "write a skill", "synthesize sources into a skill", "improve a skill from positive/negative examples", "update a skill", or "maintain skill docs and registration". Handles source capture, depth gates, authoring, registration, and validation.
+---
+
+# Skill Writer
+
+Use this as the single canonical workflow for skill creation and improvement.
+Primary success condition: maximize high-value input coverage before authoring while minimizing wasted runtime tokens.
+
+Load only the path(s) required for the task. `SKILL.md` is the primary router: every bundled reference file should have a direct "open when..." reason here.
+
+## Core Workflow References
+
+| Open when you need to... | Read |
+|--------------------------|------|
+| choose the minimum workflow path for create, update, iterate, or research-first work | `references/mode-selection.md` |
+| choose the simplest adequate execution shape before deciding files | `references/execution-shapes.md` |
+| apply writing constraints for depth, concision, and portability | `references/design-principles.md` |
+| decide what belongs in `SKILL.md`, `references/`, `SPEC.md`, or subfolders | `references/reference-architecture.md` |
+| create or update the maintenance contract for a skill | `references/spec-template.md` |
+| find missing high-signal sources, including history and regressions | `references/source-discovery.md` |
+| run the full synthesis pass with depth gates and source capture | `references/synthesis-path.md` |
+| author or update `SKILL.md`, `SPEC.md`, and supporting files | `references/authoring-path.md` |
+| improve trigger language and false-positive/false-negative behavior | `references/description-optimization.md` |
+| iterate from positive, negative, or fix examples | `references/iteration-path.md` |
+| store persistent working and holdout examples for future revisions | `references/iteration-evidence.md` |
+| choose a response template, schema, or output contract | `references/output-contracts.md` |
+| troubleshoot overloaded layouts, hidden refs, or other structure failures | `references/structure-troubleshooting.md` |
+| verify a risky, disputed, or explicitly requested change | `references/evaluation-path.md` |
+| register the skill and run final validation checks | `references/registration-validation.md` |
+
+## Artifact Layout References
+
+| Open when you need to... | Read |
+|--------------------------|------|
+| keep the whole skill inline in one coherent `SKILL.md` | `references/artifact-layouts/inline-skill-layout.md` |
+| split optional deep knowledge into focused routed references | `references/artifact-layouts/reference-backed-skill-layout.md` |
+| add scripts for deterministic automation or validation | `references/artifact-layouts/script-backed-skill-layout.md` |
+| define a skill that is usually invoked with explicit arguments | `references/artifact-layouts/argument-driven-skill-layout.md` |
+| ship reusable templates, schemas, or other static assets | `references/artifact-layouts/asset-template-skill-layout.md` |
+
+## Workflow Mechanic References
+
+| Open when you need to... | Read |
+|--------------------------|------|
+| break a task into fixed ordered steps | `references/workflow-mechanics/prompt-chaining.md` |
+| classify requests and route them to different downstream paths | `references/workflow-mechanics/routing-workflows.md` |
+| split independent work into parallel units or votes | `references/workflow-mechanics/parallel-workflows.md` |
+| discover work units dynamically and coordinate worker outputs | `references/workflow-mechanics/orchestrator-workers.md` |
+| critique and revise output against a rubric | `references/workflow-mechanics/evaluator-loops.md` |
+| run validate-fix-repeat checks during authoring or execution | `references/workflow-mechanics/validation-loops.md` |
+| validate a plan before executing a risky action | `references/workflow-mechanics/plan-validate-execute.md` |
+
+## Claude Code References
+
+| Open when you need to... | Read |
+|--------------------------|------|
+| use Claude-specific frontmatter or invocation controls | `references/claude-code/frontmatter-and-invocation.md` |
+| use Claude argument fields or substitution variables | `references/claude-code/argument-substitutions.md` |
+| build a skill that runs in isolated `context: fork` | `references/claude-code/subagent-fork-skills.md` |
+| build a skill that uses Claude hooks for deterministic enforcement | `references/claude-code/hook-backed-skills.md` |
+| use Claude shell preprocessing for dynamic context injection | `references/claude-code/dynamic-context.md` |
+
+## Example Profiles
+
+| Open when you need to... | Read |
+|--------------------------|------|
+| see the expected depth for a documentation-heavy skill | `references/examples/documentation-skill.md` |
+| see the expected depth for a security-review skill | `references/examples/security-review-skill.md` |
+| see the expected depth for a workflow-process skill | `references/examples/workflow-process-skill.md` |
+| see what a good routed skill looks like | `references/examples/router-skill.md` |
+| see what a good evaluator-loop skill looks like | `references/examples/evaluator-loop-skill.md` |
+| see what a good subagent-fork skill looks like | `references/examples/subagent-fork-skill.md` |
+| see what a good hook-backed skill looks like | `references/examples/hook-backed-skill.md` |
+
+## Step 1: Resolve target, path, and shape
+
+1. Resolve the intended operation (`create`, `update`, `synthesize`, `iterate`) and inspect workspace prior art before choosing where files belong.
+2. Choose the target skill root from observed conventions. If the canonical location is still unclear after inspection, ask one direct question before editing files.
+3. Read `references/mode-selection.md` to choose the minimum required workflow paths.
+4. Read `references/execution-shapes.md` to choose the primary execution shape.
+5. Default to the simplest adequate shape. If selecting a more complex shape, record why simpler shapes were rejected.
+6. Load only the exact artifact-layout, workflow-mechanic, and provider-specific leaf files required by that shape.
+7. Record portability implications before using provider-specific mechanics.
+
+## Step 2: Run synthesis when needed
+
+Read `references/synthesis-path.md`.
+
+1. Use this path for new skills, material changes, and research-first planning.
+2. Collect and score relevant sources with provenance.
+3. Read `references/source-discovery.md` when source material is thin, stale, or ambiguous.
+4. Produce source-backed decisions and coverage/gap status, including the class and execution-shape choice.
+5. Load example profiles only when they add concrete depth for the selected class or shape.
+6. If the skill uses provider-specific mechanics, include current official provider docs and capture usage constraints.
+7. Do not move to authoring until depth gates pass.
+
+## Step 3: Run iteration first when improving from outcomes/examples
+
+Read `references/iteration-path.md` first when selected path includes `iteration` (for example operation `iterate`).
+
+1. Capture and anonymize examples with provenance.
+2. Read `references/iteration-evidence.md` when examples should persist beyond the current turn.
+3. Re-evaluate skill behavior against working and holdout slices.
+4. Propose improvements from positive/negative/fix evidence.
+5. Carry concrete behavior deltas into authoring.
+
+Skip this step when selected path does not include `iteration`.
+
+## Step 4: Author or update skill artifacts
+
+Read `references/authoring-path.md`.
+
+1. Write or update `SKILL.md` in imperative voice with trigger-rich description.
+2. Keep `SKILL.md` as the runtime router, not an encyclopedia.
+3. Read `references/reference-architecture.md` before adding bulk instructions or new reference files.
+4. Create or update `SPEC.md` using `references/spec-template.md` when creating a new skill or materially changing its contract.
+5. Create focused reference files, subfolders, scripts, and assets only when each one has a clear "open when..." reason.
+6. If you add a bundled reference file, add a direct routing entry for it in this `SKILL.md`.
+7. Prefer checklists, tables, templates, and input/output examples over explanatory prose.
+8. Follow only the specific artifact-layout, workflow-mechanic, Claude-specific, and output-contract references selected for this skill.
+9. For advanced execution shapes, add the required routing, delegation, or safety contracts before considering the skill complete.
+10. For authoring/generator skills, include transformed examples in references:
+   - happy-path
+   - secure/robust variant
+   - anti-pattern + corrected version
+
+## Step 5: Optimize description quality
+
+Read `references/description-optimization.md`.
+
+1. Validate should-trigger and should-not-trigger query sets.
+2. Reduce false positives and false negatives with targeted description edits.
+3. Keep trigger language generic across providers unless the skill is intentionally provider-specific.
+
+## Step 6: Evaluate only when needed
+
+1. Read `references/evaluation-path.md` only when the user asks for evaluation, the change is high-risk, or the architecture choice is non-obvious.
+2. If you run evaluation, start with the lightweight qualitative check.
+3. Run deeper evals only when requested or risk warrants it.
+4. Record outcomes and unresolved risks when evaluation is run.
+
+## Step 7: Register and validate
+
+Read `references/registration-validation.md`.
+
+1. Apply repository registration steps for the active layout you verified in the workspace.
+2. Run quick validation with strict depth gates.
+3. Reject shallow outputs that fail depth gates or required artifact checks.
+
+## Output format
+
+Return:
+
+1. `Summary`
+2. `Changes Made`
+3. `Validation Results`
+4. `Open Gaps`

package/src/internal-skills/skill-writer/SOURCES.md

@@ -0,0 +1,94 @@
+# Sources
+
+This file tracks source material synthesized into `skill-writer`, plus iterative changes over time.
+
+## Current source inventory
+
+| Source | Type | Trust tier | Retrieved | Confidence | Contribution | Usage constraints | Notes |
+|---|---|---|---|---|---|---|---|
+| `SKILL.md` | local canonical | canonical | 2026-05-01 | high | Baseline orchestration, path model, and runtime contract | local active skill root | Primary source of current behavior |
+| `references/**/*.md` | local canonical | canonical | 2026-05-01 | high | Detailed path guidance, examples, routed leaf references, and validation requirements | local active skill root | Includes shape, synthesis, iteration, evaluation, provider-specific guidance, and lookup-oriented subfolders |
+| `SPEC.md` | local canonical | canonical | 2026-05-01 | high | Canonical maintenance contract for intent, scope, evidence model, evaluation, and limitations | local active skill root | Updated to treat `skill-writer` as a meta-router |
+| `https://agentskills.io/specification` | external canonical spec | canonical | 2026-05-01 | high | Portable skill structure, frontmatter, progressive disclosure, optional directories, and file-reference rules | spec-level constraints take precedence over local preferences | Cross-agent compatibility baseline |
+| `https://agentskills.io/skill-creation/best-practices` | external official docs | canonical | 2026-05-01 | high | Coherent unit design, moderate detail, progressive disclosure, defaults over menus, validation loops, plan-validate-execute | skill-authoring guidance, not provider-specific runtime semantics | Informed shape-selection and workflow guidance |
+| `https://agentskills.io/skill-creation/using-scripts` | external official docs | canonical | 2026-05-01 | high | Script bundling, non-interactive requirements, `--help`, structured output, and safe script interfaces | script examples are illustrative, adapt to local tooling | Informed script-backed workflow requirements |
+| `https://code.claude.com/docs/en/skills` | external official docs | canonical | 2026-05-01 | high | Current Claude Code skill lifecycle, frontmatter fields, argument features, `context: fork`, `allowed-tools`, and hooks-in-skills support | provider-specific; do not generalize to portable Agent Skills behavior | Replaced stale local assumptions about Claude-specific fields |
+| `https://code.claude.com/docs/en/sub-agents` | external official docs | canonical | 2026-05-01 | high | Automatic delegation, focused subagents, explicit invocation modes, and subagent lifecycle integration | provider-specific | Informed `subagent-fork` shape guidance |
+| `https://code.claude.com/docs/en/hooks` | external official docs | canonical | 2026-05-01 | high | Hook lifecycle, hooks in skills and agents, async constraints, and security requirements | provider-specific and security-sensitive | Informed `hook-backed` shape guidance and safety notes |
+| `https://www.anthropic.com/engineering/building-effective-agents` | external official engineering guidance | canonical | 2026-05-01 | high | Simplicity-first design and workflow taxonomy: prompt chaining, routing, parallelization, orchestrator-workers, evaluator-optimizer | conceptual guidance; adapt to skill authoring rather than full app orchestration | Core source for execution-shape taxonomy |
+| `https://developers.openai.com/api/docs/guides/reasoning-best-practices` | external official docs | canonical | 2026-05-01 | high | Planner/doer distinction, reasoning-vs-GPT model tradeoffs, and avoiding explicit chain-of-thought prompting | provider-specific model guidance; use only as general orchestration input unless exact product syntax matters | Informed reasoning-model and evaluator-loop notes |
+| `https://openai.com/business/guides-and-resources/a-practical-guide-to-building-ai-agents/` | external official guidance | canonical | 2026-05-01 | high | Maximize a single agent first, use multi-agent only when needed, manager-vs-handoff split, layered guardrails | product-level guidance, not a skills standard | Informed simplicity rule and advanced-shape escalation criteria |
+| `https://openai.github.io/openai-agents-python/agents/` | external official SDK docs | canonical | 2026-05-01 | medium | Manager-vs-handoff distinction and structured-output support | SDK-specific implementation details | Informed router/orchestrator language and contract expectations |
+| `https://openai.github.io/openai-agents-python/handoffs/` | external official SDK docs | canonical | 2026-05-01 | medium | Handoff metadata, input filters, and receiving-agent history control | SDK-specific implementation details | Informed route/handoff contract guidance |
+| `https://huggingface.co/docs/hub/model-cards` | external documentation pattern | secondary | 2026-04-26 | high | Model-card sections for intended use, data, evaluation, limitations, and reproducibility | adapted as documentation prior art, not a skill standard | Inspired `SPEC.md` maintenance contract shape |
+| `https://huggingface.co/docs/hub/en/model-card-annotated` | external documentation pattern | secondary | 2026-04-26 | high | Annotated intended-use, out-of-scope, risks, limitations, and evaluation sections | adapted as documentation prior art, not a skill standard | Informed SPEC scope and limitations sections |
+| `https://cacm.acm.org/research/datasheets-for-datasets/` | research/documentation pattern | secondary | 2026-04-26 | high | Data provenance, collection, composition, intended use, and maintenance transparency | adapted from dataset documentation to skill evidence documentation | Informed source/evidence model and privacy rules |
+| `https://diataxis.fr/` | documentation framework | secondary | 2026-04-26 | high | User-need-centered documentation types: tutorial, how-to, reference, explanation | adapted as information architecture prior art, not a skill standard | Informed reference files as lookup needs rather than topic buckets |
+| `https://dita-lang.org/` | documentation standard | secondary | 2026-04-26 | high | Topic-oriented technical content patterns: task, concept, reference, troubleshooting | adapted as documentation architecture prior art | Informed reference type table and troubleshooting matrix guidance |
+| `https://www.writethedocs.org/guide/writing/docs-principles/` | documentation guidance | secondary | 2026-04-26 | medium | Documentation should be structured for findability, reuse, and user participation | general writing guidance | Cross-check for reference architecture usability |
+| `AGENTS.md` | repo convention | canonical | 2026-05-01 | high | Repository-specific workflow requirements and registration checklist | repository-local policy | Registration + validator expectations |
+| `README.md` | repo convention | canonical | 2026-05-01 | high | Skill table format and authoring conventions | repository-local policy | Registration and discoverability source |
+
+## Decisions
+
+1. `skill-writer` is a meta-router: it must choose both a skill class and an execution shape before authoring.
+2. Default to the simplest adequate shape. Advanced mechanics require evidence and an explicit reason simpler shapes were rejected.
+3. Skill class and execution shape are independent axes. Class drives coverage requirements; shape drives runtime mechanics and artifact layout.
+4. `SKILL.md` remains the orchestration/index layer; references, scripts, assets, hooks, and subagents are leaves selected by that router.
+5. Provider-specific Claude Code features are valuable but not default. Use them only when justified and record portability implications.
+6. Claude-specific frontmatter guidance should track the current `code.claude.com/docs/en/skills` fields, including `when_to_use`, `arguments`, `effort`, `paths`, `shell`, `context`, `agent`, and `hooks`.
+7. Router, parallel/orchestrator, evaluator-loop, subagent-fork, and hook-backed shapes each require explicit contracts, not just prose.
+8. Hooks are deterministic enforcement and need narrow scope plus security notes because command hooks run with full user permissions.
+9. Multi-agent guidance should distinguish manager/orchestrator, handoff, and isolated subagent execution instead of collapsing them into one pattern.
+10. Reasoning-model guidance is a design option, not a universal default: planner/doer splits are useful when complexity warrants them.
+11. Authoring review should check architectural choices qualitatively; the quick validator remains mechanical.
+12. Reference files remain split by lookup need rather than topic buckets, even as the set of supported shapes expands.
+13. Subfolders inside `references/` are acceptable when they create clearer lookup leaves, but every bundled reference should still be directly discoverable from `SKILL.md`.
+14. The validator should enforce durable SKILL.md frontmatter/YAML identity guarantees, but should not hardcode provider-specific optional frontmatter keys or markdown-content opinions.
+15. `skill-writer` should default to dense structures such as tables, checklists, templates, and I/O examples, and should cut explanatory prose unless it prevents a concrete mistake.
+16. `SKILL.md` should stay a thin router; repeated policy belongs in routed references rather than always-loaded step prose.
+17. Evaluation is conditional and should not be part of the default authoring path unless the user asks for it or the change is genuinely risky.
+
+## Coverage matrix
+
+| Dimension | Coverage status | Evidence |
+|---|---|---|
+| SKILL.md vs references placement | complete | Agent Skills spec, local reference architecture |
+| Reference splitting heuristics | complete | Agent Skills best practices, Diataxis, DITA, local reference architecture and artifact-layout guidance |
+| Long reference navigation | complete | local design principles |
+| Source discovery beyond docs | complete | local synthesis depth gates, repository history practices |
+| Commit log as source material | complete | local source-discovery guidance |
+| Positive/negative evidence storage | complete | local iteration path, prior eval guidance |
+| Skill maintenance specification | complete | model cards, datasheets, local `SPEC.md` reference implementation |
+| Shape-selection framework | complete | Anthropic effective agents, OpenAI practical guide, local execution-shapes guidance |
+| Router/orchestrator/evaluator patterns | complete | Anthropic effective agents, OpenAI agent guides, local workflow-mechanics guidance |
+| Current Claude skill frontmatter and lifecycle mechanics | complete | Claude Code skills docs |
+| Subagent-fork guidance | complete | Claude Code skills docs, subagents docs |
+| Hook-backed guidance and security constraints | complete | Claude Code hooks docs |
+| Script-backed workflow design | complete | Agent Skills using scripts guide |
+| Planner/doer reasoning guidance | complete | OpenAI reasoning best practices |
+| Lookup-oriented reference architecture | complete | Diataxis user needs, DITA topic types, local reference architecture |
+
+## Open gaps
+
+1. This repository still has few real shipped examples using `hooks`, `context: fork`, `when_to_use`, `arguments`, `paths`, or `effort`.
+2. Public repo docs outside `skill-writer` may need follow-up updates to fully reflect the current Claude-specific skill fields.
+
+## Changelog
+
+- 2026-03-05: Initialized `SOURCES.md` with baseline source pack (local canonical, Codex upstream, Claude upstream, spec, and repo conventions).
+- 2026-03-19: Clarified path-resolution guidance so bundled skill references stay skill-root-relative while registration steps are resolved from the repository's active layout.
+- 2026-03-19: Made portability a default authoring rule and emphasized avoiding host-specific absolute filesystem paths.
+- 2026-04-19: Updated path guidance to preserve repository-standard root variables such as `${CLAUDE_SKILL_ROOT}` instead of banning them outright.
+- 2026-04-19: Restored `.agents/skills` as the default authoring target and kept repository-specific layouts as an inspected override rather than the default.
+- 2026-04-19: Added explicit prior-art inspection and user-confirmation guidance when the correct skill root is unclear.
+- 2026-04-26: Added reference architecture, source discovery, and iteration evidence guidance; updated synthesis, authoring, and iteration paths to prevent overloaded `SKILL.md` and catch-all reference files.
+- 2026-04-26: Added `SPEC.md` as the canonical `skill-writer` maintenance specification and added `references/spec-template.md` for future skills.
+- 2026-04-26: Removed fixed integration reference filename validation and added length-based reference warnings.
+- 2026-04-26: Reworked reference architecture around concrete lookup needs instead of generic topic buckets.
+- 2026-05-01: Reworked `skill-writer` around explicit execution-shape routing, added shape-specific example profiles, refreshed Claude Code provider mechanics from current official docs, and added eval/source guidance for routing, delegation, hooks, and evaluator loops.
+- 2026-05-01: Replaced generic pattern bucket references with routed leaf files under `references/artifact-layouts/`, `references/workflow-mechanics/`, and `references/claude-code/`; made `SKILL.md` enumerate every bundled reference file with a direct open-when reason.
+- 2026-05-01: Removed the validator's hardcoded optional frontmatter allowlist so provider-specific field drift does not create noisy false warnings.
+- 2026-05-01: Reduced prose-heavy guidance in `skill-writer`, rewrote the main runtime refs into denser tables/checklists, and made compact runtime guidance an explicit contract.
+- 2026-05-01: Thinned `SKILL.md` back toward a true router, removed duplicated execution-shape detail from `mode-selection.md`, and made evaluation conditional instead of a default workflow path.
+- 2026-05-05: Reduced `quick_validate.py` to mechanical SKILL.md frontmatter/YAML and identity checks; markdown content quality now belongs to authoring review.

package/src/internal-skills/skill-writer/SPEC.md

@@ -0,0 +1,153 @@
+# Skill Writer Specification
+
+## Intent
+
+`skill-writer` is the canonical workflow for creating, updating, synthesizing, and iteratively improving agent skills in this repository.
+
+Its primary purpose is to prevent shallow skill authoring by forcing high-value source coverage, explicit provenance, focused runtime instructions, and validation before completion.
+It is also a meta-router: before authoring, it must choose the simplest adequate execution shape for the target skill and only then decide which artifacts are needed.
+
+## Scope
+
+In scope:
+
+- New skill creation from local, external, or mixed sources.
+- Existing skill updates that affect runtime behavior, structure, trigger precision, references, or validation.
+- Research-first synthesis for proposed skills.
+- Iteration from positive examples, negative examples, review feedback, eval results, and observed agent behavior.
+- Registration and validation for this repository's canonical `skills/<skill-name>/` layout and other discovered layouts.
+- Choosing between execution shapes such as inline guidance, reference-backed expert, script-backed workflow, router, evaluator loop, subagent-fork, hook-backed, asset-template, or hybrids.
+- Assessing when provider-specific mechanics are justified and documenting portability constraints.
+
+Out of scope:
+
+- Acting as the runtime instructions for the skills it creates.
+- Storing full source inventories, raw examples, or changelog history directly in `SKILL.md`.
+- Replacing repository-level instructions in `AGENTS.md`, `README.md`, or `CONTRIBUTING.md`.
+- Creating per-skill aliases or symlink skills in this repository.
+- Guaranteeing compatibility with provider-specific skill extensions unless they are explicitly scoped and documented.
+
+## Users And Trigger Context
+
+- Primary users: agents and humans authoring or maintaining reusable agent skills.
+- Common user requests: "create a skill", "write a skill", "update this skill", "improve from examples", "synthesize a skill from docs", "maintain skill docs", or "validate/register this skill".
+- Should not trigger for: ordinary code review, generic documentation edits, PR writing, commit creation, or implementation work that does not create or modify an agent skill.
+
+## Runtime Contract
+
+- Required first actions:
+  - Resolve the target skill root and operation.
+  - Inspect local repository conventions before deciding where files belong.
+  - Classify the skill and select the minimum required workflow paths.
+  - Select a primary execution shape and default to the simplest adequate option.
+  - Treat evaluation as conditional rather than a default path.
+- Required outputs:
+  - Summary.
+  - Changes Made.
+  - Validation Results.
+  - Open Gaps.
+- Non-negotiable constraints:
+  - `SKILL.md` frontmatter is first line and `name` matches the directory.
+  - `description` contains realistic trigger language.
+  - `SKILL.md` remains an orchestration/index layer for complex skills.
+  - Runtime guidance should prefer dense structures such as tables, checklists, templates, and examples over explanatory prose.
+  - Material skill changes explicitly name the selected execution shape.
+  - Advanced mechanics are justified and include portability notes.
+  - Supporting references are focused and loaded conditionally.
+  - Source provenance and decisions live in `SOURCES.md`.
+  - Durable positive/negative examples live in `references/evidence/`.
+  - `SPEC.md` records the maintenance contract for new or materially changed skills.
+  - Validation runs before completion.
+- Expected bundled files loaded at runtime:
+  - `references/mode-selection.md`
+  - `references/execution-shapes.md`
+  - `references/synthesis-path.md`
+  - `references/iteration-path.md`
+  - `references/authoring-path.md`
+  - `references/reference-architecture.md`
+  - `references/spec-template.md`
+  - `references/description-optimization.md`
+  - `references/evaluation-path.md` when the user asks for evaluation, the change is high-risk, or the architecture choice is non-obvious
+  - `references/registration-validation.md`
+  - `references/artifact-layouts/*.md`
+  - `references/workflow-mechanics/*.md`
+  - `references/claude-code/*.md`
+  - `references/examples/*.md`
+  - `scripts/quick_validate.py`
+
+## Source And Evidence Model
+
+Authoritative sources:
+
+- Local `skill-writer` runtime files: `SKILL.md`, `references/**/*.md`, `scripts/quick_validate.py`.
+- Repository policy: `AGENTS.md`, `README.md`, `CONTRIBUTING.md`, plugin manifests, and registration settings.
+- Agent Skills specification and official skill authoring guidance.
+- Current official provider docs for any provider-specific mechanics being recommended.
+- Official orchestration guidance for routing, delegation, evaluation loops, and reasoning-model planning patterns.
+
+Useful improvement sources:
+
+- positive examples: successful generated skills, review-approved skill changes, and eval passes that demonstrate desired behavior
+- negative examples: shallow generated skills, overloaded `SKILL.md` files, catch-all references, missing provenance, failed validation, false triggers, or review feedback
+- commit logs/changelogs: repeated fixes, reversions, migrations, and changes that explain why a rule exists
+- issue or PR feedback: reviewer comments about missing coverage, confusing trigger language, poor file placement, or insufficient evaluation
+- eval results: fixed prompt sets in `EVAL.md`, qualitative depth checks, and optional baseline-vs-with-skill runs
+
+Data that must not be stored:
+
+- secrets, credentials, or tokens
+- raw customer data
+- private URLs or identifiers that are not needed for reproduction
+- large copied source documents or long copyrighted excerpts
+- unredacted personal data from examples, logs, issues, or commits
+
+## Reference Architecture
+
+- `SKILL.md` contains the top-level workflow, path-loading table, branch points, universal constraints, and output contract.
+- `SKILL.md` acts as a meta-router for the authoring process: class selection, shape selection, and path selection happen before writing.
+- `SPEC.md` contains this maintenance specification.
+- `SOURCES.md` contains source inventory, decisions, coverage matrix, open gaps, and changelog.
+- `EVAL.md` contains reusable evaluation prompts and deeper eval runbooks.
+- `references/` contains focused workflow guidance, routed leaf references, templates, rubrics, and class-specific authoring requirements.
+- `references/` may use subfolders when they create clearer leaf routing, but every bundled reference should still be directly routed from `SKILL.md`.
+- `references/evidence/` contains durable positive/negative examples when future iterations need them.
+- `scripts/` contains validation automation.
+- `assets/` is unused unless a future skill-authoring workflow needs static templates or media.
+
+## Evaluation
+
+- Lightweight validation:
+  - Run `uv run <skill-writer-root>/scripts/quick_validate.py <skill-writer-root> --skill-class skill-authoring --strict-depth` as a frontmatter/YAML smoke check.
+  - Inspect changed references qualitatively for focused scope, direct discoverability, and absence of host-specific paths.
+  - Verify that the selected execution shape is explicit and that advanced mechanics, if any, are justified.
+- Deeper evaluation:
+  - Use `references/evaluation-path.md` and `EVAL.md` only when the user requests it, the change is high-risk, or the architectural choice needs verification.
+  - Compare behavior before and after changes with representative positive and negative prompts.
+  - Include shape-selection prompts when the change affects routing, delegation, hooks, or evaluator loops.
+- Holdout examples:
+  - Keep durable holdout examples in `references/evidence/holdout-set.md` when repeated regressions appear.
+  - Do not tune directly against holdout examples until they are intentionally moved to the working set.
+- Acceptance gates:
+  - Validator passes with no errors for SKILL.md frontmatter/YAML and identity fields.
+  - New or changed workflow rules are represented in the correct artifact.
+  - `SOURCES.md` records source-backed decisions and any remaining gaps.
+  - `SPEC.md` is updated when intent, scope, evidence model, evaluation, or maintenance expectations change.
+
+## Known Limitations
+
+- The validator intentionally checks only SKILL.md frontmatter/YAML and identity fields; markdown content quality belongs to authoring review.
+- The validator does not verify advanced-shape contracts, reference completeness, source depth, prose density, or `SPEC.md` heading templates.
+- The validator intentionally does not hardcode or exhaustively validate provider-specific optional frontmatter fields.
+- Deeper evals are opt-in unless risk or user request justifies the extra cost.
+- Source discovery can still miss private operational knowledge if it is not present in local files, accessible issue/PR history, or supplied context.
+- Provider-specific skill extensions may drift; `skill-writer` treats them as compatibility guidance unless a skill is intentionally provider-specific.
+
+## Maintenance Notes
+
+- Update `SKILL.md` when the required runtime workflow, branch conditions, or output contract changes.
+- Update `references/execution-shapes.md` when new skill mechanics or orchestration patterns become important.
+- Update the relevant file under `references/artifact-layouts/`, `references/workflow-mechanics/`, or `references/claude-code/` when a specific routed leaf changes.
+- Update `SPEC.md` when intent, scope, user/trigger context, evidence model, evaluation gates, limitations, or maintenance rules change.
+- Update `SOURCES.md` when source inventory, decisions, coverage, gaps, or changelog entries change.
+- Update `EVAL.md` when reusable evaluation prompts or runbooks change.
+- Update `references/evidence/` when preserving examples for future iteration or regression tracking.

package/src/internal-skills/skill-writer/references/artifact-layouts/argument-driven-skill-layout.md

@@ -0,0 +1,32 @@
+# Argument-Driven Skill Layout
+
+Use this layout when the skill is normally invoked with explicit inputs such as issue numbers, paths, modes, or targets.
+
+## Choose this layout when
+
+- the user supplies parameters directly
+- empty-input behavior needs to be defined
+- manual invocation is safer than automatic activation
+
+## Common layout
+
+```yaml
+---
+name: fix-issue
+description: Fix a GitHub issue by number. Use when asked to fix or resolve a specific issue.
+argument-hint: "[issue-number]"
+disable-model-invocation: true
+---
+```
+
+## Required contract
+
+1. Document expected arguments and empty-input behavior.
+2. Use manual-only invocation when side effects are substantial.
+3. Use named or positional arguments only when they improve clarity.
+4. Add portability notes if the argument syntax depends on provider-specific mechanics.
+
+## Also load
+
+- `references/claude-code/argument-substitutions.md` when using Claude Code substitutions or named arguments
+- `references/claude-code/frontmatter-and-invocation.md` when invocation control needs provider-specific fields

package/src/internal-skills/skill-writer/references/artifact-layouts/asset-template-skill-layout.md

@@ -0,0 +1,30 @@
+# Asset-Template Skill Layout
+
+Use this layout when reusable templates, schemas, or static artifacts carry most of the skill's value.
+
+## Choose this layout when
+
+- the skill fills in or adapts reusable artifacts
+- the runtime procedure is small compared to the bundled assets
+- output quality depends on stable templates or schemas
+
+## File layout
+
+```text
+my-skill/
+├── SKILL.md
+└── assets/
+    ├── template.md
+    └── schema.json
+```
+
+## Required contract
+
+1. `SKILL.md` tells the agent when to load each asset.
+2. The skill explains how to adapt placeholders or fields.
+3. Add a validation checklist when filled-in output can silently drift.
+
+## Avoid this layout when
+
+- the template is small enough to stay inline
+- the asset is just an attachment with no routing or reuse value

package/src/internal-skills/skill-writer/references/artifact-layouts/inline-skill-layout.md

@@ -0,0 +1,28 @@
+# Inline Skill Layout
+
+Use this layout when one coherent policy, checklist, or procedure fits directly in `SKILL.md`.
+
+## Choose this layout when
+
+- the skill has one dominant path
+- every invocation needs roughly the same instructions
+- deep optional knowledge is not the main problem
+
+## File layout
+
+```text
+my-skill/
+└── SKILL.md
+```
+
+## Required contract
+
+1. Keep the body small enough to scan in one read.
+2. Put all universal steps in `SKILL.md`.
+3. Add references only if a real branch or lookup need appears.
+
+## Avoid this layout when
+
+- most invocations need only a subset of a large knowledge base
+- scripts or validators carry important runtime behavior
+- routing or iterative evaluation is central to the skill

package/src/internal-skills/skill-writer/references/artifact-layouts/reference-backed-skill-layout.md

@@ -0,0 +1,35 @@
+# Reference-Backed Skill Layout
+
+Use this layout when the skill needs deep knowledge, but most runs only need one branch or subset of that knowledge.
+
+## Choose this layout when
+
+- `SKILL.md` can act as a router
+- bundled references can stay focused by lookup need
+- the complexity is optional knowledge, not heavy automation
+
+## File layout
+
+```text
+my-skill/
+├── SKILL.md
+└── references/
+    ├── focused-topic-a.md
+    ├── focused-topic-b.md
+    └── troubleshooting.md
+```
+
+Subfolders are acceptable when they make the lookup path clearer, for example `references/api/` or `references/examples/`.
+
+## Required contract
+
+1. `SKILL.md` tells the agent exactly when to open each reference.
+2. Reference filenames predict their contents.
+3. No reference mixes routing, troubleshooting, examples, and source notes without a clear reason.
+4. Large references include navigation or are split further.
+
+## Avoid this layout when
+
+- the skill is small enough to stay inline
+- scripts or validators are central to execution
+- the references would only exist as vague topic buckets

package/src/internal-skills/skill-writer/references/artifact-layouts/script-backed-skill-layout.md

@@ -0,0 +1,31 @@
+# Script-Backed Skill Layout
+
+Use this layout when parsing, validation, APIs, or repeatable transformations are fragile in plain shell or prose alone.
+
+## Choose this layout when
+
+- the skill benefits from deterministic automation
+- repeated shell snippets would be brittle
+- validation or data extraction should be reusable
+
+## File layout
+
+```text
+my-skill/
+├── SKILL.md
+└── scripts/
+    ├── fetch.py
+    └── validate.py
+```
+
+## Required contract
+
+1. Every script is named in `SKILL.md` with arguments, outputs, and fallback behavior.
+2. Scripts are non-interactive.
+3. Standard output is structured when practical.
+4. The skill explains what to do if a script fails or is unavailable.
+
+## Avoid this layout when
+
+- one simple shell command is enough
+- the "script" would only wrap trivial shell for no reliability gain