Przejdź do treści
Biblioteka skilli
AI i agenci · Pisanie

add-skill

/add-skill

Pisze skill publikowany przez serwer dla agentów: główny skills/<name>/SKILL.md zgodny ze specyfikacją Agent Skills, walidowany przez lint:packaging, dołączany do pakietu MCPB i opcjonalnie serwowany przez MCP.

Repozytorium
mcp-ts-core ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
25.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
2
Przestarzałość

Brak sygnałów. Repozytorium zmienione 25.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co robi i kiedy

Pisze skill publikowany przez serwer dla agentów: główny skills/<name>/SKILL.md zgodny ze specyfikacją Agent Skills, walidowany przez lint:packaging, dołączany do pakietu MCPB i opcjonalnie serwowany przez MCP.

Oryginalny opis (EN)

Author a skill the server publishes to the agents that use it — a root `skills/<name>/SKILL.md` per the Agent Skills specification, validated by `lint:packaging`, discovered by plugin hosts, shipped in the MCPB bundle, and optionally served over MCP. Use when the user asks to add, write, or publish a skill, agent guide, or usage guide for the server's tools, or when the design calls for one.

Jak działa

  1. Context
  2. No skill by default
  3. Authoring rules
  4. Skeleton
  5. Layout and frontmatter
  6. Validation — lint:packaging
  7. Delivery
  8. Serving over MCP (opt-in)
  9. Keep instructions lean
  10. Verify before shipping
Sekcje z nagłówków SKILL.md, w oryginale · 129 linii, 1 566 słów
Podgląd SKILL.md
---
name: add-skill
description: >
  Author a skill the server publishes to the agents that use it — a root `skills/<name>/SKILL.md` per the Agent Skills specification, validated by `lint:packaging`, discovered by plugin hosts, shipped in the MCPB bundle, and optionally served over MCP. Use when the user asks to add, write, or publish a skill, agent guide, or usage guide for the server's tools, or when the design calls for one.
metadata:
  author: cyanheads
  version: "1.0"
  audience: external
  type: reference
---

## Context

A server has two skill trees, written for different readers:

| Tree | Reader | Written by |
|:-----|:-------|:-----------|
| `framework-skills/` | The agent building the server | `init` and the `maintenance` sync, plus any development skills of the server's own |
| `skills/` (root) | The agent that installed the server and is calling its tools | The author, deliberately |

Root `skills/` is absent by default; `init` and `maintenance` never write it. Claude Code always scans a plugin's root `skills/` ([Agent Plugins 1.0.0](https://agent-plugins.org/specification) fixes discovery there), so no `skills` field is needed in `.claude-plugin/plugin.json`. Each `SKILL.md` follows the [Agent Skills specification](https://agentskills.io/specification); a host skips one that doesn't, without a word, which is why `lint:packaging` validates the tree.

## No skill by default

Publish one only when an agent calling the tools needs something `instructions` and tool descriptions cannot carry: a multi-hop identifier chain, a gate that prevents a wrong call or a wrong conclusion, a query syntax. Overview skills that restate the tool list, generic "how to use this server" workflows, and skills for hypothetical tasks do not ship.

## Authoring rules

