beagle

Portability and contributing

Validation checks, contributor workflow, and release process for Beagle's Markdown skill marketplace.

Repository shape

Beagle is a Markdown marketplace. It has no npm package, Python package, compiled binary, database, or test suite. The source of truth is the skill tree:

plugins/<plugin-name>/skills/<skill-name>/SKILL.md

plugins/<plugin-name>/skills/<skill-name>/references/*.md

The active marketplace is listed in .claude-plugin/marketplace.json. Deprecated beagle-ai files remain on disk but are not part of the active marketplace catalog.

Portability scan

The main validation script is scripts/check-portability.sh:

./scripts/check-portability.sh

It scans Markdown under plugins/*/skills and fails on harness-specific content, including:

  • Claude slash invocations such as /beagle-core:...;
  • plugin namespace tokens embedded in skill bodies;
  • named harness tools such as Task tool, Skill tool, Edit tool, or Bash tool;
  • literal Claude Code references inside portable skill content;
  • non-spec frontmatter keys such as autoContext, dependencies, or triggers.

A clean run prints:

PORTABILITY OK

Frontmatter validation

Contributor docs also require frontmatter parsing for every active skill:

python3 - <<'PY'

from pathlib import Path

import yaml



for path in Path('plugins').glob('*/skills/*/SKILL.md'):

    text = path.read_text()

    if not text.startswith('---'):

        raise SystemExit(f'missing frontmatter: {path}')

    end = text.find('\n---', 3)

    if end == -1:

        raise SystemExit(f'unclosed frontmatter: {path}')

    yaml.safe_load(text[3:end])



print('frontmatter ok')

PY

The portability scan checks whether the skill content can move across agent harnesses. The frontmatter check catches malformed SKILL.md envelopes before the files are loaded by an agent.

Contributor workflow

When adding or editing a skill:

  1. Put the skill under the plugin that matches its domain.
  2. Keep the main SKILL.md short enough for an agent to load directly. Move long references into references/.
  3. Use portable Agent Skills frontmatter and avoid harness-specific commands in skill bodies.
  4. Use the standard review format [FILE:LINE] ISSUE_TITLE for code-review skills.
  5. Run the portability scan and frontmatter parser.
  6. Update SKILLS.md, .claude-plugin/marketplace.json, and plugin README content when the public catalog changes.

The repo's AGENTS.md and CONTRIBUTING.md are the operational references for contributor details.

Release process

The release process is manual and semver-based:

  1. Update CHANGELOG.md.
  2. Bump metadata.version in .claude-plugin/marketplace.json.
  3. Commit with a conventional release message.
  4. Push to main.
  5. Create and push an annotated tag:
git tag -a vX.Y.Z -m "Release vX.Y.Z"

git push origin vX.Y.Z
  1. Create the GitHub release:
gh release create vX.Y.Z --title "vX.Y.Z" --notes "..."

Patch releases cover bug fixes and documentation updates. Minor releases add skills or features. Major releases contain breaking skill changes.

Source files