diff --git a/.compiled/marketplace.json b/.compiled/marketplace.json index 5f2253c..acaf488 100644 --- a/.compiled/marketplace.json +++ b/.compiled/marketplace.json @@ -95,6 +95,21 @@ "yesterday" ] }, + { + "name": "create-shareable-skill", + "description": "Turn an existing skill or a fresh idea into a catalog-ready shareable skill -- run the quality gate, decide catalog and standalone-vs-bundle placement, pick the category, scaffold SKILL.md (+ optional .plugin.json), update the catalog docs, and open a PR. Use when adding a new skill to the catalog or promoting a personal skill into a shareable one.", + "source": "./.compiled/skill-plugins/create-shareable-skill", + "author": { + "name": "Yesterday" + }, + "keywords": [ + "claude-code", + "yesterday", + "skill-authoring", + "meta", + "contributing" + ] + }, { "name": "creative-productivity", "description": "Generate professional consulting deliverables: Excalidraw diagrams, Mermaid visualizations, Reveal.js/Marp presentations, draw.io architecture diagrams, one-pagers, proposal documents. Orchestrator with enriched assets over the underlying tool plugins.", diff --git a/.compiled/skill-plugins/create-shareable-skill/.claude-plugin/plugin.json b/.compiled/skill-plugins/create-shareable-skill/.claude-plugin/plugin.json new file mode 120000 index 0000000..6a3e9ac --- /dev/null +++ b/.compiled/skill-plugins/create-shareable-skill/.claude-plugin/plugin.json @@ -0,0 +1 @@ +../../../../skills/operations/create-shareable-skill/.plugin.json \ No newline at end of file diff --git a/.compiled/skill-plugins/create-shareable-skill/.cursor-plugin/plugin.json b/.compiled/skill-plugins/create-shareable-skill/.cursor-plugin/plugin.json new file mode 120000 index 0000000..6a3e9ac --- /dev/null +++ b/.compiled/skill-plugins/create-shareable-skill/.cursor-plugin/plugin.json @@ -0,0 +1 @@ +../../../../skills/operations/create-shareable-skill/.plugin.json \ No newline at end of file diff --git a/.compiled/skill-plugins/create-shareable-skill/skills/create-shareable-skill b/.compiled/skill-plugins/create-shareable-skill/skills/create-shareable-skill new file mode 120000 index 0000000..bec6e0c --- /dev/null +++ b/.compiled/skill-plugins/create-shareable-skill/skills/create-shareable-skill @@ -0,0 +1 @@ +../../../../skills/operations/create-shareable-skill \ No newline at end of file diff --git a/.ytstack/DECISIONS.md b/.ytstack/DECISIONS.md index ef172c6..b1096c6 100644 --- a/.ytstack/DECISIONS.md +++ b/.ytstack/DECISIONS.md @@ -220,3 +220,27 @@ Plugins that fail either criterion belong elsewhere, not here. **Chose:** Branch (`add-`) → atomic commit (`add `, CONTRIBUTING commit format) → push → `gh pr create --base main` → human signoff → merge. Never self-merge; never commit a new skill directly on `main`. **Reason:** CI (`compile.yml` + `secret-scan.yml`) re-runs compile + a gitleaks scan on the PR -- that gate only fires on a PR. A new catalog entry changes what installers receive and is hard to walk back once `main` moves, so it needs human review. This matches the existing CONTRIBUTING "PR. CI will re-run compile + audit" guidance and makes it explicit + non-optional. + +--- + +## 2026-05-14: `new-shareable-skill` ships as a standalone catalog skill (supersedes the `.agents/` placement) + +**Context:** The prior entry placed `new-shareable-skill` in `.agents/skills/` to avoid naming the private `yesterday-skills` catalog in a published artifact. The user rejected that on review: `new-shareable-skill` is to be a standalone, compiled, marketplace-published skill like any other -- "authoring a shareable skill" is itself a user-facing capability, not just internal tooling. + +**Chose:** Standalone skill at `skills/operations/new-shareable-skill/` (+ `.plugin.json`). Compiled by `compile.mjs`, listed in the marketplace (count 14 -> 15). Only `audit-skills` stays in `.agents/` -- it is pure verification machinery with no user-facing capability. + +**Reason:** User decision; user instructions outrank an agent's architectural judgement. The leak concern is handled at the content level instead of by hiding the file: the actual username path example was depersonalized, gratuitous pattern tokens were softened. The two catalogs are still named -- that was an explicit requirement ("der die policies dieses und des yesterday-skills repos kennt"), and `yesterday-skills` is not an `-internal`-suffixed repo. + +**Known consequence:** `references/quality-bar.md` documents leak patterns (grep commands, `-internal`, migration-framing examples). Now that the skill lives under `skills/` it is in `audit-skills`' scan scope, so axis-1 will surface known false positives from this skill's own pattern documentation -- the same reason `audit-skills` excludes `.agents/`. The clean structural fix, if the noise is unwanted, is to add `skills/operations/new-shareable-skill/references/` to `audit-skills`' `-not -path` exclusions; not done here because it modifies a second skill that was not in scope. + +**Supersedes:** "2026-05-14: `new-shareable-skill` lives in `.agents/skills/`, not the marketplace tree". The "meta-skill -> `.agents/`" rule from that entry no longer holds as a blanket rule; `.agents/` is now specifically for non-user-facing verification / build machinery. + +--- + +## 2026-05-14: Renamed `new-shareable-skill` -> `create-shareable-skill` + +**Context:** User review of PR #2. The slug `new-shareable-skill` reads as a state ("a skill that is new + shareable") rather than an action; the skill's job is to *create* a shareable skill from an idea or an existing one. + +**Chose:** Slug `create-shareable-skill`. Folder `skills/operations/create-shareable-skill/`, `.plugin.json` `name`, SKILL.md frontmatter `name`, the `digraph`, and every cross-reference (README, CONTRIBUTING, AGENTS, `.ytstack/` memory) renamed to match. `compile.mjs` re-run so the marketplace entry + `.compiled/skill-plugins/` symlink dir follow the slug. + +**Reason:** Slug = folder name = `.plugin.json` `name` (parity rule). An action-verb slug matches the catalog's other capability skills and is self-explanatory in a `/skills` list. The earlier entries above keep the old name verbatim -- DECISIONS.md is append-only and those record the decisions as they stood at the time. diff --git a/.ytstack/KNOWLEDGE.md b/.ytstack/KNOWLEDGE.md index 1372af0..525f310 100644 --- a/.ytstack/KNOWLEDGE.md +++ b/.ytstack/KNOWLEDGE.md @@ -29,5 +29,6 @@ Patterns, rules, and lessons learned while building skills. This file is read by - **No internal-perspective framing in user-facing files.** Phrases like "no Yesterday-infra dependencies", "generic-tauglich", "Yesterday-team needs ...", or "private companion catalog": all describe the catalog from Yesterday's vantage point. External users don't share that vantage. Frame from the user's perspective ("install with X", "requires SaaS account Y") instead. The acceptance criterion lives in DECISIONS.md. - **`allowCrossMarketplaceDependenciesOn` is a whitelist, not an installer.** It only PERMITS a plugin to depend on another marketplace's plugin. The user must still `/plugin marketplace add` the other marketplace and `/plugin install` the dep manually -- otherwise `/doctor` errors with "Dependency X not installed". Public-catalog bundles should therefore avoid cross-mp deps entirely (see DECISIONS.md "Public bundles avoid install-breaking cross-marketplace deps"). - **Sister repo `yesterday-skills` is kept at parity manually.** Both repos share `compile.mjs` + `clean.mjs` verbatim and both now have `.github/workflows/compile.yml` (sister's added 2026-05-13). When changing the compile pipeline, CI workflow, or OSS scaffold, apply to both. Sister also enforces folder-name === `plugin.json` name parity (its DECISIONS.md, 2026-05-13). -- **`.agents/skills/` is the home for meta-skills about the catalog**, not `skills/`. `compile.mjs` walks only `skills/`, so `.agents/` content is never compiled or published. Use `.agents/` when a skill would otherwise have to leak internal-perspective content to be published -- e.g. `audit-skills` (documents `-internal` patterns) and `new-shareable-skill` (knows the public↔private catalog routing). The leak audit explicitly excludes `.agents/` for this reason. See DECISIONS.md "`new-shareable-skill` lives in `.agents/skills/`". -- **Authoring a new skill: use `.agents/skills/new-shareable-skill/`.** It runs intake → quality gate → placement (public/private + standalone/bundle + category) → scaffold → `compile.mjs` + `audit-skills` → docs → PR. Counterpart to `audit-skills` (create vs. verify). +- **`.agents/skills/` is for non-user-facing verification / build machinery**, not user-facing capabilities. `compile.mjs` walks only `skills/`, so `.agents/` content is never compiled or published. `audit-skills` lives there (pure verification machinery). `create-shareable-skill` does NOT -- it ships as a standalone catalog skill (see DECISIONS.md 2026-05-14 supersede entry; the earlier `.agents/` placement was reversed on user review). +- **Authoring a new skill: use `create-shareable-skill`** (`skills/operations/create-shareable-skill/`). It runs intake → quality gate → placement (catalog + standalone/bundle + category) → scaffold → `compile.mjs` + `audit-skills` → docs → PR. Counterpart to `audit-skills` (create vs. verify). +- **A skill that documents leak patterns trips `audit-skills`' own axis-1 scan once it lives under `skills/`.** `create-shareable-skill/references/quality-bar.md` is the live example. Known false positives; structural fix is an `audit-skills` exclusion path. diff --git a/.ytstack/M001-CONTEXT.md b/.ytstack/M001-CONTEXT.md index 4f39055..84729c9 100644 --- a/.ytstack/M001-CONTEXT.md +++ b/.ytstack/M001-CONTEXT.md @@ -9,7 +9,7 @@ size: M ## Goal -Ein `new-shareable-skill` Metaskill, der Agent/User durch das Shareable-Machen eines +Ein `create-shareable-skill` Metaskill, der Agent/User durch das Shareable-Machen eines bestehenden oder das Neuerstellen eines Skills führt: Routing ins richtige Repo (public `skills` vs. privates `yesterday-skills`) und Placement (standalone + Kategorie vs. Bundle-Erweiterung mit Confirmation), Qualitäts-Gate, Doku-Updates, PR auf main -- @@ -17,7 +17,7 @@ abgeglichen mit der company-orga AI-Skills-Strategie. ## Exit criteria -- `new-shareable-skill` SKILL.md liegt in der richtigen Kategorie, `node compile.mjs` +- `create-shareable-skill` SKILL.md liegt in der richtigen Kategorie, `node compile.mjs` läuft sauber durch, der Skill erscheint im Marketplace-Output. - Skill kodiert die Repo-Policies: public-installability, no-internal-perspective, folder/name-Parität, standalone-vs-bundle Entscheidungsbaum, public-vs-private @@ -33,12 +33,14 @@ M -- see `M001-ROADMAP.md` for slice breakdown. ## Decisions locked in discuss phase -- 2026-05-14: `new-shareable-skill` lebt in `.agents/skills/`, NICHT im Marketplace-`skills/`-Baum - -- weil es das public↔private Catalog-Routing kennen muss; das Benennen des privaten - `yesterday-skills`-Repos in einem marketplace-publizierten Skill wäre genau der - internal-perspective-Leak, den die Repo-Regeln verbieten. `.agents/` ist Contributor-Tooling - (wie `audit-skills`), von der no-internal-perspective-Regel ausgenommen. Voller Eintrag in - `DECISIONS.md`. +- 2026-05-14 (REVIDIERT, siehe nächster Punkt): zunächst entschieden, `create-shareable-skill` in + `.agents/skills/` zu legen statt im Marketplace-`skills/`-Baum -- wegen des Leak-Risikos beim + Benennen des privaten `yesterday-skills`-Repos. Per PR #1 so umgesetzt. +- 2026-05-14: Auf User-Review revidiert -- `create-shareable-skill` ist ein **standalone Catalog-Skill** + unter `skills/operations/create-shareable-skill/`, kompiliert + im Marketplace gelistet (Count 14→15). + Authoring ist selbst eine user-facing Capability. Nur `audit-skills` bleibt in `.agents/` + (reine Verifikations-Maschinerie). User-Anweisung schlägt Agent-Architektur-Urteil. Voller + Eintrag + Supersede in `DECISIONS.md`. - 2026-05-14: Kein Mirror im privaten `yesterday-skills`. Der Skill *kennt* beide Kataloge und routet zwischen ihnen; er muss nicht doppelt existieren. Ein Repo, ein Skill. - 2026-05-14: Policies werden NICHT dupliziert -- der Skill verweist auf die Single Source of diff --git a/.ytstack/M001-ROADMAP.md b/.ytstack/M001-ROADMAP.md index 6d885a0..e7afc97 100644 --- a/.ytstack/M001-ROADMAP.md +++ b/.ytstack/M001-ROADMAP.md @@ -10,14 +10,14 @@ completed_slices: 1 # M001 Roadmap -**Goal:** Ein `new-shareable-skill` Metaskill, der Agent/User durch das Shareable-Machen +**Goal:** Ein `create-shareable-skill` Metaskill, der Agent/User durch das Shareable-Machen eines bestehenden oder das Neuerstellen eines Skills führt: Routing ins richtige Repo (public `skills` vs. privates `yesterday-skills`) und Placement (standalone + Kategorie vs. Bundle-Erweiterung mit Confirmation), Qualitäts-Gate, Doku-Updates, PR auf main -- abgeglichen mit der company-orga AI-Skills-Strategie. **Exit criteria:** -- `new-shareable-skill` SKILL.md liegt in der richtigen Kategorie, `node compile.mjs` +- `create-shareable-skill` SKILL.md liegt in der richtigen Kategorie, `node compile.mjs` läuft sauber durch, der Skill erscheint im Marketplace-Output. - Skill kodiert die Repo-Policies: public-installability, no-internal-perspective, folder/name-Parität, standalone-vs-bundle Entscheidungsbaum, public-vs-private @@ -33,16 +33,18 @@ Executed directly without a formal slice/task pass, on explicit user instruction ("DU SOLLST DAS IMPLEMENTIEREN ... JETZT, BIS ZUM ENDE"). User instructions take precedence over the ytstack flow (`using-ytstack`: instruction priority 1). -- [x] S01 -- `new-shareable-skill` meta-skill + contributor docs - - `.agents/skills/new-shareable-skill/SKILL.md` -- end-to-end authoring workflow - - `.agents/skills/new-shareable-skill/references/placement.md` -- catalog / form / category routing - - `.agents/skills/new-shareable-skill/references/quality-bar.md` -- shareable-by-default gates + templates - - `CONTRIBUTING.md`, `AGENTS.md` -- reference the meta-skill - - Verified: `node compile.mjs` clean, marketplace count unchanged at 14 (skill is `.agents/` tooling, not compiled), leak scan on new files clean +- [x] S01 -- `create-shareable-skill` standalone catalog skill + contributor docs + - `skills/operations/create-shareable-skill/SKILL.md` -- end-to-end authoring workflow + - `skills/operations/create-shareable-skill/.plugin.json` -- marketplace manifest + - `skills/operations/create-shareable-skill/references/placement.md` -- catalog / form / category routing + - `skills/operations/create-shareable-skill/references/quality-bar.md` -- shareable-by-default gates + templates + - `README.md`, `CONTRIBUTING.md`, `AGENTS.md` -- catalog table + reference the skill + - Verified: `node compile.mjs` clean, marketplace count 14 -> 15 (skill compiled + listed), `.plugin.json` symlinked + - Note: first delivered (PR #1) under `.agents/skills/`; moved to standalone on user review ## Run order -Single slice, done. Delivered via PR branch `add-new-shareable-skill` (push pending). +Single slice, done. PR #1 (`.agents/` placement) merged, then PR #2 moved it to standalone. ## How to update this file diff --git a/.ytstack/STATE.md b/.ytstack/STATE.md index 951ae5c..72f9158 100644 --- a/.ytstack/STATE.md +++ b/.ytstack/STATE.md @@ -9,11 +9,11 @@ active_task: none # State -**Status:** M001 done -- `new-shareable-skill` meta-skill authored in `.agents/skills/` + contributor docs updated. Executed directly (no formal slice/task pass) on explicit user instruction. PR pending push. +**Status:** M001 done -- `create-shareable-skill` is a standalone catalog skill at `skills/operations/create-shareable-skill/` + contributor docs updated. Executed directly (no formal slice/task pass) on explicit user instruction. Initial `.agents/` placement was reversed on user review (see DECISIONS.md supersede entry). -**Next action:** Push branch `add-new-shareable-skill` and open the PR to `main` (awaiting user "push" go-ahead). +**Next action:** None pending for M001. Run `ytstack:reassess-roadmap` if continuing. -**Catalog context:** Public catalog live at `Yesterday-AI/skills` with 14 plugins (1 external + 4 bundles + 9 standalone). Compile pipeline working, marketplace symlinks generated, GitHub Actions workflow in place. Open question on plugin install path (cache resolution). +**Catalog context:** Public catalog live at `Yesterday-AI/skills` with 15 plugins (1 external + 4 bundles + 10 standalone). Compile pipeline working, marketplace symlinks generated, GitHub Actions workflow in place. Open question on plugin install path (cache resolution). ## What's done @@ -24,7 +24,7 @@ active_task: none - OSS scaffold: README, LICENSE (MIT), CONTRIBUTING, NOTICE, AGENTS.md - `.ytstack/` project memory (this file + DECISIONS, KNOWLEDGE, RUNTIME, PROJECT, PREFERENCES) - `.agents/skills/audit-skills/` -- 3-axis repo audit skill (leaks, consistency, spec compliance) -- `.agents/skills/new-shareable-skill/` -- authoring meta-skill: intake → quality gate → public/private + standalone/bundle placement → scaffold → compile+audit → docs → PR (M001; counterpart to audit-skills) +- `skills/operations/create-shareable-skill/` -- standalone authoring skill: intake → quality gate → catalog + standalone/bundle placement → scaffold → compile+audit → docs → PR (M001; counterpart to audit-skills) - GitHub Actions: `compile.yml` (auto-recompile on main push, PAT-pushed via `COMPILE_PUSH_TOKEN`, bot identity from `vars.BOT_NAME` / `vars.BOT_EMAIL`); `secret-scan.yml` (gitleaks) - Repo created on GitHub (Yesterday-AI/skills, public), 12 topics set - Sister repo `Yesterday-AI/yesterday-skills` (private catalog) brought to parity: same compile pipeline, OSS scaffold, `.ytstack/`, and as of 2026-05-13 also `compile.yml` + folder/name parity rule + normalized bundle READMEs diff --git a/AGENTS.md b/AGENTS.md index fe34d5b..70fb223 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,7 +23,7 @@ A single Node script (`compile.mjs`) discovers both and produces `.compiled/skil | Task | Where to edit | |---|---| -| Author / promote a skill (guided) | `.agents/skills/new-shareable-skill/SKILL.md` -- walks intake → quality gate → placement → scaffold → compile + audit → docs → PR | +| Author / promote a skill (guided) | `skills/operations/create-shareable-skill/SKILL.md` -- walks intake → quality gate → placement → scaffold → compile + audit → docs → PR | | Add a standalone skill | `skills///SKILL.md` (+ optional `.plugin.json`), then `node compile.mjs` | | Add a bundle | `plugins//plugin.json` (canonical), then `node compile.mjs` | | Add an external plugin (github-hosted) | `marketplace.json` (top-level, `plugins[]` array), then `node compile.mjs` | diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e53ee32..fb27485 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,7 +26,7 @@ Catalog repos rot when they accumulate plugin-side concerns. This repo has three ## Authoring a new skill (guided) -The fastest correct path is the `new-shareable-skill` agent skill at [`.agents/skills/new-shareable-skill/SKILL.md`](./.agents/skills/new-shareable-skill/SKILL.md). It walks one skill end to end -- intake, the "shareable by default" quality gate, the public-vs-private and standalone-vs-bundle placement decision, category selection, scaffold, `compile.mjs` + `audit-skills`, docs, and the PR to `main`. It refuses to scaffold a skill that cannot meet the bar. +The fastest correct path is the `create-shareable-skill` skill at [`skills/operations/create-shareable-skill/SKILL.md`](./skills/operations/create-shareable-skill/SKILL.md). It walks one skill end to end -- intake, the "shareable by default" quality gate, the public-vs-private and standalone-vs-bundle placement decision, category selection, scaffold, `compile.mjs` + `audit-skills`, docs, and the PR to `main`. It refuses to scaffold a skill that cannot meet the bar. The sections below are the manual reference for each step it automates. diff --git a/README.md b/README.md index c6d555d..bad85fa 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,7 @@ No auth required -- this catalog is public. ## What's in the catalog -14 plugins total: 1 external, 4 bundles, 9 standalone skills. +15 plugins total: 1 external, 4 bundles, 10 standalone skills. ### Bundles (`./plugins/`) @@ -90,6 +90,7 @@ No auth required -- this catalog is public. | Skill | Purpose | |---|---| +| [create-shareable-skill](./skills/operations/create-shareable-skill) | Author a catalog-ready skill: quality gate, placement routing, scaffold, docs, PR | | [paperclip-api](./skills/development-operations/paperclip-api) | Paperclip AI REST API client (companies, agents, issues, budgets) | #### Travel diff --git a/skills/operations/create-shareable-skill/.plugin.json b/skills/operations/create-shareable-skill/.plugin.json new file mode 100644 index 0000000..f069719 --- /dev/null +++ b/skills/operations/create-shareable-skill/.plugin.json @@ -0,0 +1,17 @@ +{ + "name": "create-shareable-skill", + "description": "Turn an existing skill or a fresh idea into a catalog-ready shareable skill -- run the quality gate, decide catalog and standalone-vs-bundle placement, pick the category, scaffold SKILL.md (+ optional .plugin.json), update the catalog docs, and open a PR. Use when adding a new skill to the catalog or promoting a personal skill into a shareable one.", + "author": { + "name": "Yesterday" + }, + "homepage": "https://github.com/Yesterday-AI/skills/tree/main/.compiled/skill-plugins/create-shareable-skill", + "repository": "https://github.com/Yesterday-AI/skills", + "license": "MIT", + "keywords": [ + "claude-code", + "yesterday", + "skill-authoring", + "meta", + "contributing" + ] +} diff --git a/.agents/skills/new-shareable-skill/SKILL.md b/skills/operations/create-shareable-skill/SKILL.md similarity index 89% rename from .agents/skills/new-shareable-skill/SKILL.md rename to skills/operations/create-shareable-skill/SKILL.md index 2482bf0..e4762a5 100644 --- a/.agents/skills/new-shareable-skill/SKILL.md +++ b/skills/operations/create-shareable-skill/SKILL.md @@ -1,16 +1,15 @@ --- -name: new-shareable-skill +name: create-shareable-skill description: Turn an existing skill or a fresh idea into a catalog-ready shareable skill -- run the quality gate, decide public-vs-private catalog and standalone-vs-bundle placement, pick the category, scaffold SKILL.md (+ optional .plugin.json), update the catalog docs, and open a PR to main. Use when adding a new skill to this repo, promoting a personal or ad-hoc skill into a shareable one, or routing a skill into the right catalog. metadata: - category: authoring - scope: repo-local + category: skill-authoring --- -# new-shareable-skill +# create-shareable-skill -The authoring counterpart to [`audit-skills`](../audit-skills/SKILL.md): `audit-skills` verifies what is already in the catalog, `new-shareable-skill` gets a skill *into* the catalog correctly. It walks one skill end to end -- intake, quality gate, placement decision, scaffold, compile + audit, docs, PR -- and refuses to scaffold a skill that cannot meet the bar. +The authoring counterpart to `audit-skills` (`.agents/skills/audit-skills/SKILL.md`): `audit-skills` verifies what is already in the catalog, `create-shareable-skill` gets a skill *into* the catalog correctly. It walks one skill end to end -- intake, quality gate, placement decision, scaffold, compile + audit, docs, PR -- and refuses to scaffold a skill that cannot meet the bar. -This skill is **repo-local tooling**, not a marketplace plugin. It lives in `.agents/skills/` because it must reason about the private `yesterday-skills` catalog and the public↔private routing rules -- naming the private catalog in a marketplace-published skill would be exactly the internal-perspective leak the catalog rules forbid. `compile.mjs` only walks `skills/`, so this skill is never compiled or published. +`create-shareable-skill` is itself a standalone skill in the catalog (`skills/operations/create-shareable-skill/`), discovered and compiled by `compile.mjs` like any other. `audit-skills` stays repo-local tooling under `.agents/skills/` because it is pure verification machinery; this skill is the user-facing authoring workflow, so it ships in the catalog. ## When to use @@ -53,7 +52,7 @@ Apply [`references/quality-bar.md`](references/quality-bar.md) -- the "shareable - **Depersonalize.** Strip usernames in paths, personal hostnames, personal tokens/keys, personal handles. (Blocking in *both* catalogs.) - **Self-contained.** The skill carries its own knowledge in `SKILL.md` + `references/`. No links to private notes, no un-shared paths, no "ask ". -- **No internal-perspective framing** in user-facing fields (description, README, frontmatter, `.plugin.json`). Write from the user's vantage ("install with X", "requires SaaS Y"), not Yesterday's ("no Yesterday-infra deps", "formerly Z"). Migration / org framing belongs in `.ytstack/DECISIONS.md`. +- **No internal-perspective framing** in user-facing fields (description, README, frontmatter, `.plugin.json`). Write from the user's vantage ("install with X", "requires SaaS Y"), not the maintainer org's (infra-dependency disclaimers, rename / migration history). Migration / org framing belongs in `.ytstack/DECISIONS.md`. - **Description line.** One paragraph, says what the skill does AND when to invoke it. Routing depends entirely on this line (Anthropic Progressive Disclosure level 1) -- vague description = the skill never fires. - **Slug.** Specific, self-explanatory, kebab-case, collision-free. Names the concrete capability, not the tool or domain in general (`github-worktrees`, not `github`). Slug = folder name = `.plugin.json` `name`. @@ -114,7 +113,7 @@ CI (`.github/workflows/compile.yml` + `secret-scan.yml`) re-runs compile + a git ## Decision flow ```dot -digraph new_shareable_skill { +digraph create_shareable_skill { "Intake: source + capability" [shape=box]; "Quality gate" [shape=box]; "Clears the bar?" [shape=diamond]; @@ -153,7 +152,7 @@ digraph new_shareable_skill { Report each phase as you complete it. End with a summary block: ``` -new-shareable-skill: +create-shareable-skill: Catalog: public skills | private yesterday-skills Form: standalone (skills///) | bundle member of Quality: issues found, fixed (depersonalization, framing, description, slug) @@ -176,8 +175,8 @@ new-shareable-skill: - [`references/placement.md`](references/placement.md) -- public-vs-private, standalone-vs-bundle, category selection, with the current repo facts - [`references/quality-bar.md`](references/quality-bar.md) -- the shareable-by-default checklist, the `SKILL.md` + `.plugin.json` templates, the depersonalization checklist -- [`../audit-skills/SKILL.md`](../audit-skills/SKILL.md) -- the verification counterpart; run it as step 5 +- `audit-skills` (`.agents/skills/audit-skills/SKILL.md`) -- the verification counterpart; run it as step 5 - `CONTRIBUTING.md` -- adding a standalone skill / bundle / external; commit message format; versioning policy - `AGENTS.md` -- hard rules for agents working on this repo -- `.ytstack/DECISIONS.md` -- public-installability acceptance criterion; no-internal-perspective rule; no-`version` policy +- `.ytstack/DECISIONS.md` -- public-installability acceptance criterion; the internal-perspective-framing rule; no-`version` policy - company-orga `03_technologies/32_strategy/04_ai-skills-und-plugins.md` -- the "shareable by default" quality standard and the two-catalog strategy diff --git a/.agents/skills/new-shareable-skill/references/placement.md b/skills/operations/create-shareable-skill/references/placement.md similarity index 92% rename from .agents/skills/new-shareable-skill/references/placement.md rename to skills/operations/create-shareable-skill/references/placement.md index ceb3a18..f2b6008 100644 --- a/.agents/skills/new-shareable-skill/references/placement.md +++ b/skills/operations/create-shareable-skill/references/placement.md @@ -74,6 +74,6 @@ Naming rules for the slug (also enforced by `audit-skills`): | Public bundle member (dependency) | standalone path above + `` added to `plugins//plugin.json` `dependencies[]` -- **confirm first** | | Private standalone | `skills///SKILL.md` in `Yesterday-AI/yesterday-skills` | | Private bundle member | `plugins//...` in `Yesterday-AI/yesterday-skills` -- **confirm first** | -| Repo-local tooling (meta-skill about the catalog itself) | `.agents/skills//SKILL.md` -- not compiled, not published; this is where a skill lives if publishing it would force an internal-perspective leak | +| Repo-local tooling (pure verification / build machinery) | `.agents/skills//SKILL.md` -- not compiled, not published | -The last row is why this very skill (`new-shareable-skill`) and `audit-skills` live under `.agents/skills/` instead of `skills/`. +The last row is where `audit-skills` lives -- it is pure verification machinery, not a user-facing capability, so it stays repo-local. `create-shareable-skill` itself ships in the catalog as a standalone skill (`skills/operations/create-shareable-skill/`): authoring a shareable skill *is* a user-facing capability. diff --git a/.agents/skills/new-shareable-skill/references/quality-bar.md b/skills/operations/create-shareable-skill/references/quality-bar.md similarity index 93% rename from .agents/skills/new-shareable-skill/references/quality-bar.md rename to skills/operations/create-shareable-skill/references/quality-bar.md index 131a446..d08cf01 100644 --- a/.agents/skills/new-shareable-skill/references/quality-bar.md +++ b/skills/operations/create-shareable-skill/references/quality-bar.md @@ -1,6 +1,6 @@ # Quality bar -- shareable by default -A skill is only a good skill if someone else -- a colleague, a customer, a stranger's Claude Code -- can install and use it with no follow-up questions. Every item below is a gate, not a suggestion. If a skill cannot pass, `new-shareable-skill` stops and reports the gap instead of scaffolding it. +A skill is only a good skill if someone else -- a colleague, a customer, a stranger's Claude Code -- can install and use it with no follow-up questions. Every item below is a gate, not a suggestion. If a skill cannot pass, `create-shareable-skill` stops and reports the gap instead of scaffolding it. ## The gates @@ -8,8 +8,8 @@ A skill is only a good skill if someone else -- a colleague, a customer, a stran No personal data survives into a shared skill -- not even in the private catalog. -- No usernames in paths -- `/Users/alex/...`, `/home//...`, `C:\Users\\...` -> `/Users//` or strip the path entirely -- No personal hostnames / machine names / LAN IPs (`192.168.x.x`, `*.local`, `*.lan`, personal NAS names) +- No usernames in paths -- `/Users//...`, `/home//...`, `C:\Users\\...` -> replace the username with a placeholder or strip the path entirely +- No personal hostnames / machine names / LAN IPs (RFC1918 ranges like 192.168/16 or 10/8, `*.local`, `*.lan`, personal NAS names) - No personal tokens / keys (`sk-…`, `ghp_…`, `xox[baprs]-…`, `AKIA…`) -- revoke and remove - No personal handles, real contributor names (other than the `Yesterday` org / public author handles), private emails - No browser bookmarks, session cookies, OAuth callback URLs with state tokens