# Skill Authoring

> Creates, rewrites, and reviews Agent Skills that are concise, unambiguous, progressively disclosed, and agent-actionable. Use this skill when authoring or revising a SKILL.md, its routing description, references, assets, scripts, or reusable workflow guidance. Do not use when/for installing third-party skills, writing application code, prose docs, or commit messages.

- Skill: `jagreehal/skill-authoring` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add jagreehal/skill-authoring`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jagreehal/skill-authoring/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: jagreehal (https://skillmd.com/u/jagreehal)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/jagreehal/skill-authoring

---


# Skill Authoring

## Critical rules

- Put all activation guidance in frontmatter `description`. The body loads only after activation.
- Description formula: `[Third-person capability]. Use this skill when [triggers]. Do not use when/for [near misses].`
- Keep `description` under 1024 characters. No ellipsis (`...` / `…`) or placeholders.
- Keep `SKILL.md` roughly under 150 lines. Move conditional detail into `references/`.
- Cross-skill references use skill names only (`fn-args-deps`). Never relative paths to another skill's `SKILL.md`.
- Add a resource pointer only after its file exists. Keep references one level deep.
- Before finalizing, read [references/quality-checklist.md](references/quality-checklist.md) and run the validators below.

## Workflow

1. Record two or three realistic tasks (inputs, outputs, success criteria) and two or three strong near misses.
2. Inspect nearby skills so you reuse boundaries instead of duplicating policy.
3. Write the `description` before the body. Include realistic phrasing and material near misses.
4. Build the post-activation body: Critical rules → Workflow → Resources → Validation → Constraints.
5. Before drafting long examples or type-specific shapes, read [references/skill-types.md](references/skill-types.md) and [references/examples.md](references/examples.md).
6. Create `references/`, `assets/`, or `scripts/` when detail is reusable or would crowd the main file.
7. Compress: shorten wording, split overloaded bullets, delete duplicated When-to-Use from the body.
8. Validate (see Validation). Revise only evidence-backed gaps.

## Resources

- [references/quality-checklist.md](references/quality-checklist.md) — evidence checklist before publish. Read before finalizing.
- [references/skill-types.md](references/skill-types.md) — reference / technique / discipline / pattern shapes. Read when choosing structure.
- [references/examples.md](references/examples.md) — WRONG vs CORRECT descriptions, progressive disclosure, anti-patterns. Read when drafting or reviewing.

## Validation

```sh
node scripts/validate-skill-metadata.mjs path/to/skill
node scripts/validate-skill-links.mjs path/to/skill
```

- Expect 0 metadata policy violations and 0 broken local links.
- Confirm no body `## When to Use` and no `](../.*/SKILL.md)` cross-skill paths.
- Confirm `name` matches directory; bump `version` on change.

## Constraints

- One coherent job per skill. Do not broaden scope because related guidance exists.
- Do not encode one-off preferences. Prefer the smallest durable correction.
- Pair with `documentation-standards` for prose quality and `testing-strategy` for evaluation approaches.
- Discipline skills should still use Iron Law / red-flags / rationalization counters (see skill-types).