@sentry/warden 0.21.0 → 0.23.0

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

package/src/internal-skills/skill-writer/references/authoring-path.md

@@ -0,0 +1,91 @@
+# Authoring Path
+
+Use this path to create or update skill files.
+
+## Runtime Writing Rules
+
+1. Frontmatter must be first line.
+2. `name` must match the directory.
+3. `description` must contain realistic trigger language.
+4. Keep runtime guidance imperative and compact.
+5. Prefer tables, checklists, templates, and examples over prose.
+6. Use `SKILL.md` as the runtime decision layer for complex skills.
+
+## Path Rules
+
+1. Treat the skill directory as the root for bundled files.
+2. Use `references/...`, `scripts/...`, and `assets/...` paths by default.
+3. Reserve repo-root paths for registration instructions only.
+4. Follow repo prior art if the workspace already standardizes on a provider-specific path variable.
+5. Avoid host-specific absolute filesystem paths.
+
+## Supporting Files
+
+Create only what the skill needs:
+
+| File or dir | Use |
+|-------------|-----|
+| `SPEC.md` | maintenance contract |
+| `references/` | optional depth loaded by route |
+| `references/evidence/` | persistent iteration examples |
+| `scripts/` | repeatable automation or validation |
+| `assets/` | reusable templates or static artifacts |
+
+Subfolders inside `references/` are acceptable only when they make the lookup path clearer.
+
+## File Creation Rules
+
+1. Read `references/reference-architecture.md` before adding bundled files.
+2. Create a new reference only when it has a clear "open when..." reason.
+3. If you add a bundled reference, add a direct routing entry for it in `SKILL.md`.
+4. Do not create catch-all docs that mix workflow, source notes, examples, and eval results.
+5. Keep provenance in `SOURCES.md`, not in runtime files.
+6. Update `SPEC.md` when the skill contract changes materially.
+
+## Class-Specific Requirements
+
+### `integration-documentation`
+
+Require focused coverage for:
+
+1. API surface and behavior contracts
+2. config/runtime options
+3. common downstream use cases
+4. known issues and workarounds
+5. version or migration variance
+
+Default minimum depth:
+
+1. at least 6 concrete downstream use cases
+2. at least 8 issue/fix or failure/workaround entries
+
+## Shape-Specific Requirements
+
+| Shape | Require |
+|-------|---------|
+| `router` | route criteria, fallback, per-route contract, misroute recovery |
+| `script-backed-workflow` | documented scripts, non-interactive execution, structured output, fallback |
+| `parallelization` / `orchestrator-workers` | unit of work, worker output schema, merge rule, stop condition |
+| `evaluator-optimizer` | rubric, stop rule, acceptance condition, evidence handling |
+| `subagent-fork` | actionable task, return contract, isolation reason, portability note |
+| `hook-backed` | event scope, side-effect boundary, fallback, safety note |
+| `asset-template` | asset routing, placeholder guidance, validation checklist when needed |
+| `argument-driven` | expected arguments, empty-input behavior, manual-only use when risky |
+
+## Example Requirements
+
+Authoring or generator skills should include:
+
+1. happy-path example
+2. secure or robust variant
+3. anti-pattern plus correction
+
+Do not accept abstract-only guidance when a concrete example is needed.
+
+## Required Output
+
+- updated `SKILL.md`
+- updated `SPEC.md` when required
+- updated or added supporting files
+- explanation of major authoring decisions
+- description-optimization handoff

package/src/internal-skills/skill-writer/references/claude-code/argument-substitutions.md

@@ -0,0 +1,20 @@
+# Claude Argument Substitutions
+
+Load this when the skill uses Claude Code argument fields or substitution variables.
+
+## Supported substitutions
+
+- `$ARGUMENTS`
+- `$ARGUMENTS[N]`
+- `$N`
+- named arguments such as `$issue` when `arguments` is declared
+- `${CLAUDE_SESSION_ID}`
+- `${CLAUDE_EFFORT}`
+- `${CLAUDE_SKILL_DIR}`
+
+## Required contract
+
+1. Document expected arguments and empty-input behavior.
+2. Add quoting-aware examples for multi-word input when ambiguity is likely.
+3. Use manual-only invocation for side-effect-heavy argument-driven skills.
+4. Add portability notes because this syntax is Claude Code-specific.

