@ssheleg/make-skill 0.7.1 → 0.8.0

package/plugins/make-skill/skills/make-skill/references/enterprise.md

@@ -0,0 +1,141 @@
+# Trust, evaluation, governance — skills other people install
+
+**Load this when:** installing or reviewing a skill you did not write, publishing
+one that others will run, or running a fleet of skills across a team or org
+(recall limits, approval gates, lifecycle, rollback).
+
+Source: Anthropic's
+[Skills for enterprise](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/enterprise)
+plus the security section of the
+[overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview).
+*Read from both on 2026-08-03.*
+
+## Contents
+
+- Why this is a security boundary at all
+- Risk tiers — what to look for
+- Review checklist before installing anything
+- Approval gates — the five evaluation dimensions
+- Lifecycle
+- Registry — what to record per skill
+- Recall limits and consolidation
+- Versioning, rollback, integrity
+
+## Why this is a security boundary at all
+
+A skill is text an agent executes, plus code the agent runs without reading it
+into context. Installing one is installing software: it can direct the agent to
+invoke tools, read files, and send data anywhere the agent can reach. Use skills
+you wrote or that come from a source you trust; audit anything else **before**
+install, not after the first odd result.
+
+This cuts both ways. A skill you publish is asking strangers for that trust, so
+ship the things that make an audit cheap: a real `SECURITY.md`, no network calls
+the README doesn't mention, no credentials anywhere, and scripts small enough to
+read.
+
+## Risk tiers — what to look for
+
+| Indicator | What to look for | Concern |
+|---|---|---|
+| Code execution | `*.py`, `*.sh`, `*.js` in the skill dir | **High** — runs with the agent's full environment access |
+| Instruction manipulation | "ignore previous rules", hiding actions from the user, behavior that changes on a trigger word | **High** — bypasses controls |
+| MCP server references | `ServerName:tool_name` / `mcp__server__tool` instructions | **High** — extends reach beyond the skill |
+| Network patterns | URLs, `fetch`, `curl`, `requests`, `urllib` | **High** — exfiltration vector |
+| Hardcoded credentials | keys, tokens, passwords in files or scripts | **High** — leaks into git history and context |
+| Filesystem scope | paths outside the skill dir, broad globs, `../` | Medium |
+| Tool invocations | instructions to use bash / file ops | Medium — read what they do |
+
+Combined risk is the real one: file-read **plus** network in the same skill is a
+different question from either alone.
+
+## Review checklist before installing anything
+
+1. **Read every file** — `SKILL.md`, each referenced markdown file, every script,
+   and anything bundled that isn't obviously inert.
+2. **Run scripts in a sandbox** and confirm the behavior matches the stated
+   purpose.
+3. **Look for adversarial instructions** — telling the agent to ignore safety
+   rules, hide steps from the user, encode data into its own replies, or behave
+   differently on a specific input.
+4. **Grep for network access** (`http`, `requests.get`, `urllib`, `curl`, `fetch`)
+   and confirm each hit is documented.
+5. **Verify no hardcoded credentials.** Secrets belong in env vars or a credential
+   store, never in skill content.
+6. **List every tool and command** the skill tells the agent to invoke.
+7. **Confirm redirect destinations** — external URLs must point where the docs say.
+8. **Look for exfiltration shapes**: read sensitive data → write, send, or encode
+   it outward, including through the agent's own conversational output.
+
+An external URL fetched at runtime is the sharpest edge: the content can change
+after your review, so a skill that pulls instructions from a URL is only as
+trustworthy as that URL is today.
+
+## Approval gates — the five evaluation dimensions
+
+A bad skill degrades the agent even when nothing malicious happens. Gate on all
+five, not just "does it work":
+
+| Dimension | Question | Example failure |
+|---|---|---|
+| Triggering accuracy | fires for the right queries, stays quiet otherwise | fires on every mention of a spreadsheet |
+| Isolation | works correctly on its own | references a file that isn't in the directory |
+| **Coexistence** | does adding it degrade the skills already installed | its broad description steals another skill's triggers |
+| Instruction following | does the agent actually follow the steps | skips the validation step, uses the wrong library |
+| Output quality | is the result correct and useful | reports render with missing data |
+
+Require 3–5 representative queries per skill covering should-trigger,
+should-NOT-trigger, and ambiguous cases, run on every model in scope (Haiku,
+Sonnet, Opus). Coexistence is the one authors skip and the one that breaks a
+family of skills shipped from one repo — test a new member against the installed
+set, not alone.
+
+Reading the results: declining trigger accuracy → fix the description; coexistence
+conflicts → narrow descriptions or merge the skills; persistently low output
+quality → rewrite or add validation; persistent failure across updates → deprecate.
+
+## Lifecycle
+
+1. **Plan** — pick workflows that are repetitive, error-prone, or need specialist
+   knowledge. Map them to roles.
+2. **Create and review** — author follows the craft rules; a security review and an
+   eval suite are required. **Separation of duties: an author does not review their
+   own skill.**
+3. **Test** — in isolation and alongside the existing set.
+4. **Deploy** — one channel per agent (`references/distribution.md`), or the Skills
+   API for workspace-wide (`references/surfaces.md`). Record it in the registry.
+5. **Monitor** — usage analytics do not exist in the Skills API; log which skills a
+   request included at the application level. Re-run evals periodically: models and
+   workflows drift under a frozen skill.
+6. **Iterate or deprecate** — full eval suite passes before a new version is
+   promoted; retire skills whose evals keep failing or whose workflow is gone.
+
+## Registry — what to record per skill
+
+Purpose · owner (team or person) · deployed version · dependencies (MCP servers,
+packages, external services) · last evaluation date and result. Without an owner
+and a date, "is this still true?" has no answer and the skill rots in place.
+
+## Recall limits and consolidation
+
+Every installed skill's name and description sits in the system prompt competing
+for attention. Past some number — measure it, don't guess — the agent starts
+picking the wrong skill or missing the right one. The API caps a request at 8
+skills, which is a useful ceiling to design toward even off-API.
+
+Start narrow and workflow-specific (`formatting-sales-reports`,
+`querying-pipeline-data`), consolidate into role bundles (`sales-operations`) only
+when evals show the merged skill matches what it replaced. Group by role so each
+user's active set stays focused.
+
+## Versioning, rollback, integrity
+
+- **Production pins an exact version.** "latest" in production means an untested
+  skill can arrive between two identical requests.
+- **Every update is a new deployment** — full security review and full eval suite,
+  not a diff review.
+- **Keep the previous version installable** and revert immediately on a regression.
+- **Verify integrity**: checksum what you reviewed and check it at deploy time; use
+  signed commits in the skill repo so provenance is more than a claim.
+- **Git is the source of truth**, one directory per skill, changes through pull
+  requests — which also gives you the rollback and the audit trail for free.