- **Perspective.** The reader is the agent calling the server's tools in the middle of a multi-step task, not the maintainer. Walk a realistic workflow against the tool surface and write down what that agent needs at each hop.
- **One skill per server, split by trigger.** The description stays resident in every session; the body loads only on invocation, so workflows belong inside the one skill, not in a second with the same trigger. A second skill earns its place only when a distinct trigger vocabulary routes to a materially different workflow. Two is the cap; three when day-to-day use of the server proves it.
- **Naming.** Default `<package short name>-guide` (`pubmed-guide` for `pubmed-mcp-server`). The description names the tool prefix (`pubmed_*`) so the agent binds the skill to the tools it sees.
- **Layering.** Tool `.describe()` text carries the per-tool contract; `instructions` carries a one-paragraph orientation (canonical chain, identifier types, rate posture); MCP prompts stay user-invoked task templates. The skill carries what none of those can: when to reach for the server and when not to, where each opaque identifier comes from, gates, branching workflows, and syntax references. It never restates `instructions`.
- **Gates** are the section a skill exists for. Each is an imperative the agent satisfies before acting or concluding: a precondition (resolve a name to an ID before filtering, where an unresolved filter returns the global set), a stop rule (confirm coverage before reporting a record absent), or a confirmation gate (ask the user before a tool that sends, writes, or deletes). Verified facts only, sourced from `instructions`, the design doc's Workflow Analysis and Known Limitations, tool descriptions, or closed issues — nothing invented. Cut any fact that would not change what the agent does.
- **Drift.** Name tools in prose; never list their parameters — the schemas own them.
- **Budget.** `SKILL.md` under 150 lines (the specification's 500 is a ceiling, not a target); the description under 500 characters, since it is resident in every session. Long material goes to `references/`.

## Skeleton

Sections in this order, so skills read alike across servers. Omit a section with nothing to say.

| Section | Carries |
|:--------|:--------|
| Scope | What the server covers and doesn't; keyless or which key. A sibling server may appear as a composition line, never as a dependency |
| Identifiers | Each opaque ID type and the tool that yields it |
| Gates | Preconditions, stop rules, confirmation gates |
| Core chain | Only when the canonical path is two or more hops |
| Workflows | Only when the surface branches, has modes, or registers the dataframe tools (paragraph below) |
| References | `references/*.md` links, only for long syntax or vocabulary material |

A server that registers the DataCanvas tools ships this paragraph under Workflows, prefix substituted:

> Results too large to return inline are staged as a DataCanvas table, and the response carries a `canvas_id`. Call `<prefix>_dataframe_describe` with it for the staged table and column names before writing SQL, then `<prefix>_dataframe_query` with a read-only query. Pass the same `canvas_id` back to stage further results beside the first; the tables expire with the canvas.

## Layout and frontmatter

```text
skills/
└── my-server-guide/
    ├── SKILL.md
    └── references/
        └── query-syntax.md
```

```markdown
---
name: my-server-guide
description: Chain my_server_search → my_server_get and resolve item IDs. Use when the agent needs a my_server_* record it only knows by name.
license: Apache-2.0
metadata:
  author: owner
  version: "1.0"
---

## Scope
…
```

`name` equals the directory name. Every `metadata` value is a quoted string. Never set `metadata.audience` — `external` is the marker `init` and the skills sync use to recognize framework-managed skills. Host-specific fields beyond the specification (`disable-model-invocation`) are accepted.

## Validation — `lint:packaging`

Runs when root `skills/` exists (inside `devcheck`) and skips cleanly when it doesn't. The specification rules come from the MCP SDK's strict skill loader through `validateSkillTree()` (`@cyanheads/mcp-ts-core/linter`), the loader the server serves with, so a tree that passes is served whole. Each failure names the file and field:

- `name` missing, not a string, not the directory name, over 64 characters, or outside `^[a-z0-9]+(-[a-z0-9]+)*$`
- `description` missing, empty, or over 1024 characters (project rule: 500); `compatibility` empty, not a string, or over 500
- a `metadata` value that is not a string (`version: 1.0` unquoted); `allowed-tools` that is not a string
- frontmatter outside the SDK's YAML subset — a multi-line quoted value, an anchor, a tag
- a symlink anywhere in a skill; a skill over 512 files or 16 MiB
- a `SKILL.md` directly under `skills/`; a `skills/<name>/` with no `SKILL.md`; a `SKILL.md` deeper than `skills/<name>/` (plugin hosts discover immediate children only)
- a `SKILL.md` over 150 lines; `metadata.audience: external`
- an `.mcpbignore` pattern that strips a file of the tree from the bundle — a pre-0.13 `.mcpbignore` may still carry `/skills/`

## Delivery

| Channel | What carries the tree |
|:--------|:----------------------|
| Plugin install (Claude Code, Codex) | The repository tree — root `skills/` is scanned by default |
| MCPB bundle | Bundle root `skills/`, which the Claude Directory surfaces as Skills; `.mcpbignore` must not exclude it, and `clean-mcpb` strips `skills/` only under `node_modules/` |
| npm (`npx`) | `package.json` `files` lists `"skills/"` (scaffold default) |
| Docker | The template Dockerfile creates `skills/` in the build stage and copies it into the production stage |

A project scaffolded before these defaults adds the `files` entry and the two Dockerfile lines from `node_modules/@cyanheads/mcp-ts-core/templates/` before relying on npm or Docker delivery.

## Serving over MCP (opt-in)

Plugin delivery reaches only agents that install the server as a plugin. To reach MCP clients through the SEP-2640 Skills extension:

```ts
await createApp({ tools: allToolDefinitions, skills: 'skills' });
```

A relative path resolves against the application root, so a stdio server launched from a client's project serves its own tree. The folder is read once at startup: a missing or unreadable folder fails startup with a `ConfigurationError` naming the resolved path; a skill the SDK rejects is skipped with a `Skill problem in <path>` warning and the rest are served. Opting in advertises `io.modelcontextprotocol/skills` under `capabilities.extensions`, adds `skills/list`, `skills/get`, and `resources/directory/read`, lists each `SKILL.md` in `resources/list`, and registers the `skill://{+path}` template, on both protocol eras; `tools/list` and `instructions` are unchanged. The `Core services constructed` log record's `skills` field lists the names served. Skill resources are served by the SDK: transport auth applies, per-definition `auth` scopes do not.

A Worker has no filesystem, so `createWorkerHandler` takes the files as a record built from Wrangler `Text` module imports — the record form and the Wrangler rule are in `api-workers`.

## Keep `instructions` lean

Once the skill exists, move extended workflows into it and keep `instructions` to its paragraph. Essential identifier, auth, and call-order requirements stay in `instructions` and the schemas anyway: a client connecting directly may never install the plugin or load the skill.

## Verify before shipping

`field-test` reads the published skill and checks every gate and identifier claim against live tool behavior. A claim that does not hold is fixed or cut.

## Checklist

- [ ] The skill clears the bar: a gate, a multi-hop identifier chain, or a query syntax that `instructions` and tool descriptions cannot carry
- [ ] `skills/<name>/SKILL.md` created; `name` equals the directory, default `<package short name>-guide`
- [ ] Description under 500 characters, names the tool prefix and the trigger
- [ ] Sections follow the skeleton order; empty sections omitted; the canvas paragraph present when the dataframe tools are registered
- [ ] Every gate and identifier claim traced to `instructions`, the design doc, a tool description, or a closed issue
- [ ] Tools named in prose only, no parameter lists; nothing restated from `instructions`
- [ ] `SKILL.md` under 150 lines; long material in `references/`
- [ ] No `metadata.audience`; every `metadata` value quoted
- [ ] `.mcpbignore` does not exclude `/skills/`; `package.json` `files` lists `skills/`; the Dockerfile copies it
- [ ] `instructions` trimmed to its paragraph, essential requirements kept
- [ ] **If serving over MCP:** `createApp({ skills: 'skills' })` (or the Worker record) set; the `Core services constructed` record's `skills` field lists the skill
- [ ] `bun run lint:packaging` passes
- [ ] `field-test` verified every gate and identifier claim against live behavior

Wersje

RepozytoriumWynikLicencja
Ta strona · cyanheads/mcp-ts-core100Apache-2.0
cyanheads/pubmed-mcp-server100Apache-2.0
h2xd/skills100MIT
workbench-soft/agent-skills100MIT
coralogix/cx-cli100Apache-2.0
htlin222/dotfiles100MIT
aomni-com/open-duet100MIT
Paldom/pptx-style100MIT
microsoft/copilot-studio-plugin100MIT

Identyczna treść występuje jeszcze w 11 innych folderach na GitHubie. Tu pokazujemy jedną, najlepiej ocenioną kopię.

Migawka bazy z 13.11.2026 · wersja paczki 11a2713371df (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 95build-mcpb
    Pakuje lokalny serwer MCP do pliku .mcpb z wbudowanym środowiskiem Node lub Python, aby dało się go zainstalować bez konfiguracji środowiska po stronie użytkownika.
  • 95build-mcpb
    Pakuje lokalny serwer MCP do pliku .mcpb z wbudowanym środowiskiem Node lub Python, aby dało się go zainstalować bez konfiguracji środowiska po stronie użytkownika.
  • 100skill-writer
    Tworzy i ulepsza skille agentów zgodnie ze specyfikacją Agent Skills, przy pisaniu i aktualizacji skilli.
  • 100skill-writer
    Tworzy i ulepsza skille agentów zgodnie ze specyfikacją Agent Skills, przy pisaniu i aktualizacji skilli.
  • 90hive.writing-hive-skills
    Pisze nowy skill dla agenta Hive zgodny ze specyfikacją SKILL.md, z szablonem, skryptami i pakowaniem.
  • 100skill-writer
    Prowadzi przez tworzenie Agent Skills dla Claude Code, w tym pliki SKILL.md, frontmatter i strukturę skilla.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.