@olegkoval/agent-skills 1.0.0-beta.1

package/.claude-plugin/marketplace.json

@@ -0,0 +1,58 @@
+{
+  "name": "agent skills",
+  "owner": {
+    "name": "Oleg Koval"
+  },
+  "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."
+    }
+  ]
+}

package/.cursor-plugin/index.json

@@ -0,0 +1,55 @@
+{
+  "name": "agent skills",
+  "plugins": [
+    {
+      "name": "olko:docs-index-keeper",
+      "source": "./packages/software-development/docs-index-keeper/adapters/cursor",
+      "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/cursor",
+      "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/cursor",
+      "description": "Generate user-facing changelogs and release notes from git history."
+    },
+    {
+      "name": "olko:gh-cli",
+      "source": "./packages/software-development/gh-cli/adapters/cursor",
+      "description": "Use the GitHub CLI effectively for repositories, PRs, Actions, releases, and more."
+    },
+    {
+      "name": "olko:git-commit",
+      "source": "./packages/software-development/git-commit/adapters/cursor",
+      "description": "Create conventional commits with diff-aware staging and message generation."
+    },
+    {
+      "name": "olko:gallery",
+      "source": "./packages/photography/gallery/adapters/cursor",
+      "description": "Create photo galleries with AI-assisted layout curation and sequencing."
+    },
+    {
+      "name": "olko:promptctl",
+      "source": "./packages/software-development/promptctl/adapters/cursor",
+      "description": "Use promptctl for template-based prompt engineering, scoring, and workflow automation."
+    },
+    {
+      "name": "olko:fill-music-player",
+      "source": "./packages/music/fill-music-player/adapters/cursor",
+      "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/cursor",
+      "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/cursor",
+      "description": "Set up a project repository and launch plan for shareable marketing, public launch readiness, and growth loops."
+    }
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleg Koval
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,181 @@
+<div align="center">
+  <h1>agent skills</h1>
+  <p><strong>Agent-agnostic skill catalog for Codex, Claude, Cursor, and other skill-aware tools.</strong></p>
+  <p>
+    <img src="https://img.shields.io/badge/license-MIT-16a34a" alt="MIT license">
+    <img src="https://img.shields.io/badge/skills-10-2563eb" alt="10 skills">
+    <img src="https://img.shields.io/badge/platforms-Codex%20%7C%20Claude%20%7C%20Cursor%20%7C%20Copilot-111827" alt="Codex Claude Cursor Copilot">
+    <img src="https://img.shields.io/badge/status-public%20catalog-16a34a" alt="Public catalog">
+  </p>
+</div>
+
+Agent-agnostic skill collection for Codex, Claude, Cursor, and other skill-aware tools.
+
+These skills are opinionated by design. They encode working defaults, preferred tools, and repeatable workflows instead of trying to be neutral snippets. Treat them as starting points with taste: useful out of the box, easy to inspect, and specific enough for an agent to execute consistently.
+
+## Structure
+
+- `packages/` — canonical skill packages organized by category
+- `catalog/` — machine-readable inventory
+- `collections/` — grouped package bundles
+- `scripts/` — sync and validation helpers
+
+## Principles
+
+- Keep one canonical skill package per workflow.
+- Put agent-specific wrappers in `adapters/` instead of duplicating the core skill.
+- Keep catalogs neutral and machine-readable.
+- Add marketplace-specific metadata on top of the canonical package, not instead of it.
+
+## 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`
+
+## How to use skills
+
+Install the Codex symlinks, then mention a skill by its lookup name in a new agent session:
+
+```bash
+./scripts/install-codex-symlinks.sh
+```
+
+```text
+Use the olko:semantic-release-beta skill to add prereleases on a beta branch.
+```
+
+```text
+Use the olko:gallery skill to build a photo gallery from this image folder.
+```
+
+```text
+Use the olko:viral-launch skill to make this project launch-ready.
+```
+
+Each package has a canonical `SKILL.md` under `packages/{category}/{skill}/`. Agent-specific wrappers live under that package's `adapters/` directory.
+
+When adding or changing a skill:
+
+1. Update the canonical `SKILL.md` first.
+2. Keep instructions concrete and operational.
+3. Add references only when the agent needs extra detail to execute the workflow.
+4. Update `catalog/skills.json` if the skill name, category, description, path, tags, or adapters change.
+5. Run local validation before publishing changes.
+
+## Root manifests
+
+- Claude marketplace manifest: `.claude-plugin/marketplace.json`
+- Cursor plugin index: `.cursor-plugin/index.json`
+- Copilot repository instructions: `.github/copilot-instructions.md`
+- Copilot prompt files: `.github/prompts/*.prompt.md`
+
+These are generated from the neutral package inventory and kept in the repo for platform-specific consumption.
+
+## Install and test
+
+### Codex
+
+Install all canonical packages into your local Codex skills directory:
+
+```bash
+./scripts/install-codex-symlinks.sh
+```
+
+This creates symlinks from the package catalog into `${CODEX_HOME:-~/.codex}/skills` using the lookup format `olko:{skill_name}`.
+
+To test a skill in a fresh Codex session, mention it explicitly:
+
+```text
+Use the olko:docs-index-keeper skill to set up docs index automation in this repo.
+```
+
+```text
+Use the olko:semantic-release-beta skill to add prereleases on a beta branch.
+```
+
+### Claude
+
+The repository includes a generated root manifest at `.claude-plugin/marketplace.json` and per-package Claude adapter stubs under `packages/*/*/adapters/claude/`.
+
+Current status:
+
+- suitable for local packaging and iteration
+- not yet validated against a live Claude marketplace install flow
+
+### Cursor
+
+The repository includes a generated root plugin index at `.cursor-plugin/index.json` and per-package Cursor adapter stubs under `packages/*/*/adapters/cursor/`.
+
+Current status:
+
+- suitable for local packaging and iteration
+- not yet validated against a live Cursor plugin install flow
+
+### GitHub Copilot
+
+The repository includes generated Copilot repository instructions at `.github/copilot-instructions.md` and one reusable prompt file per skill under `.github/prompts/`.
+
+Current status:
+
+- suitable for repository-level Copilot customization
+- generated from the canonical package catalog
+- not yet validated against GitHub Copilot in a live GitHub workspace
+
+### Source sync
+
+`./scripts/sync-from-sources.sh` syncs package content only for catalog entries that explicitly define `sourcePath`. If no package has `sourcePath`, the script exits successfully and reports that there is nothing to sync.
+
+## Local validation
+
+Rebuild generated manifests:
+
+```bash
+./scripts/build-adapters.sh
+```
+
+Validate the neutral catalog and generated root manifests:
+
+```bash
+./scripts/validate-catalog.sh
+```
+
+## Smoke-tested workflows
+
+The following package workflows have been smoke-tested locally before first push:
+
+- `docs-index-keeper`
+  - installed from npm in a temporary git repo
+  - initialized hook generation with `npx docs-index-keeper init`
+  - updated `docs/README.md` from a staged Markdown file
+  - passed `docs-index-keeper check`
+- `semantic-release-beta`
+  - configured a temporary git repo with `main` and `beta` branches
+  - used `semantic-release-npm-github-publish` as the release preset
+  - ran `semantic-release --dry-run --no-ci` on `beta`
+  - verified prerelease calculation to `1.0.0-beta.1`
+
+The semantic-release smoke test was intentionally self-contained and used a local bare git remote plus a valid `file://` repository URL so dry-run behavior could be validated without real npm or GitHub publishing credentials.
+
+## Licensing notes
+
+- `fill-music-player` includes an MIT license and is safe to carry as-is in this repository.
+- `product-builder` now has an MIT license file added in the source repo clone and in this catalog package, matching the existing MIT claim in its README.

package/catalog/skills.json

@@ -0,0 +1,202 @@
+{
+  "name": "agent skills",
+  "packages": [
+    {
+      "name": "docs-index-keeper",
+      "lookupName": "olko:docs-index-keeper",
+      "category": "software-development",
+      "path": "packages/software-development/docs-index-keeper",
+      "description": "Keep a Markdown docs index in sync through pre-commit, CI, or one-off maintenance flows.",
+      "tags": [
+        "docs",
+        "markdown",
+        "index",
+        "ci",
+        "pre-commit"
+      ],
+      "adapters": [
+        "codex",
+        "claude",
+        "cursor",
+        "copilot"
+      ]
+    },
+    {
+      "name": "semantic-release-beta",
+      "lookupName": "olko:semantic-release-beta",
+      "category": "software-development",
+      "path": "packages/software-development/semantic-release-beta",
+      "description": "Set up semantic-release-npm-github-publish with stable main releases and prerelease beta releases on a beta branch.",
+      "tags": [
+        "semantic-release",
+        "semantic-release-npm-github-publish",
+        "release",
+        "beta",
+        "github-actions",
+        "npm"
+      ],
+      "adapters": [
+        "codex",
+        "claude",
+        "cursor",
+        "copilot"
+      ]
+    },
+    {
+      "name": "changelog-generator",
+      "lookupName": "olko:changelog-generator",
+      "category": "software-development",
+      "path": "packages/software-development/changelog-generator",
+      "description": "Generate user-facing changelogs and release notes from git history.",
+      "tags": [
+        "changelog",
+        "release-notes",
+        "git",
+        "docs"
+      ],
+      "adapters": [
+        "codex",
+        "claude",
+        "cursor",
+        "copilot"
+      ]
+    },
+    {
+      "name": "gh-cli",
+      "lookupName": "olko:gh-cli",
+      "category": "software-development",
+      "path": "packages/software-development/gh-cli",
+      "description": "Use the GitHub CLI effectively for repositories, PRs, Actions, releases, and more.",
+      "tags": [
+        "github",
+        "gh",
+        "cli",
+        "pull-requests",
+        "actions"
+      ],
+      "adapters": [
+        "codex",
+        "claude",
+        "cursor",
+        "copilot"
+      ]
+    },
+    {
+      "name": "git-commit",
+      "lookupName": "olko:git-commit",
+      "category": "software-development",
+      "path": "packages/software-development/git-commit",
+      "description": "Create conventional commits with diff-aware staging and message generation.",
+      "tags": [
+        "git",
+        "commit",
+        "conventional-commits"
+      ],
+      "adapters": [
+        "codex",
+        "claude",
+        "cursor",
+        "copilot"
+      ]
+    },
+    {
+      "name": "gallery",
+      "lookupName": "olko:gallery",
+      "category": "photography",
+      "path": "packages/photography/gallery",
+      "description": "Create photo galleries with AI-assisted layout curation and sequencing.",
+      "tags": [
+        "photos",
+        "gallery",
+        "layout",
+        "curation"
+      ],
+      "adapters": [
+        "codex",
+        "claude",
+        "cursor",
+        "copilot"
+      ]
+    },
+    {
+      "name": "promptctl",
+      "lookupName": "olko:promptctl",
+      "category": "software-development",
+      "path": "packages/software-development/promptctl",
+      "description": "Use promptctl for template-based prompt engineering, scoring, and workflow automation.",
+      "tags": [
+        "prompts",
+        "prompt-engineering",
+        "cli",
+        "templates"
+      ],
+      "adapters": [
+        "codex",
+        "claude",
+        "cursor",
+        "copilot"
+      ]
+    },
+    {
+      "name": "fill-music-player",
+      "lookupName": "olko:fill-music-player",
+      "category": "music",
+      "path": "packages/music/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.",
+      "tags": [
+        "music",
+        "media",
+        "copy",
+        "curation",
+        "cli"
+      ],
+      "adapters": [
+        "codex",
+        "claude",
+        "cursor",
+        "copilot"
+      ]
+    },
+    {
+      "name": "product-builder",
+      "lookupName": "olko:product-builder",
+      "category": "software-development",
+      "path": "packages/software-development/product-builder",
+      "description": "Build a full-stack web application or SaaS product from a user description using production-oriented defaults.",
+      "tags": [
+        "product",
+        "full-stack",
+        "saas",
+        "web-app",
+        "builder"
+      ],
+      "adapters": [
+        "codex",
+        "claude",
+        "cursor",
+        "copilot"
+      ]
+    },
+    {
+      "name": "viral-launch",
+      "lookupName": "olko:viral-launch",
+      "category": "marketing",
+      "path": "packages/marketing/viral-launch",
+      "description": "Set up a project repository and launch plan for shareable marketing, public launch readiness, and growth loops.",
+      "tags": [
+        "marketing",
+        "launch",
+        "growth",
+        "virality",
+        "positioning",
+        "github"
+      ],
+      "adapters": [
+        "codex",
+        "claude",
+        "cursor",
+        "copilot"
+      ]
+    }
+  ]
+}

package/collections/creative-tools.json

@@ -0,0 +1,5 @@
+{
+  "name": "creative-tools",
+  "description": "Skills for creative media curation and presentation workflows.",
+  "packages": ["gallery", "fill-music-player"]
+}

package/collections/docs-tools.json

@@ -0,0 +1,5 @@
+{
+  "name": "docs-tools",
+  "description": "Skills for documentation maintenance and docs automation.",
+  "packages": ["docs-index-keeper", "changelog-generator"]
+}

package/collections/git-tools.json

@@ -0,0 +1,5 @@
+{
+  "name": "git-tools",
+  "description": "Skills for git workflows, commits, GitHub CLI usage, and related automation.",
+  "packages": ["gh-cli", "git-commit", "changelog-generator"]
+}

package/collections/marketing.json

@@ -0,0 +1,5 @@
+{
+  "name": "marketing",
+  "description": "Skills for project marketing, public launches, positioning, and shareable growth workflows.",
+  "packages": ["viral-launch"]
+}

package/collections/music.json

@@ -0,0 +1,5 @@
+{
+  "name": "music",
+  "description": "Skills for music library curation and portable music player workflows.",
+  "packages": ["fill-music-player"]
+}

package/collections/photography.json

@@ -0,0 +1,5 @@
+{
+  "name": "photography",
+  "description": "Skills for photography curation and gallery presentation workflows.",
+  "packages": ["gallery"]
+}

package/collections/product-tools.json

@@ -0,0 +1,5 @@
+{
+  "name": "product-tools",
+  "description": "Skills for building, shaping, and shipping full-stack products and SaaS applications.",
+  "packages": ["product-builder"]
+}

package/collections/prompt-tools.json

@@ -0,0 +1,5 @@
+{
+  "name": "prompt-tools",
+  "description": "Skills for prompt engineering, prompt quality, and prompt workflow automation.",
+  "packages": ["promptctl"]
+}

package/collections/release-tools.json

@@ -0,0 +1,5 @@
+{
+  "name": "release-tools",
+  "description": "Skills for release automation, versioning, and prerelease workflows.",
+  "packages": ["semantic-release-beta"]
+}

package/collections/software-development.json

@@ -0,0 +1,13 @@
+{
+  "name": "software-development",
+  "description": "Skills for software development, release automation, git workflows, documentation, prompt tooling, and product building.",
+  "packages": [
+    "docs-index-keeper",
+    "semantic-release-beta",
+    "changelog-generator",
+    "gh-cli",
+    "git-commit",
+    "promptctl",
+    "product-builder"
+  ]
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@olegkoval/agent-skills",
+  "version": "1.0.0-beta.1",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Agent-agnostic skill catalog for Codex, Claude, Cursor, and other skill-aware tools.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oleg-koval/agent-skills.git"
+  },
+  "bugs": {
+    "url": "https://github.com/oleg-koval/agent-skills/issues"
+  },
+  "homepage": "https://github.com/oleg-koval/agent-skills#readme",
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "catalog",
+    "collections",
+    "packages",
+    ".claude-plugin",
+    ".cursor-plugin",
+    "scripts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "sh ./scripts/build-adapters.sh",
+    "test": "sh ./scripts/validate-catalog.sh",
+    "semantic-release": "semantic-release",
+    "release:dry-run": "semantic-release --dry-run --no-ci --verify-conditions=@semantic-release/changelog --verify-conditions=@semantic-release/git --verify-conditions=@semantic-release/github"
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.6",
+    "@semantic-release/npm": "^13.1.5",
+    "@semantic-release/release-notes-generator": "^14.1.0",
+    "semantic-release": "^25.0.3",
+    "semantic-release-npm-github-publish": "^1.7.3"
+  }
+}