package/src/internal-skills/skill-writer/references/claude-code/dynamic-context.md

@@ -0,0 +1,16 @@
+# Claude Dynamic Context Injection
+
+Load this when the skill uses Claude Code shell preprocessing with ``!`command` `` or fenced ````!` blocks.
+
+## Use this file for
+
+- stable, high-signal preprocessing
+- small dynamic snippets that are cheaper than adding a full script
+
+## Use sparingly
+
+1. Only inject output that is stable, high-signal, and cheap.
+2. Never inject large or noisy output.
+3. Prefer a normal script or tool call when that is easier to reason about.
+
+Treat this as preprocessing, not model behavior, and add portability notes because it is Claude Code-specific.

package/src/internal-skills/skill-writer/references/claude-code/frontmatter-and-invocation.md

@@ -0,0 +1,33 @@
+# Claude Frontmatter And Invocation
+
+Load this when the skill needs Claude Code-specific frontmatter or invocation control.
+
+## Use this file for
+
+- extra trigger metadata
+- invocation visibility rules
+- skill-scoped model or effort overrides
+- path or shell activation controls
+
+## Relevant fields
+
+| Field | Purpose | Notes |
+|-------|---------|-------|
+| `when_to_use` | extra trigger context for Claude | additive only; keep trigger-rich language in `description` |
+| `disable-model-invocation` | only the user can invoke | good for side-effect-heavy workflows |
+| `user-invocable` | hide from `/` menu and let Claude invoke | good for passive background knowledge |
+| `allowed-tools` | pre-approve tools while skill is active | provider-specific |
+| `model` | skill-scoped model override | provider-specific |
+| `effort` | skill-scoped effort override | provider-specific |
+| `paths` | glob-based activation limits | provider-specific |
+| `shell` | shell for `!` preprocessing | provider-specific |
+
+## Invocation rules
+
+1. If Claude should not decide when to run the skill, set `disable-model-invocation: true`.
+2. If the skill is not a meaningful command for humans, consider `user-invocable: false`.
+3. Keep trigger-rich language in `description` even if `when_to_use` is present.
+
+## Portability rule
+
+When using any Claude-specific field, say why it is necessary and note that it is not portable Agent Skills behavior.

package/src/internal-skills/skill-writer/references/claude-code/hook-backed-skills.md

@@ -0,0 +1,28 @@
+# Claude Hook-Backed Skills
+
+Load this when the skill uses Claude Code hooks for deterministic enforcement around tool or lifecycle events.
+
+## Use this file for
+
+- pre-tool validation for risky commands
+- post-edit formatting or linting
+- scoped guardrails around specific tool events
+
+## Required contract
+
+1. Narrow event and matcher scope.
+2. Explicit side-effect boundaries.
+3. Fallback behavior when hooks are unavailable.
+4. Security note for shell execution, path handling, and sensitive files.
+
+## Security rules
+
+1. Command hooks run with full user permissions.
+2. Validate and sanitize inputs.
+3. Use absolute paths for scripts inside the hook definition.
+4. Avoid sensitive files such as `.env`, `.git/`, and keys.
+5. Test hooks before treating them as trusted enforcement.
+
+## Async note
+
+Async hooks cannot block the action that triggered them; they are not a substitute for synchronous validation.

package/src/internal-skills/skill-writer/references/claude-code/subagent-fork-skills.md

@@ -0,0 +1,22 @@
+# Claude Subagent-Fork Skills
+
+Load this when the skill should run in isolated context with `context: fork`.
+
+## Use this file for
+
+- self-contained delegated investigations
+- isolated context for focus or permission boundaries
+- model or tool specialization where the main thread only needs a summary
+
+## Required contract
+
+1. An actionable task in the skill body.
+2. Expected return or summary contract.
+3. Explicit reason isolation is useful.
+4. Portability note because this is Claude Code-specific.
+
+## Avoid when
+
+1. The skill is passive conventions or reference material.
+2. The task depends heavily on the current conversation history.
+3. The main value comes from inline collaboration rather than delegation.