skilldrop-cli 0.16.3__py3-none-any.whl

skilldrop_cli/data/packs/skill-engineering/pack.json

@@ -0,0 +1,46 @@
+{
+  "description": "For people writing Agent Skills in their own repos: write a portable SKILL.md folder from a described task, then audit any skill for routing, portability, safety, structure and evals before you share it.",
+  "display_name": "Skill engineering",
+  "keywords": ["agent-skills", "skill-md", "claude-code", "codex", "copilot", "cursor", "kiro", "antigravity", "lint"],
+  "links": {
+    "documentation": "https://sananthanarayan.github.io/skilldrop/packs/skill-engineering/"
+  },
+  "maintainers": [
+    {
+      "name": "sananthanarayan"
+    }
+  ],
+  "first-value": {
+    "audience-posture": "technical",
+    "prerequisites": ["A task you repeat with your coding agent, and Python 3.9 or later for the lint script"],
+    "starter-task": "Turn a task you keep explaining into a skill, then review it",
+    "starter-prompt": "Make a skill that writes customer-facing release notes from the merged PRs I paste: grouped New / Improved / Fixed, breaking changes first, one line per PR with its number. We use Claude Code and Copilot, and we already have a launch-post skill for announcements. Then review the skill before I commit it.",
+    "verification": "skill-author writes a folder with SKILL.md, a template and evals, plus the install path for each of your tools, and skill-review returns a READY, FIX FIRST or REWRITE verdict with the lint script's output pasted in.",
+    "recovery": "If a skill does not activate, ask for it by name (\"use skill-author\"). If the lint script will not run, check that python3 is on your PATH; skill-review can walk the same checks by hand."
+  },
+  "requires": ["core"],
+  "journey": {
+    "when": "You keep explaining the same task to your coding agent, or you are about to share or install a skill and want to know it will route, work in every tool, and do nothing unsafe.",
+    "you_bring": [
+      "the task: what it produces and what makes a good one",
+      "three to five things you'd type to ask for it",
+      "the skills already installed next to it, and which requests belong to them",
+      "the tools your team uses: Claude Code, Codex, Copilot, Cursor, Kiro or Antigravity"
+    ],
+    "time": "20–40 minutes",
+    "steps": [
+      {
+        "skill": "skill-author",
+        "you_do": "Describe the task, the trigger phrases and the nearby skills, and answer one round of questions.",
+        "you_get": "A skill folder: SKILL.md with a routable description, steps, quality bar, boundaries and anti-patterns, plus a template, evals, and the install path for each tool."
+      },
+      {
+        "skill": "skill-review",
+        "you_do": "Point it at the folder and at the folder that holds your other skills.",
+        "you_get": "The lint script's output and a verdict with severity-tagged findings on routing, portability, safety, structure and evals, each with a fix.",
+        "decide": "Commit the skill, apply the fixes and review again, or rewrite it around one artifact."
+      }
+    ],
+    "you_end_with": "A reviewed skill that installs into each of your tools from one folder, with evals to rerun when you change it."
+  }
+}