package/plugins/make-skill/skills/make-skill/references/mcp.md

@@ -9,6 +9,16 @@ build against and re-verify method names before locking a contract — MCP versi
 by date and the negotiated `protocolVersion` string is part of the handshake.
 *Read from the spec on 2026-07-28.*
 
+## Contents
+
+- Skill vs MCP server — pick the right one
+- Architecture, lifecycle
+- Server primitives and methods
+- Client primitives (sampling, elicitation, roots)
+- Transports
+- Security — the parts a skill must respect
+- Gotchas when writing an MCP-adjacent skill
+
 ## Skill vs MCP server — pick the right one
 
 | Need | Build |
@@ -108,10 +118,13 @@ The spec is explicit that MCP grants arbitrary data access and execution:
 
 ## Gotchas when writing an MCP-adjacent skill
 
-- **Name tools, don't guess them.** Tool names are server-namespaced and hosts
-  often prefix them (`mcp__<server>__<tool>`). Hardcoding a bare name in a skill
-  breaks on half the hosts — tell the agent to list tools and match, and give the
-  exact name only as a hint.
+- **Name tools, don't guess them — and never bare.** A bare `create_issue` is the
+  documented cause of "tool not found" once two servers are connected. Qualify it:
+  Anthropic's authoring guidance writes `ServerName:tool_name` (`GitHub:create_issue`),
+  while Claude Code's own runtime names are `mcp__<server>__<tool>` and a
+  plugin's own server is `mcp__plugin_<plugin>_<server>__<tool>`. Since the form
+  differs per host, tell the agent to **list tools and match**, and give the exact
+  string only as a hint.
 - **The tool list is dynamic.** Never assert a tool exists; instruct a fallback
   when it is missing (the server may be unauthenticated, disconnected, or gated).
 - **Remote servers need auth the agent cannot do**: OAuth flows are interactive.

