@its-thepoe/write-a-skill 1.0.0

package/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: write-a-skill
+description: >-
+  Authors or improves an Agent Skill (SKILL.md + optional reference/examples/scripts)
+  with correct structure, frontmatter, and trigger phrases. Use when the user asks to
+  create, write, add, refine, or scaffold a skill, slash command, or prompt pack; or
+  to decide skill vs always-on rules (.cursor/rules, CLAUDE.md, AGENTS.md).
+argument-hint: "[topic or skill name]"
+---
+
+# Write a skill
+
+## One folder per skill
+
+**Yes — exactly one directory per skill.** That folder is the whole skill: put **`SKILL.md` in the root of that folder**, plus optional siblings (`reference.md`, `examples.md`, `scripts/`, `package.json`, `LOVABLE.md`, etc.). Do not scatter one skill across multiple folders.
+
+**Plugin bundles (optional):** some teams ship many skills inside a single installable plugin (e.g. `plugins/<plugin-id>/skills/<skill-name>/`). Same rule applies: **one folder per skill**, with `SKILL.md` inside. See [reference.md](reference.md#plugin-or-monorepo-layout).
+
+## This repo (many skills)
+
+Put each skill in its **own folder at the repo root** (kebab-case; **`name` in frontmatter** should match the folder where products require it — some allow `ce:plan`-style `name` with a different folder name; follow your target product docs). Same folder copies or symlinks into Cursor, Claude Code, Windsurf, Gemini / Antigravity, etc.
+
+```text
+<this repo>/
+  README.md
+  LICENSE
+  write-a-skill/
+    SKILL.md
+    reference.md
+    package.json        # optional; only if you publish this skill to npm
+  another-skill/
+    SKILL.md
+```
+
+**Use a skill locally:** copy or symlink `<repo>/<skill-name>/` into that product’s skills directory (see table below). Example — install `write-a-skill` for your user account on every tool you use:
+
+```bash
+SKILL_SRC="/path/to/this/repo/write-a-skill"
+ln -sf "$SKILL_SRC" ~/.cursor/skills/write-a-skill
+ln -sf "$SKILL_SRC" ~/.claude/skills/write-a-skill
+mkdir -p ~/.config/opencode/skills
+ln -sf "$SKILL_SRC" ~/.config/opencode/skills/write-a-skill
+ln -sf "$SKILL_SRC" ~/.codeium/windsurf/skills/write-a-skill
+# Gemini / Antigravity: confirm current path in product docs, then same pattern, e.g.
+# ln -sf "$SKILL_SRC" ~/.gemini/skills/write-a-skill
+```
+
+Reload or restart each agent after adding a skill.
+
+---
+
+## Install this skill (copy the folder)
+
+Same folder works for any agent that loads **Agent Skills** (`SKILL.md` + frontmatter). Typical paths:
+
+| Product | Personal (all projects) | Project-only |
+|--------|-------------------------|--------------|
+| **Cursor** | `~/.cursor/skills/write-a-skill/` | `<repo>/.cursor/skills/write-a-skill/` |
+| **Claude Code** | `~/.claude/skills/write-a-skill/` | `<repo>/.claude/skills/write-a-skill/` |
+| **OpenCode** | `~/.config/opencode/skills/write-a-skill/` | `<repo>/.opencode/skills/write-a-skill/` |
+| **Windsurf** | `~/.codeium/windsurf/skills/write-a-skill/` | `<repo>/.windsurf/skills/write-a-skill/` |
+| **Antigravity / Gemini** | Often under `~/.gemini/skills/` or `~/.gemini/antigravity/skills/` — confirm in current docs | `<repo>/.agent/skills/write-a-skill/` (common) |
+
+Each location must contain this directory with `SKILL.md` inside. Restart or reload the agent if it does not pick up a new skill immediately.
+
+**From npm:** after `npm install write-a-skill`, copy or symlink `node_modules/write-a-skill/` to one of the paths above (folder must contain `SKILL.md`).
+
+**Lovable:** does not use agent skill folders. This skill is for authoring **Agent Skills**; no `LOVABLE.md` is expected here. UI skills that support Lovable add **`LOVABLE.md`** next to `SKILL.md` (examples elsewhere: accessibility-review, design-engineering, family-taste).
+
+For the open standard, see [Agent Skills](https://agentskills.io). For Claude Code–only options (subagents, `allowed-tools`, `context: fork`, `$ARGUMENTS`), see [Claude Code skills](https://code.claude.com/docs/en/skills). When authoring for **many agents**, prefer portable frontmatter (`name`, `description`, optional `argument-hint`) and add tool-specific keys only where needed.
+
+---
+
+## Step 1 — Establish context (ask if unclear)
+
+**Audience**
+
+- Engineer (Cursor, Claude Code, Windsurf, OpenCode, Antigravity, etc.) → primary deliverable is `skill-name/SKILL.md` (+ optional files).
+- Non-technical or web builders (Claude.ai, v0, etc.) → add a copy-paste **prompt pack** (no repo-only paths). For **Lovable**, optional **`LOVABLE.md`** in the skill folder (not every skill needs one). See [reference.md](reference.md#prompt-pack-non-repo-users).
+
+**Skill vs always-on rule**
+
+- If the answer is “what should the agent *always* follow?” → prefer **rules/memory**: `.cursor/rules/`, `CLAUDE.md`, or `AGENTS.md` — not an invoked skill. Say that clearly and offer a short rule snippet instead.
+- If the answer is “what should run when asked / when this task appears?” → **skill**.
+
+**Greenfield vs brownfield vs recurring**
+
+- One-time setup → setup flow in the skill.
+- Migration → migration steps + verification.
+- Ongoing workflow → checklist + idempotent steps.
+
+---
+
+## Step 2 — Avoid duplication
+
+Before drafting:
+
+- Extend or link an existing skill instead of cloning.
+- If only a small section fits another skill, add a heading there and link out.
+- Put long tables, full templates, and huge checklists in [reference.md](reference.md), not in this file.
+
+---
+
+## Step 3 — Write the skill
+
+1. **Folder**: `skill-name/` in kebab-case; `name` in frontmatter matches product rules (often same as folder; max **64** chars, lowercase and hyphens where required).
+2. **Required file**: `SKILL.md` with YAML frontmatter (`name`, `description`) and concise body.
+3. **Optional siblings**: `reference.md`, `examples.md`, `scripts/`, **`references/`** (schemas, templates, catalogs — link from `SKILL.md` in one hop). See [reference.md](reference.md#supporting-files-beyond-referencemd).
+
+**Router-quality `description` (most important)**
+
+- Concrete **what** + **when**: real phrases users say.
+- **Guards and handoffs:** when the model should **prefer another skill or step first** (“if ambiguous, use brainstorm first”), or **not** invoke this skill (“side-effect deploys: manual only” via docs + frontmatter on Claude Code).
+- Avoid fluff: not “helps with”, “handles”, “manages”.
+- Aim under ~500 characters if possible; hard max **1024** where enforced. See [reference.md](reference.md#description-with-guards-and-handoffs).
+
+**Leaf vs orchestrator**
+
+- **Leaf skill:** one clear job (e.g. format a commit message).
+- **Orchestrator skill:** phased workflow that delegates to subagents, other skills, or parallel tasks. Split into multiple skills if phases are independently useful or descriptions become vague. Details: [reference.md](reference.md#leaf-vs-orchestrator-skills).
+
+**Arguments and modes (when slash args matter)**
+
+- Use **`argument-hint`** for autocomplete. In Claude Code, **`$ARGUMENTS`**, **`$0` / `$1`**, and optional **mode tokens** (e.g. `mode:report-only`) in the body can steer one command with multiple behaviors. Full pattern: [reference.md](reference.md#arguments-modes-and-claude-code-placeholders).
+
+Full template, good/bad examples, invariants, and review checklist: [reference.md](reference.md).
+
+---
+
+## Step 4 — Review before done
+
+**Structure**
+
+- [ ] `SKILL.md` stays focused; heavy detail lives in `reference.md`, `examples.md`, or `references/`
+- [ ] Directory name matches `name` in frontmatter (per product rules)
+- [ ] No stale dates or “before August 20xx” unless in a clearly marked legacy section
+
+**Description**
+
+- [ ] States capability in the first sentence
+- [ ] Includes “Use when …” **or equivalent** trigger coverage
+- [ ] Adds **handoffs or guards** when mis-routing would waste time (see reference)
+- [ ] No vague-only wording
+
+**Content**
+
+- [ ] Steps are ordered and verifiable
+- [ ] **Invariants** stated where it matters: paths never to delete, “never run X here”, quality gates (see [reference.md](reference.md#invariants-never-rules-and-quality-gates))
+- [ ] Links to team standards only if paths exist in *this* repo (or say “if present”)
+- [ ] Examples are concrete
+
+**Distribution**
+
+- [ ] User knows whether to install under personal vs project path (table above)
+- [ ] If non-repo users need it, prompt pack exists (see reference)
+- [ ] If the skill should work on **Lovable**, add or update **`LOVABLE.md`** in the skill folder (condensed if Knowledge **10k** limit applies); most skills do not need this
+
+**Multi-product (optional)**
+
+- [ ] If the skill references a **blocking user question**, note how other CLIs expose the same idea (see [reference.md](reference.md#cross-product-interactive-prompts)) — or keep wording product-agnostic

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@its-thepoe/write-a-skill",
+  "version": "1.0.0",
+  "description": "Agent Skill (SKILL.md + reference) for authoring and improving portable Agent Skills across Cursor, Claude Code, OpenCode, Windsurf, and similar tools.",
+  "license": "MIT",
+  "keywords": [
+    "agent-skills",
+    "cursor",
+    "claude-code",
+    "skill",
+    "prompt",
+    "agentskills"
+  ],
+  "files": ["SKILL.md", "reference.md", "package.json"],
+  "exports": {
+    ".": "./SKILL.md",
+    "./skill": "./SKILL.md",
+    "./SKILL.md": "./SKILL.md",
+    "./reference": "./reference.md",
+    "./reference.md": "./reference.md"
+  }
+}

package/reference.md

@@ -0,0 +1,280 @@
+# Write a skill — reference
+
+## Folder structure
+
+```text
+skill-name/
+├── SKILL.md              # Entry point — required
+├── reference.md          # Long tables, templates, extra checklists (optional)
+├── examples.md           # Before/after samples (optional)
+├── references/           # Optional: schemas, templates, catalogs (see below)
+│   ├── findings-schema.json
+│   └── ...
+└── scripts/              # Validation or scaffolding only (optional)
+```
+
+**This repo:** each skill is a **top-level folder** next to `README.md` (e.g. `write-a-skill/`, `another-skill/`). Copy or symlink that folder into each agent’s global skills path (Cursor, Claude Code, Windsurf, Gemini / Antigravity — see `SKILL.md` table).
+
+Keep `SKILL.md` short; move bulk here.
+
+---
+
+## Plugin or monorepo layout
+
+When publishing a **Claude Code plugin** (or similar), skills often live under:
+
+```text
+plugins/<plugin-id>/
+├── .claude-plugin/       # plugin manifest (product-specific)
+├── skills/
+│   └── <skill-name>/
+│       └── SKILL.md
+├── agents/               # optional: subagent definitions
+├── AGENTS.md             # optional: project memory for the plugin
+└── .mcp.json             # optional: bundled MCP
+```
+
+The **one-folder-per-skill** rule is unchanged: each `skills/<skill-name>/` directory is a single skill. Names may be **namespaced** by the product (e.g. `plugin-id:skill-name` in menus).
+
+---
+
+## Supporting files beyond `reference.md`
+
+For heavier skills, colocate machine- or human-facing artifacts and **link them from `SKILL.md`** with “what this file is / when to load it”:
+
+| Artifact | Use case |
+|----------|----------|
+| `references/*.md` | Persona catalogs, diff rules, long policy |
+| `references/*.json` | JSON schema for subagent outputs, merge pipelines |
+| `references/*-template.md` | Subagent prompt shells, output report shells |
+| `examples/*` | Expected output shapes |
+
+Avoid dumping 2k+ lines into `SKILL.md` without navigation; mature orchestration skills use an **index body + deep files**.
+
+---
+
+## Leaf vs orchestrator skills
+
+**Leaf**
+
+- Single outcome, narrow triggers.
+- Body is a short ordered checklist or policy.
+- Example: “write conventional commit message from diff”.
+
+**Orchestrator**
+
+- Phases (research → decide → write → handoff), **parallel** sub-tasks, or fan-out to **subagents**.
+- Body states **which steps run when**, what can run in **parallel**, and **stop conditions**.
+- Risk: one giant skill with vague `description` → wrong invocations. Mitigation: **split phases into separate skills** when each phase is useful alone, or tighten `description` with **guards** (see below).
+
+Orchestrators still benefit from **invariants** and **structured outputs** (e.g. JSON schema) when merging subagent results.
+
+---
+
+## Description with guards and handoffs
+
+The `description` is the **router**. Besides “use when …”, strong skills add:
+
+1. **Handoff:** “Prefer **\<other skill>** when …” (ambiguous scope, missing inputs, wrong phase).
+2. **Guard:** “Do not use for …” or “Requires … before running” (only when it prevents real failures).
+
+**Example (pattern only)**
+
+```yaml
+description: >
+  Turns an approved requirements doc into a technical implementation plan with
+  file-level traceability. Use when the user says "plan this", "technical plan",
+  or "break down implementation". Prefer skill "brainstorm-requirements" first
+  when goals or scope are still unclear. Does not implement code or run tests —
+  use "execute-plan" for implementation.
+```
+
+Stay within product **length limits** (~1024 chars where enforced). Prioritize triggers + the single most important guard.
+
+---
+
+## Arguments, modes, and Claude Code placeholders
+
+[Claude Code skills](https://code.claude.com/docs/en/skills) support:
+
+- **`argument-hint`:** shown during `/` completion (e.g. `[pr-url] [mode:report-only]`).
+- **`$ARGUMENTS`:** full remainder after `/skill-name`.
+- **`$0`, `$1`, …** or **`$ARGUMENTS[0]`:** positional args.
+- **Mode tokens:** conventionally embed keywords in args (e.g. `mode:autofix`) and strip them in the body before interpreting the rest — yields **one slash command, multiple behaviors**.
+
+Document in the skill body: **parse order**, **mutual exclusion**, and **side-effect rules** per mode.
+
+Other products may not support these placeholders; for **portable** skills, keep critical behavior in prose and treat `$…` as progressive enhancement for Claude Code.
+
+---
+
+## Cross-product interactive prompts
+
+If a step requires **blocking user input**, name the mechanism per product where you know it, e.g.:
+
+- Claude Code: interactive question / `AskUserQuestion`
+- Other CLIs: as documented
+
+Otherwise stay **product-agnostic**: “Ask one focused question; wait for an answer before continuing.”
+
+---
+
+## Invariants, never-rules, and quality gates
+
+**Invariants** — state what must never be violated:
+
+- Paths or artifacts that **must not** be deleted or “cleaned up” by subagents.
+- “Never run migrations in this skill — planning only.”
+
+**Never-rules** — short bullets the agent must not do (reduces compound errors in long playbooks).
+
+**Quality gates** — before delivering output, confirm:
+
+- Findings are actionable (not “consider improving…” with no concrete next step).
+- Severities match impact.
+- Line refs / file paths were verified if cited.
+
+Use these in **orchestrator** and **review**-style skills especially.
+
+---
+
+## SKILL.md template
+
+Use this as a starting point. Most agents accept `name` + `description` (see [Agent Skills](https://agentskills.io)). Claude Code may also use `disable-model-invocation`, `allowed-tools`, `context: fork`, etc. — see [Claude Code skills](https://code.claude.com/docs/en/skills). For skills shared across Cursor, Windsurf, OpenCode, Antigravity, and Claude Code, keep frontmatter minimal unless a key is widely supported.
+
+```yaml
+---
+name: skill-name
+description: >
+  One sentence: what capability this adds. When to use: user phrases and tasks.
+  Prefer skill "other-skill" when [guard condition]. Not for [anti-pattern].
+argument-hint: "[optional-args]"
+---
+
+# Human-readable title
+
+## When to use this skill
+
+[Who invokes it, project state, boundaries. Handoffs to sibling skills.]
+
+## Standards (if any)
+
+Before starting, read if they exist in this repo:
+
+- docs/contributing.md
+- AGENTS.md
+
+## Workflow
+
+1. …
+2. …
+
+## Invariants (if any)
+
+- Never …
+- Do not delete …
+
+## Checklist
+
+- [ ] …
+- [ ] …
+
+## Additional resources
+
+- [reference.md](reference.md) — …
+- [references/schema.json](references/schema.json) — …
+```
+
+---
+
+## Description rules
+
+The **description** is what the model uses to decide whether to load the skill. Make it unambiguous.
+
+**Good**
+
+> Sets up a new frontend repo with shared tokens, folder layout, and UI primitives. Use when starting a greenfield frontend, scaffolding an app, or when the user says: new project, bootstrap, design tokens, component library, or init frontend.
+
+**Bad**
+
+> Helps with frontend setup and the design system.
+
+---
+
+## Prompt pack (non-repo users)
+
+If the audience does not have the repo, add `prompts/skill-name.md` (or a single section in your docs) with:
+
+- One copy-paste block with the rules inlined (no `see ../foo` only paths).
+- One line: when to use it.
+- No dependency on local-only files unless you also paste their content.
+
+---
+
+## Lovable (optional; not every skill)
+
+[Lovable](https://lovable.dev) uses [Knowledge](https://docs.lovable.dev/features/knowledge) and root **`AGENTS.md`** / **`CLAUDE.md`** on GitHub-linked projects — not `SKILL.md` folders.
+
+Skills that support Lovable add **`LOVABLE.md`** beside `SKILL.md`. Keep each `LOVABLE.md` under the **10,000-character** Knowledge limit where possible, or point `AGENTS.md` at the full `SKILL.md` in the synced repo.
+
+---
+
+## Full review checklist
+
+**Structure**
+
+- [ ] `SKILL.md` under ~100–200 lines of *instruction* unless it is a deliberate, well-structured orchestrator; split detail to this file or `references/`
+- [ ] Folder name is kebab-case and matches `name` in frontmatter (per product)
+- [ ] No time-sensitive information baked in without a “legacy” label
+
+**Description**
+
+- [ ] Specific trigger words or scenarios
+- [ ] First sentence = capability; when to use is obvious
+- [ ] Guards or handoffs if mis-routing is costly
+- [ ] Under 1024 characters where enforced
+
+**Content**
+
+- [ ] Greenfield vs brownfield called out if it changes the workflow
+- [ ] Final checklist the agent can tick
+- [ ] Examples are concrete (not lorem ipsum)
+- [ ] Invariants / never-rules if the skill is high-stakes or delegates to subagents
+
+**Distribution**
+
+- [ ] Documented install paths for target agents (global vs project; see repo `README.md` for a path table)
+- [ ] Prompt pack created if non-repo or non-engineering tools need the same behavior
+- [ ] If Lovable matters for this skill: `LOVABLE.md` added in the skill folder
+
+---
+
+## Claude Code extras (optional frontmatter)
+
+Examples you can add to `SKILL.md` frontmatter when using Claude Code only:
+
+```yaml
+disable-model-invocation: true   # only you invoke with /skill-name
+user-invocable: false            # hide from / menu; model-only
+allowed-tools: Read, Grep, Glob  # restrict tools while skill is active
+context: fork                    # run in subagent
+agent: Explore                   # with context: fork
+```
+
+Other agents typically ignore keys they do not support; keep portable skills to `name` and `description` (and optional `argument-hint`) when one folder is shared across many products.
+
+**Invocation recap (Claude Code)**
+
+| Pattern | Effect |
+|---------|--------|
+| Default | You and the model can invoke; description helps auto-routing |
+| `disable-model-invocation: true` | Manual `/skill` only; use for risky or user-gated workflows |
+| `user-invocable: false` | Model can load; user doesn’t see a friendly `/` action |
+
+---
+
+## Further reading (examples)
+
+Mature open-source plugin layouts with phased skills, persona catalogs, and structured review pipelines — useful for **orchestration inspiration**, not mandatory conventions:
+
+- [EveryInc/compound-engineering-plugin](https://github.com/EveryInc/compound-engineering-plugin) (`plugins/compound-engineering/skills/`)