skilldrop_cli/data/packs/skill-engineering/skills/skill-author/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: skill-author
+description: Write a new portable Agent Skill (a SKILL.md folder) from a described task, for Claude Code, Codex, Copilot, Cursor, Kiro or Antigravity in any repo — a description that leads with the artifact and ends with trigger phrases, decisive steps, a quality bar, when and when-not sections naming near-miss siblings, anti-patterns, a non-interactive rule, reference files and scripts that work in every tool, acceptance evals and trigger queries, and the install path for each tool. Use when the user says "turn this into a skill", "write a SKILL.md for…", "make an agent skill that…", or wants a repeatable task packaged so their coding agent does it the same way every time.
+---
+
+# skill-author
+
+You write one skill folder that does one task well and loads in every tool that reads
+SKILL.md. Most skills fail before the body is read: the description is vague, so the router
+never picks it, or it overlaps a sibling and wins the wrong requests. So you spend the
+interview on three things, the deliverable, the trigger phrases and the near-miss siblings,
+and decide everything else yourself. Once it's written, `skill-review` audits it.
+
+## How to respond
+
+1. **Interview once, in one message.** Take what the user already said and ask only for the
+   gaps. Suggest defaults so they can answer "go".
+
+   > 1. **The deliverable:** what file or output does the skill produce, and what makes one good?
+   > 2. **The triggers:** three to five things you'd actually type to ask for it.
+   > 3. **The near-misses:** which nearby requests should *not* use it, and which skill or tool
+   >    handles them instead? List any skills already installed next to it.
+   > 4. **The inputs:** what does the agent get (a paste, a file, a repo), and which facts must it
+   >    never make up?
+   > 5. **Tools and repo:** which tools, and where it lives. *Default: every tool, project scope.*
+
+   If the user describes a task with no single artifact ("help with our backend"), stop and
+   ask what the one output is. A skill with no artifact can't have a quality bar.
+
+2. **Check that it should be a skill.** A skill is a repeatable task with one artifact that
+   the agent loads on demand. An always-on rule for the whole repo ("use pnpm", "never edit
+   generated files") belongs in AGENTS.md, so point the user to `agents-md-generator`. A
+   one-off task needs a prompt, not a skill. Say which, and stop if it isn't a skill.
+
+3. **Name it.** Kebab-case, artifact first, at most 64 characters, identical to the folder
+   name. ✅ `release-notes-from-prs` ❌ `ReleaseHelper`, `release-notes-v2`, `my-skill`.
+
+4. **Write the description, then test it against the siblings.** Formula: artifact and use
+   case, then two or three distinguishing details, then `Use when the user …, says "…", "…".`
+   Stay under 1,024 characters (the Agent Skills specification limit); 250–600 is the useful
+   range.
+   - ✅ *"Write customer-facing release notes from merged pull requests — grouped New / Improved /
+     Fixed, internal changes dropped, breaking changes first. Use when the user pastes merged
+     PRs and says "write the release notes" or "draft the changelog"."*
+   - ❌ *"A helpful skill for release management and documentation tasks."*
+
+   For each near-miss sibling, read your description as if you were routing that sibling's
+   request. If yours would win it, add the distinguishing words now. Rules for wording are in
+   [`reference.md`](reference.md).
+
+5. **Write SKILL.md from [`templates/skill-template.md`](templates/skill-template.md)**, sections
+   in this order: title and a short intro naming the siblings, `How to respond` (numbered,
+   imperative, with asking once for missing inputs as step 1), the non-interactive line,
+   useful references, `Quality bar`, `When to use`, `When NOT to use` (each line naming the
+   alternative), `Anti-patterns to avoid`. Steps decide: pick defaults, cap questions at two,
+   and show a ✅ and a ❌ example wherever a rule could be read two ways.
+
+6. **Write the non-interactive rule.** One self-contained line: in a subagent, CI or headless
+   run, which missing inputs become an `[assumption]` line at the top of the output, and which
+   stop the run with `BLOCKED: need <X>`. Block on anything whose invention would corrupt the
+   artifact: the user's facts, numbers, names, dates.
+
+7. **Split long material out.** Keep SKILL.md under about 500 lines; 100–250 is typical. Move
+   lookup tables, long rubrics and worked examples into `reference.md` or a `references/`
+   folder, and link every file from SKILL.md with a relative link. An unlinked file is never
+   read.
+
+8. **Add a script only for work that must be exact:** arithmetic, parsing, file conversion,
+   validation. Use the standard library, read input from arguments or stdin, write to a path
+   the user gives, and exit non-zero with a clear message on bad input. Reference it both
+   ways, because only Claude Code sets `CLAUDE_SKILL_DIR`:
+
+```bash
+# Claude Code
+python3 "${CLAUDE_SKILL_DIR}/scripts/<script>.py" <args>
+# Other tools (run from the skill folder)
+python3 scripts/<script>.py <args>
+```
+
+   Run the script on a real input and on a bad one before shipping it. Any example output in
+   the skill must be pasted from a real run.
+
+9. **Write the evals.** `evals/evals.json` holds one or two realistic prompts with concrete
+   details and placeholder names (Acme, Northwind), each with five to eight assertions taken
+   from the quality bar. A skill that handles facts gets a "does not invent X" assertion.
+   `evals/eval_queries.json` holds at least four should-trigger phrasings and three or four
+   should-not-trigger near-misses, each one belonging to a sibling named in When NOT to use.
+   Shapes are in [`templates/evals.json`](templates/evals.json) and
+   [`templates/eval_queries.json`](templates/eval_queries.json).
+
+10. **Hand over the folder and the install line.** Show the file tree, then every file in full,
+    then where to put it for each of the user's tools (the table in [`reference.md`](reference.md)).
+    Close with the check: run `skill-review` on the folder, or its lint script, then one eval
+    prompt in a fresh session.
+
+**Non-interactive runs** (subagent, CI, headless): with no deliverable named, emit
+`BLOCKED: need the skill's deliverable (what file or output it produces)` and write nothing.
+Missing triggers, siblings or tools degrade to `[assumption]` lines at the top: triggers
+derived from the task wording, no siblings checked, every tool targeted.
+
+## Useful references in this skill
+
+- [`reference.md`](reference.md) — description rules with passing and failing examples, the frontmatter fields, per-tool install paths, portability rules, the script contract, and the eval formats
+- [`templates/skill-template.md`](templates/skill-template.md) — the SKILL.md skeleton, sections in order
+- [`templates/evals.json`](templates/evals.json) and [`templates/eval_queries.json`](templates/eval_queries.json) — eval shapes
+- [`examples/release-notes-skill.md`](examples/release-notes-skill.md) — a described task, the interview, and the finished folder with its real lint output
+
+## Quality bar
+
+- **The description leads with the artifact and ends with trigger phrases** a user would actually type, and is under 1,024 characters.
+- **Name equals folder name**, kebab-case, at most 64 characters.
+- **Every near-miss sibling the user named appears twice:** in a When NOT line and in a should-not-trigger query.
+- **Steps decide.** No "consider", "you might", or "depending on preference"; at most two clarifying questions.
+- **A quality bar and anti-patterns are present**, and the evals' assertions restate the quality bar as checkable claims.
+- **Portable:** every script appears in both the `${CLAUDE_SKILL_DIR}` form and the plain relative form; no absolute paths; no tool-only syntax without saying what other tools do.
+- **Nothing is invented.** Install paths come from the reference table, and example outputs come from real runs.
+
+## When to use this skill
+
+- ✅ Packaging a task the user repeats (a report, a review, a conversion) as a skill for their coding agent
+- ✅ Turning a long prompt the user keeps pasting into a SKILL.md folder
+- ✅ Writing a skill for a team repo that people use from different tools
+
+## When NOT to use this skill
+
+- ❌ Adding a skill to the skilldrop catalogue itself, with its manifest, pack and `validate.py` rules: use `contribution-wizard`
+- ❌ Auditing a skill that already exists: use `skill-review`
+- ❌ Adding evals to an existing skill without changing it: use `eval-harness-generator`
+- ❌ Repo-wide always-on rules for agents (commands, conventions, forbidden actions): use `agents-md-generator`
+
+## Anti-patterns to avoid
+
+- ❌ **The "helpful assistant" description.** "Helps with documentation tasks" matches everything and wins nothing. Name the artifact.
+- ❌ **Triggers nobody types.** "Use for knowledge management workflows." Write what the user says: "write up the meeting notes".
+- ❌ **A skill that does five things.** Five artifacts mean five quality bars. Split it.
+- ❌ **Claude-only script paths.** A script reached only through the `CLAUDE_SKILL_DIR` variable, with no plain relative path beside it, breaks in every other tool.
+- ❌ **Asking eight questions before writing anything.** Ask for the deliverable, the triggers and the siblings; default the rest.
+- ❌ **Near-miss queries invented to fill the file.** Each should-not-trigger row belongs to a real sibling the user has.
+- ❌ **A skill that calls another skill.** Skills install one at a time, so a skill that needs a sibling breaks when copied alone. Name the sibling as a next step instead.

skilldrop_cli/data/packs/skill-engineering/skills/skill-author/evals/eval_queries.json

@@ -0,0 +1,10 @@
+[
+  {"query": "Turn this prompt I keep pasting into a reusable skill for Claude Code", "should_trigger": true},
+  {"query": "Write a SKILL.md that makes our agent draft API changelogs the same way every time", "should_trigger": true},
+  {"query": "Make an agent skill that converts our Jira export into a sprint summary, it has to work in Copilot and Cursor", "should_trigger": true},
+  {"query": "Help me package our code-review checklist as a skill for Codex", "should_trigger": true},
+  {"query": "Add a new skill to the skilldrop catalogue with its manifest and catalogue row", "should_trigger": false},
+  {"query": "Review my existing skill folder and tell me if it's ready to publish", "should_trigger": false},
+  {"query": "Generate eval cases for the SKILL.md I already have", "should_trigger": false},
+  {"query": "Write an AGENTS.md for this repo so agents stop running npm when we use pnpm", "should_trigger": false}
+]

skilldrop_cli/data/packs/skill-engineering/skills/skill-author/evals/evals.json

@@ -0,0 +1,19 @@
+{
+  "skill_name": "skill-author",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Make me an agent skill for Northwind's support team: every Monday someone pastes last week's Zendesk ticket export (CSV with id, subject, tags, created_at, status) and wants a one-page digest with the top five themes, counts per theme, and three example ticket ids each. We use Codex and Cursor. We already have a skill called incident-summary for single outages and one called csat-report for survey scores. It should never make up ticket counts.",
+      "assertions": [
+        "The frontmatter name is kebab-case, leads with the artifact, and matches the folder name in the file tree",
+        "The description leads with the digest as the artifact and ends with quoted trigger phrases a support lead would type",
+        "incident-summary and csat-report each appear in a When NOT line and in a should-not-trigger query",
+        "The counts are computed by a stdlib script, and SKILL.md shows the script with both the ${CLAUDE_SKILL_DIR} form and a plain relative scripts/ path",
+        "SKILL.md has a non-interactive line that emits BLOCKED when there is no ticket export, rather than inventing counts",
+        "The quality bar and the eval assertions include that no count or ticket id appears that is not in the export",
+        "Install instructions give .agents/skills/ for Codex and the .cursor/skills/ plus .cursor/rules/ pattern for Cursor",
+        "The interview asks at most two questions, because the deliverable, the tools and the siblings were already given"
+      ]
+    }
+  ]
+}

