{"id":16696,"plugin_id":"plugins_6a630817fcdc8191a6e0114bbd61bc33","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T23:13:39.849Z","digest":"26c301268f386d2179caa360acd5dc4f9ede70e23bbc7570ca110897555555b5","against":null,"payload":{"description":"Create, adopt, review, or refine selected area handbooks, coordinating practices, checks, Playbooks, and templates. Use when the user asks to shape working methods or assess a handbook. Review requests stay read-only; ordinary work does not itself request handbook changes or Playbook creation.","included_files":[{"relative_path":"agents/openai.yaml","size_in_bytes":225},{"relative_path":"assets/check.md","size_in_bytes":821},{"relative_path":"assets/handbook-readme.md","size_in_bytes":1946},{"relative_path":"assets/playbook.md","size_in_bytes":1076},{"relative_path":"assets/practice.md","size_in_bytes":634},{"relative_path":"references/CONTRACT.md","size_in_bytes":15762},{"relative_path":"references/checks.md","size_in_bytes":2749},{"relative_path":"references/methodology.md","size_in_bytes":10863},{"relative_path":"references/playbooks.md","size_in_bytes":3574},{"relative_path":"references/practices.md","size_in_bytes":2481},{"relative_path":"references/review.md","size_in_bytes":6012},{"relative_path":"references/setup.md","size_in_bytes":3516}],"name":"shape-handbook","skill_md_contents":"---\nname: shape-handbook\ndescription: Create, adopt, review, or refine selected area handbooks, coordinating practices, checks, Playbooks, and templates. Use when the user asks to shape working methods or assess a handbook. Review requests stay read-only; ordinary work does not itself request handbook changes or Playbook creation.\n---\n\n# Shape Handbook\n\nBefore applying this skill, read the full [Trellis methodology](references/methodology.md).\n\nHelp the selected handbook improve a future contributor's decisions about the\narea's work. Choose the smallest coherent change that serves the requested outcome;\nthe user need not divide a concern into separate practice, check, and template tasks.\n\n## Follow the requested intent\n\nA request to create, adopt, or refine a handbook authorizes the corresponding\nchanges. A review request asks for findings and remains read-only. If the user asks\nfor review and fixes, apply the requested fixes within scope. Do not require a\nspecial invocation, a named mode, or repeated confirmation of existing authority.\n\nCreating a Playbook requires a request to preserve that procedure, or the user's\nacceptance of a proposal that clearly includes it. Broad improvement, a review\nfinding, or a learning recommendation alone does not authorize inventing Playbooks.\nAn intended procedure can be written without prior successful use; creating it\ndoes not demonstrate its effectiveness or carry it out.\n\n## Resolve the handbook and its owners\n\nResolve the workspace and owning area from the request and applicable project\ninstructions. A workspace is an identified working directory, not necessarily a\nGit repository. Do not select the current directory when plausible alternatives\nwould materially change scope. Each handbook lives at `<area>/handbook/`; its\nparent is the owning area and must be inside the selected workspace.\nVerify that the workspace and owning area already exist as directories. Never\ncreate their missing parents: every setup write must remain inside the handbook.\n\nRead an existing README's single marker to check its declared workspace:\n\n```html\n<!-- trellis:handbook {\"format\":1,\"workspace\":\"../..\"} -->\n```\n\nThe workspace path is relative to the handbook; use `..` for a workspace-root\nhandbook. Verify physical locations against the selected scope. The marker does\nnot grant authority over another workspace or ownership of every existing file.\nResolve each handbook separately in a multi-handbook request.\n\nInspect the requested area, applicable shared guidance, and explicitly selected\nevidence. Do not search unrelated areas merely because they share a workspace.\nRoot and nested handbooks can both apply; ancestry alone does not settle conflicts.\nLink shared rules at their owners, explain deliberate local specializations, and\nraise consequential unresolved conflicts.\n\nThe handbook preserves how people do and review the work. Keep current plans,\ndrafts, decisions, and results in the area's working files. Judge mixed documents\nstatement by statement and link to the authoritative files for the work.\nExtracting a practice does not authorize cleaning up its source outside the handbook.\n\n## Resolve decisions before encoding them\n\nIdentify the future task or decision the requested change should help. Inspect the\nselected sources first. Retrieve answers available there; ask the user about a\nmissing purpose, conflicting rule, acceptable tradeoff, or exception only when\ndifferent answers would change the guidance. Explain the concrete choice and its\nconsequence, offering grounded alternatives when useful. Do not ask the user to\ndesign the handbook or choose artifact types.\n\nAsk a small batch of consequential questions and wait for the answers before\nencoding the dependent rules. Continue independent work where possible. Existing\ninstructions or explicit owner direction can settle a choice without another\nconfirmation. If the user cannot decide, keep that dependency visibly unresolved\nor proposed; do not silently choose policy or claim the dependent work is complete.\nA clear request needs no questionnaire. Review can report an unresolved choice\nas a finding without requiring the user to settle it first.\n\n## Load the guidance needed for this request\n\n- [Setup](references/setup.md): create or adopt a handbook, or materially revise its\n  README's scope, navigation, or explanation of use. Read the README starter when\n  writing that explanation; return the setup blurb only for setup or adoption.\n- [Practices](references/practices.md): clarify working conventions, distinctions,\n  ownership, method selection, and interpretation of evidence.\n- [Checks](references/checks.md): define independently evaluable expectations and\n  their concrete verification.\n- [Playbooks](references/playbooks.md): preserve a requested procedure and its\n  optional supporting scripts.\n- [Review](references/review.md): assess a handbook and relevant sources without\n  executing its work; use the findings within any separately requested refinement.\n\nRead the relevant task references together when one concern spans artifact types. Adapt\nthe bundled assets and applicable local templates to the task.\nCreate local templates only for useful reuse. Filling headings does not establish\nsubstantive adequacy, and sample instructions do not become adopted local policy.\n\n## Keep effects within scope\n\nAll filesystem writes, including temporary files, generated support, fixtures,\ncaches, and test outputs, stay inside the selected handbook. A review-only request\nperforms no filesystem writes. For review-only work, prefer direct file reads;\nwhen shell reads are needed, use a non-login shell to avoid cache-writing login hooks.\nResolve destinations physically and inspect every parent directory in the path. Reject\ntraversal or symlinks that escape the handbook. Do not follow a handbook\nsymlink to widen the boundary. Re-read targets before overwriting, reconcile\nconcurrent changes that invalidate the edit, and preserve unrelated owner content.\n\nShow affected paths and material decisions before writing, using existing\nauthorization to proceed. Recommend required outside-handbook changes instead of\nmaking them. Never edit `AGENTS.md`, initialize Git, stage, commit, push, publish,\ninstall outside the handbook, or communicate with others through this skill.\nDo not carry out the underlying work. Supporting-script tests use only\nfixtures inside the handbook and host confinement as described in the Playbook\nreference; authoring a procedure and performing it remain separate operations.\n\n## Verify the useful result\n\nVerify local links, navigation, artifact fit, and consistency across affected\nmaterial. Then read the result as a contributor without this conversation or the\nTrellis skills: can they find what applies, make the intended decision, evaluate\nthe result, and recognize an exception or a needed owner decision? Use a bounded\nillustrative situation when it exposes ambiguity; do not perform the actual work\nor present this author review as an independent agent exercise. Check that answers\nchanged all affected guidance and that inferred rules remain proposed until adopted.\n\nSetup alone establishes an understandable entry point. Substantive authoring must\nalso supply the requested working guidance; review must explain supported findings\nor why no change is needed. Keep the README's explanation of handbook use accurate\nwhen the requested change affects it. These are completion criteria for the chosen\ntask, not a requirement to audit the whole handbook on every edit.\n\nRetain useful current rationale and evidence limits, not transcripts,\nsession identifiers, secrets, unnecessary personal data, or obsolete accounts.\nReport the decision the result now helps, changed paths or findings, checks actually\nperformed, and remaining dependencies. For a required user action, name the action,\nits destination, and what remains incomplete until it happens. Distinguish authored\nguidance, its discovery by future agents, and demonstrated use. When future reuse\nis requested, check the applicable project instructions for a discovery route;\nif absent, name a suitable instruction-file location and the user's remaining\naction without editing it. When another agent uses the\nresult, preserve those limits and distinguish your completed work from its next task.\nEach operation retains its own authority; a skill's restrictions do not revoke a\nseparately authorized task's permissions, and delegation cannot bypass the skill's\nboundaries. Structural validity and instruction quality do not establish agent\ncompliance or correctness of the work.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}