authoring-org-skills

# authoring-org-skills Gets a non-expert admin from *"I want everyone's drafts grounded in our own data"* to a bundle that installs. The constraints are enforced by code, not by this document — `schemas/org-skill-rules.json` is the contract and `scripts/orgskill.py` is the enforcer. > **This is a Claude *Code* skill, and it does not fully conform to the rules it > enforces.** Organization Skills are a different artifact with a different packaging > contract, so `FM11`/`FM12` (frontmatter keys), the archive rules, and the body-length > guidance do not literally apply here — this file carries `allowed-tools`, which an > Organization Skill may not. What does transfer, and is honoured: a description that > names both capability and trigger, third person throughout, and progressive disclosure. > Saying so beats implying a self-conformance that is not there. ## Two entry points, deliberately not chained | You want | Start at | Needs | |---|---|---| | **Ship a skill** | §1 → §6 | nothing else | | **Judge a skill you already have** | the rubric lane | Phase 6 | The seam between them is real. A quarterly admin ships and leaves; the rubric is the deluxe version and is a **separate invocation**. Do not chain them by default. --- ## 1. Intake — five questions, before any file exists 1. **Who is the audience?** Every member of the org sees this in their system prompt. 2. **What situations should trigger it?** Not the capability — the *moments*. Keep the list; §2 needs it, and it is the ground truth for the invocation checks later. 3. **What data does it need**, and does a connector exist? If not, the data has to be maintained somewhere the skill can reach. 4. **How much latitude does Claude have?** The degrees-of-freedom call (S6): a compliance-shaped task wants a checklist, a judgement-shaped task wants principles and a worked example. Getting this backwards is the most common cause of a skill that is technically correct and useless. 5. **Who reviews it?** With org sharing on there is no approval step (S10). If the answer is "nobody", that is the answer — write it down. ## 2. The trigger-enumeration exercise Write **six to ten concrete situations**, in the words a colleague would use. > *"A customer replies asking why they were charged twice."* > *"A renewal is 30 days out and the account has an open ticket."* Then compress them into a description that **names both the capability and the trigger** (S3 — the description is the discovery mechanism, and it is all Claude sees when choosing among the org's other skills). Keep the list; it is not scaffolding. ⛔ **A description that names only the capability is the single most common defect in the corpus.** `DS01` measures it, and its fire rate is printed with every finding. ## 3. The scope-negation exercise Write **what this is NOT for, and what to use instead.** Three lines is enough. This is the cheapest quality lever available. It costs a sentence, it prevents the skill firing on adjacent work, and — because selection is relative to the whole field of skills in the org — it is the only part of scope the author can actually control. ## 4. Layout — what stays in the body Body: the procedure someone follows. Everything else becomes a bundled file, referenced by a relative link, with a table of contents if it is long (S6). Bundled files cost nothing until they are read, so the split is close to free. Two rules that are not obvious: - **Avoid deeply nested references** (S6). A file that points at a file that points at a file is one nobody reaches. - **A bundled file must actually be in the archive.** `ZP08` checks the archive, not the disk, because a link that resolves in the working tree and not in the bundle fails only in production. Start from `templates/skeleton/`. ## 5. lint → fix → pack → verify ```bash orgskill lint <skill-dir> # add --run-record <path> for a quarantine orgskill pack <skill-dir> -o <out.zip> orgskill verify <out.zip> ``` `lint` exits 0 clean, 2 on a finding or a parse ambiguity — never 1, because a non-blocking exit is the defect class this tool exists to avoid. **FAIL blocks; WARN informs.** A warn is a heuristic, and every advisory finding prints the rate it fired at and the population it was measured on, so it can be discounted on sight rather than obeyed on reflex. **Refusals `R1`–`R4` have no override.** No flag, no environment variable, no config key. If one fires, read `reference/refusals.md`: the first remedy is to **paraphrase**, which resolves most cases in one sentence and needs no reviewer. `verify` re-opens the archive and re-runs the linter on the **extracted** tree. It shares no state with `pack` — a packer that checks its own output is checking its own intent. ## 6. Ship it, and read the disclosure Upload at **Organization settings → Skills**. Provisioning is immediate and org-wide. ⛔ **Whether the skill FIRES is not testable here, and this tool will never tell you it will.** Selection is relative to the whole field of skills installed in the target org — which the author does not have and cannot simulate (S18). A clean lint says the archive is well-formed. It says nothing about whether the skill is ever chosen, whether it is useful, or whether the platform's scanner will accept it. That scanner's verdict is unappealable, it re-fires on every edit, and it is why the advice is to **attempt the upload early rather than on a deadline**. ## Reference - [`reference/refusals.md`](reference/refusals.md) — what the studio will not emit, and the four-condition quarantine path. - [`reference/platform-constraints.md`](reference/platform-constraints.md) — the evidence file. Rules whose tier is derived read it; the zip-root question is still open there, and settling it is one upload each. - [`schemas/org-skill-rules.json`](schemas/org-skill-rules.json) — every rule, its tier, its claim, and for advisories its measured fire rate and population. - [`templates/skeleton/`](templates/skeleton/) — the starting tree. - [`templates/examples/`](templates/examples/) — two skills authored through this procedure, in different domains, both lint-clean and verified. Related, and not reimplemented here (S13): `refine-to-rubric` for the judged lane, `prompt-pattern-library` for prompt shapes, and the `prompt-engineer` agent for wording.