skilldrop_cli/data/packs/skill-engineering/skills/skill-author/examples/release-notes-skill.md

@@ -0,0 +1,185 @@
+# Example: from a described task to a finished skill
+
+## Input
+
+> Every release I paste our merged PRs into the chat and ask for customer-facing notes, and
+> every time I have to explain the format again. Can you make this a skill? We use Claude Code
+> and Copilot at Acme. We already have `sprint-status` and `launch-post` skills in the repo.
+
+## The interview (one message)
+
+The user had already given the tools, the repo and two siblings, so the interview asked only
+for the gaps:
+
+> Before I write it, three things. Reply "go" to take the defaults.
+> 1. **What makes the notes good?** *Default: grouped New / Improved / Fixed, breaking changes
+>    first, one line per PR in user terms with the PR number, internal changes dropped.*
+> 2. **What would you type to ask for it?** *Default: "write the release notes", "draft the
+>    changelog for v2.4", "what shipped this sprint, for customers".*
+> 3. **Anything it must never make up?** *Default: changes or benefits that no PR states.*
+
+The user replied: "go, and breaking changes need a 'what to do' line."
+
+## Decisions made without asking
+
+- **It is a skill:** a repeatable task with one artifact. Not an AGENTS.md rule.
+- **Name:** `release-notes-from-prs`. The input is in the name because "release notes" alone
+  would also claim roadmap-driven announcements, which belong to `launch-post`.
+- **No script.** Sorting and rewriting PR titles is judgment, not arithmetic.
+- **Boundaries:** the sprint report goes to `sprint-status`, the announcement to
+  `launch-post`. Each appears in When NOT to use and as a should-not-trigger query.
+- **Install:** `.claude/skills/` for Claude Code, which Copilot CLI also reads. Add
+  `.github/skills/` for Copilot in the editor.
+
+## Output
+
+```
+.claude/skills/release-notes-from-prs/
+├── SKILL.md
+├── templates/release-notes.md
+└── evals/
+    ├── evals.json
+    └── eval_queries.json
+```
+
+### `SKILL.md`
+
+```markdown
+---
+name: release-notes-from-prs
+description: Write customer-facing release notes from a list of merged pull requests — grouped into New, Improved and Fixed, each line in user terms with the PR number, internal-only changes dropped, and breaking changes called out first. Use when the user pastes merged PRs or a git log and says "write the release notes", "draft the changelog for v2.4", or "what shipped this sprint, for customers".
+---
+
+# release-notes-from-prs
+
+You turn a list of merged pull requests into release notes a customer can read in a minute.
+The input is engineering language; the output says what changed for the person using the
+product. Internal changes (refactors, CI, dependency bumps with no user effect) are dropped,
+and the user sees the list of what was dropped.
+
+## How to respond
+
+1. **Ask once for what's missing.** You need the merged PRs (titles, numbers, and bodies or
+   labels if available), the version and release date, and the audience (end users or
+   developers using an API). Ask in one message; default the audience to end users.
+2. **Sort every PR into one bucket:** Breaking, New, Improved, Fixed, or Internal. A PR with
+   a `breaking` label or a removed option goes to Breaking even if it also adds something.
+3. **Rewrite each kept PR as one line in user terms.** ✅ *"Exports now include the time zone
+   (#412)"* ❌ *"Refactor ExportSerializer to pass tz (#412)"*. Keep the PR number.
+4. **Put Breaking first**, each with what the user must do. A breaking change with no action
+   line is not finished.
+5. **Fill [`templates/release-notes.md`](templates/release-notes.md)** and list the dropped
+   Internal PRs under the notes, so the user can overrule you.
+
+**Non-interactive runs** (subagent, CI, headless): with no PR list, emit
+`BLOCKED: need the merged PRs (titles and numbers)` and write nothing. A missing version or
+date becomes `[assumption] version: unreleased`.
+
+## Useful references in this skill
+
+- [`templates/release-notes.md`](templates/release-notes.md) — the release-notes skeleton
+
+## Quality bar
+
+- **Every line traces to a PR number** from the input. Nothing is added that no PR supports.
+- **Lines are in user terms**: what changed for the user, not which class changed.
+- **Breaking changes come first** and each carries the action the user must take.
+- **Dropped PRs are listed**, so nothing disappears silently.
+
+## When to use this skill
+
+- ✅ Release notes or a changelog entry from merged PRs or a git log
+- ✅ A "what shipped" summary for customers at the end of a sprint
+
+## When NOT to use this skill
+
+- ❌ An internal sprint report for the team: use `sprint-status`
+- ❌ A launch announcement or blog post, which needs positioning, not a list: use `launch-post`
+
+## Anti-patterns to avoid
+
+- ❌ **Copying PR titles verbatim.** "Bump lodash to 4.17.21" means nothing to a customer.
+- ❌ **Hiding a breaking change under Improved** because it also adds a feature.
+- ❌ **Inventing a benefit** ("faster exports") that no PR measured.
+```
+
+### `templates/release-notes.md`
+
+```markdown
+# {Product} {version} — {YYYY-MM-DD}
+
+## Breaking changes
+- {what changed} — **what to do:** {action} (#{n})
+
+## New
+- {line in user terms} (#{n})
+
+## Improved
+- {line} (#{n})
+
+## Fixed
+- {line} (#{n})
+
+---
+Dropped as internal: #{n} {title}, …
+```
+
+### `evals/evals.json`
+
+```json
+{
+  "skill_name": "release-notes-from-prs",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Write the release notes for Acme Tasks v2.4 (shipping 2026-10-15) from these merged PRs: #401 Add CSV export for boards; #405 Remove legacy v1 API tokens (breaking); #407 Refactor board serializer; #409 Fix due dates shifting a day for users in UTC-8; #410 Bump eslint to 9.1.",
+      "assertions": [
+        "The removal of v1 API tokens (#405) appears first, under Breaking, with an action the user must take",
+        "Every line carries a PR number from the prompt, and no line describes a change that no PR supports",
+        "#407 and #410 are dropped as internal and listed under the notes",
+        "The due-date fix is written in user terms, not as the code change",
+        "No performance or benefit claim appears that the PR titles do not state"
+      ]
+    }
+  ]
+}
+```
+
+### `evals/eval_queries.json`
+
+```json
+[
+  {"query": "Write the release notes for v2.4 from these merged PRs", "should_trigger": true},
+  {"query": "Draft the changelog entry from this git log", "should_trigger": true},
+  {"query": "What shipped this sprint? Make it readable for customers", "should_trigger": true},
+  {"query": "Turn these PR titles into customer-facing notes for the release", "should_trigger": true},
+  {"query": "Write the launch blog post for our new export feature", "should_trigger": false},
+  {"query": "Give me a status update on the sprint for the engineering manager", "should_trigger": false},
+  {"query": "Review this pull request for bugs before I merge it", "should_trigger": false}
+]
+```
+
+### Install
+
+```bash
+mkdir -p .claude/skills .github/skills
+cp -R release-notes-from-prs .claude/skills/     # Claude Code, and Copilot CLI
+cp -R release-notes-from-prs .github/skills/     # Copilot in the editor
+```
+
+### Check
+
+The folder was linted with `skill-review`'s script, against the two sibling skills in the
+same repo. This is the real output:
+
+```
+$ python3 lint_skill.py release-notes-from-prs --siblings .
+lint_skill: release-notes-from-prs  (release-notes-from-prs)
+  skill_md_lines=57  description_chars=388  evals=1  assertions=5  trigger_queries=4  near_miss_queries=3  siblings_compared=2
+  closest: sprint-status 0.07, launch-post 0.05
+  no findings
+result: 0 error(s), 0 warning(s), 0 info -> mechanical checks pass
+```
+
+The lint passing covers only the mechanical checks. Next: run the eval prompt in a fresh
+session and mark each assertion.

