Liatrio skills

A multi-skill repository — each subdirectory under skills/ is a self-contained Claude skill. The layout follows Anthropic's skill-repo convention (one repo, many skills), but distribution and discovery go entirely through the Liatrio skills platform: every skill is published as an OCI artifact to GHCR, and browseable at https://skills.liatr.io/. Claude Code's plugin marketplace is intentionally not used here.

Layout

.
├── .github/workflows/
│   ├── release.yml                   # Per-skill semantic-release on push to main
│   ├── publish.yml                   # Tag-triggered publish to GHCR via reusable workflow
│   ├── pr-smoke.yml                  # Static-per-skill smoke jobs, on every PR
│   └── templates/                    # Parameterized scaffolds (not auto-executed)
│       ├── release.yml               #   ↑ skill-publish-github copies these
│       ├── publish.yml               #   ↑ into consumer repos with substitutions
│       ├── pr-smoke.yml              #   ↑ for {{SKILL_NAME}} and {{PLATFORM_TAG}}
│       ├── .releaserc.cjs            #
│       └── README.md                 # Placeholder reference + dogfood notes
├── .releaserc.cjs                    # Shared semantic-release config (driven by $SKILL)
├── skills/                           # Skill content (one subdirectory per skill)
│   └── <skill-name>/
│       ├── SKILL.md                  # Frontmatter + body (required); metadata.version is auto-bumped
│       ├── references/               # Optional: long-form docs Claude can pull on demand
│       └── scripts/                  # Optional: helper scripts the skill invokes
├── template/SKILL.md                 # Starter for new skills (copy + rename)
└── README.md

Each skills/<name>/SKILL.md follows the agentskills.io spec. The spec places version under metadata.version; the release workflow maintains it automatically based on the conventional-commit history scoped to that skill. See Adding a new skill.

The files in .github/workflows/*.yml are the dogfood form of the templates under .github/workflows/templates/ — this repo publishes its own skill-publish-github using the same scaffolds it asks other repos to adopt. When you update one side, mirror the change to the other. See .github/workflows/templates/README.md.

Skills

Name	Description
none yet	Copy template/ to skills/<your-skill>/ and follow the steps below.

Adding a new skill

1. Copy the template:

   cp -R template skills/my-new-skill

2. Edit skills/my-new-skill/SKILL.md. Required frontmatter:

   ---
   name: my-new-skill          # Must match the directory name, kebab-case lowercase.
   description: One-line description Claude uses to decide when to load this skill. ≤ 1024 chars.
   metadata:
     version: "0.1.0"          # Maintained by release.yml — bumped automatically from commit history.
   ---

3. (Optional) Add references/ for long-form docs Claude can pull on demand, and scripts/ for helper scripts.
4. Open a PR. The pr-smoke.yml matrix runs a dry-run publish for every skill changed in the PR — broken frontmatter, missing fields, or contract violations fail the PR.
5. Once merged, release.yml cuts the next tag for any skill whose scoped commits warrant a release (see Releasing).

Releasing

Releases are fully automated and per-skill. There is no manual tag step; merging to main is the release trigger.

Author workflow

Write Conventional Commits scoped to the skill you are changing:

feat(skill-publish-github): add support for monorepo onboarding
fix(skill-publish-github): tolerate trailing whitespace in frontmatter
feat(skill-publish-github)!: rename `onboard` command to `publish`   # major bump

The scope (skill-publish-github above) selects which skill's history the release engine analyses. Unscoped commits, or commits scoped to non-skill paths (docs:, chore:, feat(template):, etc.) do not trigger any release.

What happens on merge to main

release.yml runs semantic-release once per skill, in matrix:

1. Discovers every skills/<name>/SKILL.md.
2. For each skill, reads commits since its last <skill>-v* tag, filtered to commits that touched files under skills/<skill>/ (via semantic-release-monorepo).
3. If those commits warrant a release (feat: → minor, fix: → patch, feat!: or BREAKING CHANGE → major), semantic-release:
   • Stamps the new semver into skills/<skill>/SKILL.md under metadata.version.
   • Commits the updated SKILL.md back to main with [skip ci] (so this workflow does not re-trigger itself).
   • Creates the tag <skill>-v<semver> (e.g. skill-publish-github-v0.2.0) and a GitHub release with notes.

The tag push then fires publish.yml, which:

1. Parses <skill> and <version> from the tag.
2. Verifies the tagged commit's metadata.version matches.
3. Invokes liatrio/skills-platform/.github/workflows/publish-skill.yml with skill-name, version, and skill-path: skills/<skill>.
4. The reusable workflow pushes ghcr.io/liatrio/skills/<skill-name>:<version> to GHCR with a SLSA build-provenance attestation.

First release of a new skill

When a skill has no <skill>-v* tag yet, semantic-release defaults the first release to 1.0.0. If you want to preserve the metadata.version you seeded in the SKILL.md (e.g. 0.1.0), pre-tag the current main once before merging the first feature commit:

git tag skill-publish-github-v0.1.0 origin/main
git push origin skill-publish-github-v0.1.0

After that, every release is derived automatically from commit history.

Installing a skill

Skills are distributed as OCI artifacts. Pull one directly from GHCR:

# Inspect what's available
skills-discover inspect ghcr.io/liatrio/skills/<skill-name>

# (Installation CLI / consumer-side tooling: see liatrio/skills-platform.)

Browsing on the catalog

Published skills are listed at https://skills.liatr.io/. The platform's discovery walks skills/<name>/SKILL.md and emits one catalog entry per skill in this repo.

Contributing

Follow Conventional Commits and scope every skill-affecting commit to the skill name (feat(<skill-name>): ...). PR title is enforced by the platform's pr-title.yml. Releases are fully automated — no manual version stamping or tagging.

License

To be determined.