| name | authoring-org-skills |
| description | Authors, validates and packages a claude.ai Organization Skill — the intake questions, the trigger and scope exercises, then lint, pack and verify against measured platform constraints. Reach for this when someone wants to publish a Skill to their organization, or when an upload was rejected and the reason is unclear. |
| allowed-tools | Read, Write, Edit, Bash, Glob, Grep |
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
- Who is the audience? Every member of the org sees this in their system prompt.
- 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.
- What data does it need, and does a connector exist? If not, the data has to be
maintained somewhere the skill can reach.
- 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.
- 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
orgskill lint <skill-dir>
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
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.