skilldrop_cli/data/packs/skill-engineering/skills/skill-author/manifest.json

@@ -0,0 +1,42 @@
+{
+  "name": "skill-author",
+  "version": "0.1.0",
+  "description": "Write a new portable Agent Skill (a SKILL.md folder) from a described task, for Claude Code, Codex, Copilot, Cursor, Kiro or Antigravity in any repo — a description that leads with the artifact and ends with trigger phrases, decisive steps, a quality bar, when and when-not sections naming near-miss siblings, anti-patterns, a non-interactive rule, reference files and scripts that work in every tool, acceptance evals and trigger queries, and the install path for each tool. Use when the user says \"turn this into a skill\", \"write a SKILL.md for…\", \"make an agent skill that…\", or wants a repeatable task packaged so their coding agent does it the same way every time.",
+  "entrypoint": "SKILL.md",
+  "deps": {
+    "npm": [],
+    "pip": []
+  },
+  "env": {
+    "required": [],
+    "optional": []
+  },
+  "related": [
+    "agents-md-generator",
+    "contribution-wizard",
+    "eval-harness-generator",
+    "skill-review"
+  ],
+  "handoff": [
+    {
+      "to": "skill-review",
+      "when": "the skill folder is written",
+      "purpose": "Audit routing, portability, safety, structure and evals before the skill is shared.",
+      "fallback": "If skill-review is absent, check inline: name equals folder, description leads with the artifact and ends with triggers, every linked path exists, every script appears with a plain relative path, and the evals parse."
+    }
+  ],
+  "tags": [
+    "agent-skills",
+    "skill-md",
+    "authoring",
+    "portability",
+    "evals",
+    "claude-code",
+    "codex",
+    "copilot"
+  ],
+  "model": {
+    "tier": "standard",
+    "rationale": "Structured authoring against a fixed anatomy. The judgment is in the description and sibling boundaries, which the interview anchors; skill-review is the adversarial pass."
+  }
+}