package/plugins/make-skill/skills/make-skill/references/surfaces.md

@@ -0,0 +1,139 @@
+# Surfaces — where a skill runs, and what breaks when it moves
+
+**Load this when:** the skill must work anywhere except Claude Code — uploading
+through the Skills API, shipping to claude.ai, or writing `scripts/` that assume
+network access or a package install.
+
+Source: Anthropic's
+[Agent Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)
+and [Using Agent Skills with the API](https://platform.claude.com/docs/en/build-with-claude/skills-guide).
+*Read from both on 2026-08-03.* The API is beta; re-check the header dates and
+limits before locking a contract.
+
+## Contents
+
+- The surface matrix — one table that decides portability
+- Nothing syncs — each surface is a separate deployment
+- Runtime constraints authors get wrong
+- Skills API — upload, version, attach
+- claude.ai
+- Pre-built Anthropic skills
+- Data retention
+
+## The surface matrix — one table that decides portability
+
+| | Claude Code | Claude API | claude.ai |
+|---|---|---|---|
+| Install | filesystem: `~/.claude/skills/` (personal), `.claude/skills/` (project), or a plugin | upload via `/v1/skills`, attach per request | zip upload in Settings → Features |
+| Sharing | per machine / per repo; plugins for teams | **workspace-wide** — every member sees it | **per user only**; no org-wide push, no admin management |
+| Network at runtime | full — same as any program on the machine | **none** | varies with user/admin settings |
+| Install packages at runtime | yes, but keep it local to the project | **no** — pre-installed only | npm / PyPI / GitHub allowed |
+| Cap per session/request | none | **8 skills per request** | — |
+| Pre-built doc skills | no | yes (`pptx`/`xlsx`/`docx`/`pdf`) | yes |
+
+Claude Platform on AWS and Microsoft Foundry behave as the Claude API (on Foundry,
+Agent Skills need a *Hosted on Anthropic* deployment).
+
+**The two claude.ai rows are Anthropic's own docs disagreeing**: the overview
+says network access there is full, partial or none depending on user/admin
+settings, while the authoring guide says claude.ai can install from npm and PyPI
+and pull from GitHub. Both are true per-tenant, which means neither is something
+to build on — treat claude.ai as "network may be off" and the skill still has to
+work.
+
+## Nothing syncs — each surface is a separate deployment
+
+A skill uploaded to the API is not on claude.ai and not in Claude Code, in any
+direction. There is no sync mechanism and none is planned in the docs. Keep the
+skill directory in git as the single source of truth and treat every surface as a
+publish target — which is exactly what the distribution matrix in
+`references/distribution.md` automates for the filesystem-based agents.
+
+## Runtime constraints authors get wrong
+
+Written once for the surface you happen to use, a skill silently fails elsewhere:
+
+- **`pip install` / `npm install` in a workflow step** — impossible on the API.
+  Either use only pre-installed packages (check the
+  [code execution tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool)
+  list) or state the dependency in `compatibility` and give a fallback path.
+- **`curl`/`requests`/any fetch inside a script** — no network on the API, maybe
+  none on claude.ai. A skill whose only path to data is an HTTP call is a Claude
+  Code skill; say so in `compatibility`.
+- **Global installs** (`npm i -g`, `pip install --user`) — discouraged even where
+  they work: the skill is a guest on the user's machine.
+- **Absolute machine paths** (`/Users/you/...`) — nothing outside the skill
+  directory exists on the API or claude.ai container.
+
+Declare what you need in front-matter `compatibility` (≤500 chars) and keep the
+skill useful, or explicitly refuse, when it is absent.
+
+## Skills API — upload, version, attach
+
+Beta headers: `skills-2025-10-02` enables Skills; `code-execution-2025-08-25`
+enables the code execution tool the skills run in; add `files-api-2025-04-14` when
+uploading inputs or downloading produced files. The overview calls only the skills
+header required, every example in the API guide sends both — send both.
+
+**Attach** — `container.skills[]`, max **8** per request, alongside the code
+execution tool:
+
+```python
+response = client.beta.messages.create(
+    model="claude-opus-5",
+    max_tokens=4096,
+    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
+    container={"skills": [
+        {"type": "anthropic", "skill_id": "pptx", "version": "latest"},
+        {"type": "custom", "skill_id": "skill_01AbCdEf…", "version": "latest"},
+    ]},
+    messages=[{"role": "user", "content": "…"}],
+    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
+)
+```
+
+Reuse `container={"id": response.container.id, "skills": [...]}` to continue in the
+same container, and re-issue the request while `stop_reason == "pause_turn"` for
+long jobs. Files the skill produces come back as `file_id`s — fetch them with the
+Files API.
+
+**Upload** — `client.beta.skills.create(files=…)` (a zip, file tuples, or
+`files_from_dir("my_skill")`), or `POST /v1/skills` multipart. Rules that reject an
+upload:
+
+| Rule | Detail |
+|---|---|
+| `SKILL.md` at the top level | of the single common root directory all files share |
+| top-level directory name == `name` | case- and underscore-insensitive match |
+| `name` | ≤64 chars, `[a-z0-9-]`, no XML tags, not containing `anthropic` or `claude` |
+| `description` | non-empty, ≤1024 chars, no XML tags |
+| `display_title` | optional, derived from `name`; if set explicitly it must be unique |
+| total upload | **< 30 MB** |
+
+**Version** — custom skills version as epoch timestamps
+(`1759178010641129`), Anthropic's own as dates (`20251013`); `"latest"` resolves
+either. New version = `client.beta.skills.versions.create(skill_id, files=…)`;
+pin an exact version in production. **Deleting a skill requires deleting every
+version first** — `skills.versions.delete(...)` in a loop, then `skills.delete(...)`.
+List with `client.beta.skills.list(source="custom")`.
+
+## claude.ai
+
+Upload the skill directory as a **zip** in Settings → Features. Requires a Pro,
+Max, Team, or Enterprise plan with code execution enabled. Custom skills there are
+**individual to each user** — there is no org-wide distribution and no admin
+console for them, so "roll this out to the team" means every member uploads it, or
+you use the API/plugin channels instead.
+
+## Pre-built Anthropic skills
+
+`pptx`, `xlsx`, `docx`, `pdf` — document creation/editing, available on the API,
+AWS, Foundry and claude.ai, attached by `skill_id` with `"type": "anthropic"`.
+**They are not available in Claude Code** (which instead bundles the open-source
+Claude API skill). Don't rebuild them; don't promise them on the wrong surface.
+
+## Data retention
+
+Agent Skills are **not covered by zero-data-retention arrangements** — skill
+definitions and execution data fall under standard retention. If a team is on ZDR
+for a reason, that reason applies to what you put in a skill.

package/templates/README.md

@@ -5,13 +5,13 @@ is absent; never overwrite existing files.
 
 | Template | Seeds | Used by |
 |---|---|---|
-| `SKILL.template.md` | a new `skills/<name>/SKILL.md` — spec-legal front-matter (required + optional fields, limits stated inline) and section stubs incl. References and Gotchas | Create / Promote |
+| `SKILL.template.md` | a new `skills/<name>/SKILL.md` — front-matter legal under BOTH rulebooks (limits stated inline, plain placeholders instead of `<angle brackets>`, which count as XML tags and are rejected on upload) and section stubs incl. References and Gotchas | Create / Promote |
 | `plugin.template.json` | `plugins/<name>/.claude-plugin/plugin.json` | Create (distributable) / Promote |
 | `marketplace.template.json` | `.claude-plugin/marketplace.json` at the repo root | Create (distributable) / Promote |
 
 The two JSON skeletons carry only fields Claude Code recognizes, so
 `claude plugin validate <path> --strict` passes on the seeded repo. Replace every
-`<placeholder>`, keep the `$schema` lines (editor autocomplete), and keep all
+placeholder, keep the `$schema` lines (editor autocomplete), and keep all
 four versions in sync. Marketplace level takes `name`, `owner`, `plugins`,
 `$schema`, `description`, `version`, `metadata`,
 `allowCrossMarketplaceDependenciesOn`, `renames` and nothing else —

package/templates/SKILL.template.md

@@ -1,11 +1,11 @@
 ---
-name: <skill-name>
-description: Use when <concrete triggering conditions and symptoms>. Add trigger phrases in English AND Russian. Describe WHEN to use, not what the skill does. Max 1024 chars.
+name: skill-name-here
+description: Use when CONCRETE TRIGGERING CONDITIONS AND SYMPTOMS. Add trigger phrases in English AND Russian. Say what the skill does AND when to use it, in third person, max 1024 chars, no angle brackets.
 # Optional, spec-legal — delete the ones you don't need:
 # license: MIT
-# compatibility: <runtime / system packages / required MCP server / protocol version>
+# compatibility: runtime / system packages / required MCP server / protocol version
 # metadata:
-#   author: <you>
+#   author: you
 #   version: "0.1.0"          # quote it, or YAML makes it a float
 # allowed-tools: Bash(git:*) Read     # space-separated string, experimental
 #
@@ -16,15 +16,20 @@ description: Use when <concrete triggering conditions and symptoms>. Add trigger
 # background / hooks / paths / shell
 ---
 
-# <Skill Name>
+# Skill Name
 
 <!--
-Spec floor (https://agentskills.io/specification):
-  name        1-64 chars, a-z0-9 and single internal hyphens, == directory name
-  description 1-1024 chars
+Spec floor — https://agentskills.io/specification plus Anthropic's platform rules
+(https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview):
+  name        1-64 chars, a-z0-9 and single internal hyphens, == directory name,
+              no angle brackets, never containing "anthropic" or "claude"
+  description 1-1024 chars, third person, no angle brackets, what + when
   body        < 500 lines and < 5000 tokens
 Heavier material → references/ (docs), scripts/ (code), assets/ (templates,
-schemas) inside THIS directory, one level deep, each with a stated load trigger.
+schemas) inside THIS directory, one level deep, each linked from the body with a
+stated load trigger. Reference files over 100 lines start with a "## Contents"
+list. Forward slashes in every path. Nothing time-branching: superseded material
+goes under "## Old patterns".
 -->
 
 ## Overview
@@ -41,6 +46,8 @@ What is this? Core principle in 1–2 sentences.
 
 Imperative, procedural steps or a before/after example. Checklists over prose.
 State non-negotiables as such. Give a default, not a menu of equal options.
+Match prescriptiveness to fragility: an exact command for destructive or
+order-dependent work, direction only where context decides.
 
 ## Quick reference
 
@@ -52,7 +59,7 @@ State non-negotiables as such. Give a default, not a menu of equal options.
 
 | Read | When |
 |---|---|
-| `references/<file>.md` | <the exact condition that should send the agent there> |
+| `references/FILE.md` | the exact condition that should send the agent there |
 
 ## Common mistakes
 
@@ -63,3 +70,9 @@ State non-negotiables as such. Give a default, not a menu of equal options.
 - Environment facts that defy reasonable assumptions. Keep these HERE, not in a
   reference file — the agent can't know to open a file about a trap it doesn't
   know exists.
+
+<!--
+Before shipping: ≥3 evaluations recorded (with should-NOT-trigger cases), run
+against a no-skill baseline and on every model you claim support for; runtime
+needs (network, packages, MCP servers) declared in `compatibility`.
+-->