@olegkoval/agent-skills 1.0.0-beta.1 → 1.0.0

package/.claude-plugin/marketplace.json

@@ -1,58 +1,16 @@
 {
-  "name": "agent skills",
+  "name": "olko-agent-skills",
   "owner": {
     "name": "Oleg Koval"
   },
+  "metadata": {
+    "description": "Agent-agnostic skill catalog for Codex, Claude, Cursor, and other skill-aware tools."
+  },
   "plugins": [
     {
-      "name": "olko:docs-index-keeper",
-      "source": "./packages/software-development/docs-index-keeper/adapters/claude",
-      "description": "Keep a Markdown docs index in sync through pre-commit, CI, or one-off maintenance flows."
-    },
-    {
-      "name": "olko:semantic-release-beta",
-      "source": "./packages/software-development/semantic-release-beta/adapters/claude",
-      "description": "Set up semantic-release-npm-github-publish with stable main releases and prerelease beta releases on a beta branch."
-    },
-    {
-      "name": "olko:changelog-generator",
-      "source": "./packages/software-development/changelog-generator/adapters/claude",
-      "description": "Generate user-facing changelogs and release notes from git history."
-    },
-    {
-      "name": "olko:gh-cli",
-      "source": "./packages/software-development/gh-cli/adapters/claude",
-      "description": "Use the GitHub CLI effectively for repositories, PRs, Actions, releases, and more."
-    },
-    {
-      "name": "olko:git-commit",
-      "source": "./packages/software-development/git-commit/adapters/claude",
-      "description": "Create conventional commits with diff-aware staging and message generation."
-    },
-    {
-      "name": "olko:gallery",
-      "source": "./packages/photography/gallery/adapters/claude",
-      "description": "Create photo galleries with AI-assisted layout curation and sequencing."
-    },
-    {
-      "name": "olko:promptctl",
-      "source": "./packages/software-development/promptctl/adapters/claude",
-      "description": "Use promptctl for template-based prompt engineering, scoring, and workflow automation."
-    },
-    {
-      "name": "olko:fill-music-player",
-      "source": "./packages/music/fill-music-player/adapters/claude",
-      "description": "Fill a portable music player with a curated random selection from a source music library while balancing formats, artists, albums, and capacity."
-    },
-    {
-      "name": "olko:product-builder",
-      "source": "./packages/software-development/product-builder/adapters/claude",
-      "description": "Build a full-stack web application or SaaS product from a user description using production-oriented defaults."
-    },
-    {
-      "name": "olko:viral-launch",
-      "source": "./packages/marketing/viral-launch/adapters/claude",
-      "description": "Set up a project repository and launch plan for shareable marketing, public launch readiness, and growth loops."
+      "name": "olko-agent-skills",
+      "source": "./",
+      "description": "Agent-agnostic skill catalog for Codex, Claude, Cursor, and other skill-aware tools."
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -0,0 +1,23 @@
+{
+  "name": "olko-agent-skills",
+  "description": "Agent-agnostic skill catalog for Codex, Claude, Cursor, and other skill-aware tools.",
+  "version": "1.0.0-beta.1",
+  "author": {
+    "name": "Oleg Koval"
+  },
+  "homepage": "https://github.com/oleg-koval/agent-skills",
+  "repository": "https://github.com/oleg-koval/agent-skills",
+  "license": "MIT",
+  "skills": [
+    "./packages/software-development/docs-index-keeper",
+    "./packages/software-development/semantic-release-beta",
+    "./packages/software-development/changelog-generator",
+    "./packages/software-development/gh-cli",
+    "./packages/software-development/git-commit",
+    "./packages/photography/gallery",
+    "./packages/software-development/promptctl",
+    "./packages/music/fill-music-player",
+    "./packages/software-development/product-builder",
+    "./packages/marketing/viral-launch"
+  ]
+}

package/.cursor-plugin/index.json

@@ -1,5 +1,5 @@
 {
-  "name": "agent skills",
+  "name": "agent-skills",
   "plugins": [
     {
       "name": "olko:docs-index-keeper",

package/README.md

@@ -27,29 +27,128 @@ These skills are opinionated by design. They encode working defaults, preferred
 - Keep catalogs neutral and machine-readable.
 - Add marketplace-specific metadata on top of the canonical package, not instead of it.
 
-## Packages
+## Quick Start
+
+<details>
+<summary><b>Codex</b></summary>
+
+Install all package symlinks into your local Codex skills directory:
+
+```bash
+git clone https://github.com/oleg-koval/agent-skills.git
+cd agent-skills
+./scripts/install-codex-symlinks.sh
+```
+
+Then mention a lookup name in a new Codex session:
+
+```text
+Use the olko:semantic-release-beta skill to add prereleases on a beta branch.
+```
+
+</details>
+
+<details>
+<summary><b>Claude Code</b></summary>
+
+The repository includes a generated Claude marketplace manifest at `.claude-plugin/marketplace.json`.
+
+For local development, clone the repo and point Claude Code at the plugin directory:
+
+```bash
+git clone https://github.com/oleg-koval/agent-skills.git
+claude --plugin-dir /path/to/agent-skills
+```
+
+If your Claude Code environment supports GitHub marketplace installs for this repo, add the marketplace source first:
+
+```text
+/plugin marketplace add oleg-koval/agent-skills
+```
+
+Then install the catalog plugin:
+
+```text
+/plugin install olko-agent-skills@olko-agent-skills
+```
+
+Live Claude marketplace install is not yet validated for this repo.
+
+</details>
+
+<details>
+<summary><b>Cursor</b></summary>
+
+The repository includes a generated Cursor plugin index at `.cursor-plugin/index.json` and per-package Cursor adapters under `packages/*/*/adapters/cursor/`.
+
+For a single project, copy the relevant `SKILL.md` or adapter content into `.cursor/rules/`, or reference the full package directory from your Cursor rules.
+
+</details>
+
+<details>
+<summary><b>GitHub Copilot</b></summary>
+
+Use the generated repository instructions and prompt files:
+
+```text
+.github/copilot-instructions.md
+.github/prompts/*.prompt.md
+```
+
+These files are generated from `catalog/skills.json` and can be copied into a repository that should use the same skill guidance.
+
+</details>
+
+<details>
+<summary><b>Other agents</b></summary>
+
+Skills are plain Markdown. Use the canonical package file directly:
+
+```text
+packages/{category}/{skill}/SKILL.md
+```
+
+Agent-specific wrappers live under:
+
+```text
+packages/{category}/{skill}/adapters/
+```
+
+</details>
+
+## All 10 Skills
+
+These packages are the entry points. Each one is a structured workflow with concrete trigger conditions and execution steps. You can reference any skill directly by its `olko:*` lookup name.
 
 ### Software development
 
-- `docs-index-keeper`
-- `semantic-release-beta`
-- `changelog-generator`
-- `gh-cli`
-- `git-commit`
-- `promptctl`
-- `product-builder`
+| Skill | What It Does | Use When |
+|-------|-------------|----------|
+| [docs-index-keeper](packages/software-development/docs-index-keeper/SKILL.md) | Keeps a Markdown docs index in sync through pre-commit, CI, or one-off maintenance flows | A repo has `docs/` and needs `docs/README.md` or another Markdown index updated automatically |
+| [semantic-release-beta](packages/software-development/semantic-release-beta/SKILL.md) | Sets up `semantic-release-npm-github-publish` with stable `main` releases and beta prereleases | A Node package needs stable npm publishing plus beta prereleases from a `beta` branch |
+| [changelog-generator](packages/software-development/changelog-generator/SKILL.md) | Generates user-facing changelogs and release notes from git history | Preparing release notes, app store update text, customer changelogs, or internal release summaries |
+| [gh-cli](packages/software-development/gh-cli/SKILL.md) | Guides GitHub CLI usage for repos, PRs, Actions, releases, issues, and related GitHub operations | Working with GitHub from the command line and needing reliable `gh` commands |
+| [git-commit](packages/software-development/git-commit/SKILL.md) | Creates conventional commits with diff-aware staging and message generation | The user asks to commit changes or wants a conventional commit message from the current diff |
+| [promptctl](packages/software-development/promptctl/SKILL.md) | Uses `promptctl` for reusable prompt templates, scoring, and workflow automation | A project needs prompt conventions, prompt review, prompt scoring, or reusable prompt workflows |
+| [product-builder](packages/software-development/product-builder/SKILL.md) | Builds a full-stack web app or SaaS product from a user description using production-oriented defaults | The user asks to build a complete app, SaaS, dashboard, or product rather than a prototype |
 
 ### Music
 
-- `fill-music-player`
+| Skill | What It Does | Use When |
+|-------|-------------|----------|
+| [fill-music-player](packages/music/fill-music-player/SKILL.md) | Fills a portable music player with a curated random music selection while balancing formats, artists, albums, and capacity | Copying music from a NAS or local library to a Walkman, iPod, USB drive, or similar device |
 
 ### Marketing
 
-- `viral-launch`
+| Skill | What It Does | Use When |
+|-------|-------------|----------|
+| [viral-launch](packages/marketing/viral-launch/SKILL.md) | Sets up a project repository and launch plan for shareable marketing, public launch readiness, and growth loops | Preparing a repo, product, open-source package, waitlist, or creator tool for public launch |
 
 ### Photography
 
-- `gallery`
+| Skill | What It Does | Use When |
+|-------|-------------|----------|
+| [gallery](packages/photography/gallery/SKILL.md) | Creates photo galleries with AI-assisted layout curation and sequencing | Building a gallery from photos or planning photo layout, sequencing, and curation |
 
 ## How to use skills
 
@@ -90,6 +189,57 @@ When adding or changing a skill:
 
 These are generated from the neutral package inventory and kept in the repo for platform-specific consumption.
 
+## How Skills Work
+
+Every package follows a consistent anatomy:
+
+```text
+packages/{category}/{skill}/
+├── SKILL.md              # Required canonical skill definition
+├── references/           # Optional supporting material loaded only when needed
+└── adapters/             # Optional agent-specific wrappers
+    ├── codex/
+    ├── claude/
+    └── cursor/
+```
+
+Key design choices:
+
+- Process over prose: skills are workflows agents follow, not generic reference essays.
+- Progressive disclosure: `SKILL.md` is the entry point; supporting files load only when needed.
+- Adapter separation: Codex, Claude, Cursor, and Copilot metadata wrap the canonical package instead of forking it.
+- Verifiable changes: catalog and manifest changes should pass `./scripts/validate-catalog.sh`.
+
+See [docs/skill-anatomy.md](docs/skill-anatomy.md) for the package format.
+
+## Project Structure
+
+```text
+agent-skills/
+├── packages/                         # Canonical skill packages
+│   ├── software-development/
+│   │   ├── docs-index-keeper/
+│   │   ├── semantic-release-beta/
+│   │   ├── changelog-generator/
+│   │   ├── gh-cli/
+│   │   ├── git-commit/
+│   │   ├── promptctl/
+│   │   └── product-builder/
+│   ├── music/
+│   │   └── fill-music-player/
+│   ├── marketing/
+│   │   └── viral-launch/
+│   └── photography/
+│       └── gallery/
+├── catalog/                          # Machine-readable package inventory
+├── collections/                      # Grouped package bundles
+├── scripts/                          # Build, validation, sync, and install helpers
+├── .claude-plugin/                   # Generated Claude marketplace manifest
+├── .cursor-plugin/                   # Generated Cursor plugin index
+├── .github/prompts/                  # Generated GitHub Copilot prompt files
+└── docs/                             # Contributor and package format docs
+```
+
 ## Install and test
 
 ### Codex

package/catalog/skills.json

@@ -1,5 +1,5 @@
 {
-  "name": "agent skills",
+  "name": "agent-skills",
   "packages": [
     {
       "name": "docs-index-keeper",

package/docs/skill-anatomy.md

@@ -0,0 +1,191 @@
+# Skill Anatomy
+
+This document describes the structure and format of skill packages in this repository. Use it when adding a new package, reviewing an existing skill, or updating generated adapters.
+
+## File Location
+
+Every skill lives in its own category directory under `packages/`:
+
+```text
+packages/
+  category-name/
+    skill-name/
+      SKILL.md            # Required canonical skill definition
+      references/         # Optional supporting material loaded on demand
+      adapters/           # Optional agent-specific wrappers
+        codex/
+        claude/
+        cursor/
+```
+
+Examples:
+
+```text
+packages/software-development/semantic-release-beta/SKILL.md
+packages/music/fill-music-player/SKILL.md
+packages/photography/gallery/SKILL.md
+```
+
+## SKILL.md Format
+
+### Frontmatter
+
+Every `SKILL.md` starts with YAML frontmatter:
+
+```yaml
+---
+name: skill-name-with-hyphens
+description: Brief statement of what the skill does. Use when specific trigger conditions apply.
+license: MIT
+compatibility: Codex, Claude Code, Cursor, GitHub Copilot, and other Agent Skills compatible tools.
+metadata:
+  author: Oleg Koval
+  tags:
+    - tag-name
+---
+```
+
+Rules:
+
+- `name`: lowercase, hyphen-separated, and matching the package directory name.
+- `description`: concise activation guidance; include what the skill does and when to use it.
+- `license`: include when the source package carries an explicit license.
+- `compatibility`: state supported agent/tool assumptions and any required local tooling.
+- `metadata.tags`: keep tags practical for catalog discovery.
+
+The frontmatter feeds generated manifests and adapter files, so keep it accurate and avoid long process summaries.
+
+## Standard Sections
+
+Use sections that make the skill executable by an agent. Exact headings can vary by workflow, but strong skills usually include:
+
+```markdown
+# Skill Title
+
+## Overview
+One or two sentences explaining the outcome the skill produces.
+
+## When to Use
+- Concrete trigger phrases or task types
+- Exclusions when the skill should not run
+
+## Workflow
+Numbered steps the agent should follow.
+
+## Commands
+Exact commands, flags, or file paths when relevant.
+
+## Verification
+- [ ] Evidence that proves the work completed successfully
+- [ ] Tests, build output, generated files, or manual checks to report
+```
+
+## Section Purposes
+
+### Overview
+
+State the skill's job and expected outcome. Keep this short enough that the workflow remains the source of truth.
+
+### When to Use
+
+List concrete triggers. Good triggers are user phrases, repository conditions, or task types. Avoid vague statements such as "use for better quality."
+
+### Workflow
+
+The workflow is the core of the skill. It should be specific enough for an agent to execute without inventing missing steps.
+
+Good:
+
+```text
+Run `./scripts/validate-catalog.sh` after changing catalog paths.
+```
+
+Bad:
+
+```text
+Make sure the catalog is good.
+```
+
+### Commands
+
+Include exact commands when a tool is part of the workflow. Prefer existing repo scripts over one-off shell fragments.
+
+### Verification
+
+Verification is the exit criteria. Every item should be evidence-backed: test output, command output, generated files, screenshots, or a documented manual check.
+
+## Supporting Files
+
+Create supporting files only when they reduce the main `SKILL.md` size or keep specialized detail out of the primary workflow.
+
+Use `references/` for:
+
+- long checklists
+- example templates
+- provider-specific notes
+- detailed command references
+
+Keep short operational guidance in `SKILL.md` so the skill remains self-contained.
+
+## Adapters
+
+Adapters are wrappers for agent-specific packaging. They should point back to the canonical skill package and avoid duplicating business logic.
+
+Current adapter targets:
+
+- `adapters/codex/`
+- `adapters/claude/`
+- `adapters/cursor/`
+- generated GitHub Copilot prompt files in `.github/prompts/`
+
+Claude plugin and marketplace identifiers must be kebab-case. Keep `olko:*` names for Codex lookup names, but do not use colons or spaces in Claude marketplace/plugin names.
+
+After changing a package name, description, category, path, tags, or adapter support, update `catalog/skills.json` and rebuild generated files:
+
+```bash
+./scripts/build-adapters.sh
+./scripts/validate-catalog.sh
+```
+
+## Catalog Requirements
+
+Each package must have a matching entry in `catalog/skills.json`:
+
+```json
+{
+  "name": "skill-name",
+  "lookupName": "olko:skill-name",
+  "category": "software-development",
+  "path": "packages/software-development/skill-name",
+  "description": "Short catalog description.",
+  "tags": ["tag"],
+  "adapters": ["codex", "claude", "cursor", "copilot"]
+}
+```
+
+Rules:
+
+- `lookupName` uses the `olko:` prefix.
+- `path` points at the canonical package directory, not an adapter.
+- `description` should be shorter than the full frontmatter description.
+- `adapters` must reflect generated or supported adapter targets.
+
+## Writing Principles
+
+1. Process over knowledge. Skills are workflows, not essays.
+2. Specific over general. Name commands, paths, files, and evidence.
+3. Evidence over assumption. Verification should require proof.
+4. Canonical package first. Update `SKILL.md` before generated adapters.
+5. Progressive disclosure. Move long detail into `references/` only when needed.
+6. Minimal scope. Add only the sections that change agent behavior.
+
+## Cross-Skill References
+
+Reference other skills by lookup name or package path instead of duplicating content:
+
+```markdown
+Use `olko:git-commit` when the user asks to commit the resulting changes.
+See `packages/software-development/semantic-release-beta/SKILL.md` for beta release setup.
+```
+
+Do not copy another skill's workflow into a new package unless the behavior intentionally diverges.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olegkoval/agent-skills",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -21,6 +21,7 @@
   "files": [
     "catalog",
     "collections",
+    "docs",
     "packages",
     ".claude-plugin",
     ".cursor-plugin",

package/packages/marketing/viral-launch/adapters/claude/plugin.json

@@ -1,10 +1,5 @@
 {
-  "name": "olko:viral-launch",
+  "name": "olko-viral-launch",
   "description": "Set up a project repository and launch plan for shareable marketing, public launch readiness, and growth loops.",
-  "skills": [
-    {
-      "name": "olko:viral-launch",
-      "source": "../../SKILL.md"
-    }
-  ]
+  "skills": "./skills"
 }

package/packages/marketing/viral-launch/adapters/claude/skills/viral-launch/SKILL.md

@@ -0,0 +1,103 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+
+name: viral-launch
+description: Set up a project repository and launch plan for shareable marketing, public launch readiness, and growth loops without pretending virality is guaranteed.
+compatibility: Codex, Claude Code, Cursor, GitHub Copilot, and other Agent Skills compatible tools. Useful for product repos, open-source packages, SaaS launches, waitlists, and creator tools.
+metadata:
+  author: Oleg Koval
+  tags:
+    - marketing
+    - launch
+    - growth
+    - virality
+    - positioning
+    - github
+
+---
+
+# viral-launch
+
+Use this skill when a user wants to launch a project, make a repo marketable, improve discoverability, or build shareable launch assets.
+
+This skill is opinionated: virality is not a promise. The goal is to make the project easy to understand, easy to share, and easy to act on.
+
+## Trigger phrases
+
+- make this repo launch-ready
+- set this up to go viral
+- prepare a product launch
+- create marketing assets for this project
+- improve the README for launch
+- prepare Product Hunt / Hacker News / X / LinkedIn launch copy
+- set up an open-source repo for growth
+
+## Workflow
+
+1. Inspect the project first:
+  - product purpose
+  - target user
+  - core use case
+  - current README and docs
+  - install or demo path
+  - screenshots, videos, or visual proof
+  - analytics or waitlist capture if present
+2. Define the launch angle in one sentence:
+  - who it is for
+  - what painful job it solves
+  - why now
+  - what makes it different
+3. Make the repo launch-ready:
+  - clear README headline and first paragraph
+  - demo or quickstart within the first screen
+  - installation steps that work from a clean checkout
+  - screenshots, GIF, or demo link where possible
+  - feature list based on outcomes, not implementation trivia
+  - examples for the highest-intent use cases
+  - badges only when they add trust
+  - license, contributing notes, and issue templates when useful
+4. Create launch assets:
+  - short tagline
+  - 1-paragraph announcement
+  - 5 social post variants
+  - Product Hunt tagline and description when relevant
+  - Hacker News title candidates when relevant
+  - launch email or DM when relevant
+  - creator/influencer outreach list criteria, not spam copy
+5. Design share loops:
+  - a reason users would show the output to someone else
+  - a public artifact worth linking
+  - a before/after demo
+  - a template, benchmark, checklist, or gallery that can travel
+  - referral or waitlist loop only if it fits the product
+6. Define proof and metrics:
+  - activation event
+  - share event
+  - conversion event
+  - retention proxy
+  - launch-day dashboard or simple tracking checklist
+7. Keep claims grounded:
+  - do not invent traction, logos, benchmarks, testimonials, or user counts
+  - mark assumptions explicitly
+  - prefer specific proof over hype
+  - avoid dark patterns and spam
+
+## Output format
+
+When planning, produce:
+
+- Launch angle
+- Repo changes
+- Launch assets
+- Share loops
+- Metrics
+- Risks and assumptions
+- Next actions
+
+When editing a repository, make the smallest useful set of changes first, then validate by reading the README from a new user's perspective.
+
+## References
+
+- `references/launch-checklist.md`
+- `references/external-skills.md`

package/packages/music/fill-music-player/adapters/claude/plugin.json

@@ -1,10 +1,5 @@
 {
-  "name": "olko:fill-music-player",
-  "description": "Fill a portable music player with a curated random selection from a source music library.",
-  "skills": [
-    {
-      "name": "olko:fill-music-player",
-      "source": "../../SKILL.md"
-    }
-  ]
+  "name": "olko-fill-music-player",
+  "description": "Fill a portable music player with a curated random selection from a source music library while balancing formats, artists, albums, and capacity.",
+  "skills": "./skills"
 }