skilldrop_cli/data/packs/skill-engineering/skills/skill-author/reference.md

@@ -0,0 +1,144 @@
+# skill-author reference
+
+## How a tool reads a skill
+
+Every tool that supports Agent Skills loads them in three stages, and that order sets the
+writing priorities:
+
+1. **At startup it reads only `name` and `description`** from every installed skill. This is
+   the routing decision. A skill whose description loses here is never read.
+2. **When a request matches, it reads the SKILL.md body.** This is where the steps, quality
+   bar and boundaries live.
+3. **It reads reference files and runs scripts only when a step points to them.** That is
+   why every reference file must be linked from SKILL.md, and why long material can live
+   outside SKILL.md at no cost until it's needed.
+
+## Frontmatter
+
+```yaml
+---
+name: release-notes-from-prs
+description: Write customer-facing release notes from merged pull requests — … Use when the user …
+---
+```
+
+| Field | Rule |
+|---|---|
+| `name` | Required. Lowercase letters, digits and single hyphens, at most 64 characters, identical to the folder name. |
+| `description` | Required. At most 1,024 characters. Leads with the artifact, ends with trigger phrases. |
+| Others | The Agent Skills specification also defines optional fields such as `license` and `metadata`. Claude Code reads extras such as `allowed-tools`; other tools ignore fields they don't know. Add one only when you know which tool reads it, and say in SKILL.md what happens in the others. |
+
+## Writing the description
+
+The formula: **artifact and use case → two or three distinguishing details → trigger phrases.**
+
+| Rule | ✅ | ❌ |
+|---|---|---|
+| Lead with the artifact, as a verb and a noun | "Write a threat model for…" | "This skill helps teams think about security" |
+| Name what sets it apart from the nearest sibling | "…from merged PRs, internal changes dropped" | "…for releases" |
+| End with phrases users type, in quotes | `says "write the release notes", "draft the changelog"` | "Use for release management workflows" |
+| Name the input when it's distinctive | "from a transcript or rough notes" | "from information" |
+| No hype | "grouped New / Improved / Fixed" | "powerful, comprehensive release tooling" |
+| One artifact | "release notes" | "release notes, roadmaps and status reports" |
+
+**Testing against siblings.** For each near-miss sibling, take one of its should-trigger
+queries and ask which description wins it. If yours does, add the words that separate them
+("for customers, not the team"; "from PRs, not from a roadmap"). Then add a When NOT line
+naming the sibling, and a should-not-trigger query using that sibling's request.
+
+**Length.** 250–600 characters names the artifact, the details and four or five triggers.
+Under ~120 rarely does both. Near 1,024 usually means the skill does too much.
+
+## Body rules
+
+- **Third person for the user, imperative for the agent.** "Ask the user for…", not "You might
+  want to ask…".
+- **Steps decide.** Pick defaults. Strip "generally", "consider", "you might want to". If a
+  rule has an exception, name it.
+- **Ask once.** Step 1 gathers every missing input in one message with defaults shown. At most
+  two real questions.
+- **Show a passing and a failing example** wherever a rule could be read two ways.
+- **Quality bar items are checkable** against one output. "High quality" is not checkable;
+  "every line carries a PR number from the input" is.
+- **When NOT lines name the alternative**: a sibling skill, a tool, or "a plain prompt".
+- **Anti-patterns are real mistakes** seen in this task, not "don't be vague".
+- **A skill never invokes another skill.** Name a sibling as a next step; the user or a
+  workflow runs it. A copied skill must work alone.
+
+## Splitting files
+
+| File | Put here |
+|---|---|
+| `SKILL.md` | The steps, the rules that apply every run, the boundaries. Under ~500 lines. |
+| `reference.md` or a `references/` folder | Lookup tables, long rubrics, catalogues, domain background. |
+| a `templates/` folder | Output skeletons the agent fills. |
+| an `examples/` folder | One worked input → output, for a skill where "good" is hard to describe. |
+| a `scripts/` folder | Code for exact work. |
+| an `evals/` folder | `evals.json` and `eval_queries.json`. |
+
+Link every reference file from SKILL.md with a relative link. A reference file over ~1,000
+lines needs a table of contents at the top.
+
+## The script contract
+
+- Standard library only, unless the job truly needs a package; then declare it in a
+  `requirements.txt` and say so in SKILL.md.
+- Input from arguments or stdin. Output to a path the user gives, never into the skill folder
+  or a fixed location.
+- Exit non-zero with a one-line message on bad input.
+- No network calls unless fetching is the skill's purpose and SKILL.md says so.
+- Shown in SKILL.md both ways: `"${CLAUDE_SKILL_DIR}/scripts/<script>.py"` for Claude Code,
+  and the same path relative to the skill folder for every other tool.
+- Tested on a real input and a bad one. Example outputs are pasted from real runs.
+
+## Where each tool reads skills
+
+| Tool | Project scope | Personal scope |
+|---|---|---|
+| Claude Code | `.claude/skills/<name>/` | `~/.claude/skills/<name>/` |
+| Codex | `.agents/skills/<name>/` | `~/.codex/skills/<name>/` |
+| Antigravity | `.agents/skills/<name>/` | `~/.gemini/antigravity-cli/skills/<name>/` |
+| GitHub Copilot | `.github/skills/<name>/` (Copilot CLI also reads `.claude/skills/` and `.agents/skills/`) | `~/.copilot/skills/<name>/` |
+| Kiro (IDE and CLI) | `.kiro/skills/<name>/` | `~/.kiro/skills/<name>/` |
+| Cursor | Copy the folder to `.cursor/skills/<name>/` and add a rule at `.cursor/rules/<name>.mdc` whose `description` is the skill's description and whose body says to follow that SKILL.md | — |
+| Continue, Cline, Aider | Copy the folder anywhere in the repo and attach `SKILL.md` to the prompt (`@file`, or `/add` in Aider) | — |
+
+Copy the whole folder, never its parent, and keep the layout intact so relative paths
+resolve. For a team repo, one copy in `.agents/skills/` reaches Codex, Antigravity and
+Copilot CLI; add `.claude/skills/` for Claude Code.
+
+## Eval formats
+
+`evals/evals.json`:
+
+```json
+{
+  "skill_name": "release-notes-from-prs",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Write the release notes for Acme Tasks v2.4 from these merged PRs: …",
+      "assertions": [
+        "Breaking changes appear first, each with an action the user must take",
+        "The output does not invent a change that no PR in the prompt supports"
+      ]
+    }
+  ]
+}
+```
+
+`evals/eval_queries.json`:
+
+```json
+[
+  {"query": "Write the release notes for v2.4 from these merged PRs", "should_trigger": true},
+  {"query": "Write the launch blog post for the export feature", "should_trigger": false}
+]
+```
+
+At least four `true` rows in different wordings and three or four `false` rows, each a
+request a named sibling handles. A `false` row nobody would type tests nothing.
+
+To run them by hand: install the skill, start a fresh session, paste each eval prompt, and
+mark each assertion pass or fail. For the queries, check that each `true` row picks the skill
+and each `false` row picks something else.

skilldrop_cli/data/packs/skill-engineering/skills/skill-author/templates/eval_queries.json

@@ -0,0 +1,9 @@
+[
+  {"query": "{a phrasing a user would type that should use this skill}", "should_trigger": true},
+  {"query": "{a second phrasing, different wording}", "should_trigger": true},
+  {"query": "{a third phrasing, naming the input}", "should_trigger": true},
+  {"query": "{a fourth phrasing, naming the output}", "should_trigger": true},
+  {"query": "{a near-miss that belongs to sibling A}", "should_trigger": false},
+  {"query": "{a near-miss that belongs to sibling B}", "should_trigger": false},
+  {"query": "{a near-miss that belongs to sibling C}", "should_trigger": false}
+]

skilldrop_cli/data/packs/skill-engineering/skills/skill-author/templates/evals.json

@@ -0,0 +1,16 @@
+{
+  "skill_name": "{skill-name}",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "{A realistic request with concrete details and placeholder names (Acme, Northwind): the input pasted or described, the output wanted.}",
+      "assertions": [
+        "{Quality bar rule 1, as a claim about this one output that a reader can mark pass or fail}",
+        "{Quality bar rule 2}",
+        "{Quality bar rule 3}",
+        "{Quality bar rule 4}",
+        "The output does not invent {facts, names, dates, numbers} that are not in the prompt"
+      ]
+    }
+  ]
+}