mallard-release

name	mallard-release
description	Workflow for adding skills/commands to mallard and shipping a new release. Use when the user asks how to release mallard, ship a new mallard version, add a skill or command to mallard, bump a mallard version, "publicar mallard", "subir mallard", "nueva versión de mallard", or anything involving editing this repo and getting the change to the team's machines.
version	0.1.0
metadata	{"author":"Eduardo Calvo"}

mallard release workflow

Reference for adding/updating skills, commands, and shipping releases for mallard. The tool lives at /Users/eduardocalvolopez/Developer/Personal/mallard (on Eduardo's machine).

When to use this skill

• "How do I add a skill to mallard?"
• "Release a new version of mallard" / "ship mallard" / "tag mallard vX.Y.Z"
• "Update mallard" / "bump the mallard version"
• Anything that involves editing files under skills/, claude/commands/, claude/agents/, or shipping the change to other team members.

TL;DR

# 1. Edit the skill/command file
# 2. Bump its `version:` in frontmatter (semver, conservative)
# 3. Test locally
go build -o mallard .
./mallard update                    # re-link with backup
./mallard registry                  # confirm new version + ok status

# 4. Commit using Conventional Commits, in English
git add skills/<name>/ claude/commands/<name>.md
git commit -m "feat(skills): add <name>"   # or fix:, refactor:, docs:, chore:

# 5. Push
git push

# 6. Tag a release (this is what propagates to the team)
git tag vX.Y.Z
git push origin vX.Y.Z

# GitHub Actions runs goreleaser → publishes binaries + auto-changelog

Team members pick it up with:

curl -fsSL https://raw.githubusercontent.com/educlopez/mallard/main/install.sh | bash
mallard update

Adding a new skill

1. Create skills/<skill-name>/SKILL.md with frontmatter:

   ---
   name: <skill-name>
   description: >
     When to trigger this skill. Be specific — Claude uses this to decide
     whether to invoke. Include keywords the user might say, project types,
     and contexts.
   version: "0.1.0"
   ---
   

2. Write the skill body in markdown. Sections, code blocks, tables — whatever helps Claude execute the skill. Reference existing skills in this repo for style.
3. Locally: go build -o mallard . && ./mallard update — the symlink will appear in ~/.claude/skills/<skill-name>/.
4. Validate: ./mallard doctor (managed count goes up) and ./mallard registry (entry shows v0.1.0 ok).
5. Skip to Shipping a release below.

Adding a new command

1. Create claude/commands/<command-name>.md with frontmatter:

   ---
   name: <command-name>
   description: One-line summary of what the command does.
   version: "0.1.0"
   ---
   

2. Body: instructions for the slash command. Available in Claude Code as /<command-name> after install.
3. Locally: ./mallard update.
4. Skip to Shipping a release below.

Adding a new agent

Agents are Claude Code subagents. They symlink to ~/.claude/agents/ and are Claude-only (codex/opencode/generic adapters return an empty agents dir and skip them).

1. Create claude/agents/<agent-name>.md with frontmatter:

   ---
   name: <agent-name>
   description: When Claude should route to this agent.
   tools: Read, Grep, Glob, Bash
   model: sonnet
   color: orange
   version: "0.1.0"
   ---
   

2. Body: the agent's system prompt. Optionally add a /<name> command in claude/commands/ to invoke it explicitly.
3. Locally: ./mallard update — the symlink appears in ~/.claude/agents/<agent-name>.md.
4. Skip to Shipping a release below.

Bumping an existing skill, command, or agent

1. Edit the file.
2. Bump version: in the frontmatter. Semver guidance:
   • Patch (0.1.0 → 0.1.1): typo fixes, doc clarifications, no behavior change.
   • Minor (0.1.0 → 0.2.0): new functionality inside the skill, backward-compatible.
   • Major (0.1.0 → 1.0.0): breaking change in expected user-facing behavior (rare for a skill).
3. Locally: ./mallard update && ./mallard registry — confirm new version shows ok, old drift if you also have an older symlink elsewhere.

Shipping a release

git add <files>
git commit -m "feat(skills): add <name>"
# Conventional Commit prefixes: feat, fix, refactor, docs, chore, ci, test
git push
git tag vX.Y.Z
git push origin vX.Y.Z

Version the mallard release, not the skill: skills carry their own versions inside frontmatter, the tag versions the binary + the set of skills shipped together.

GitHub Actions (.github/workflows/release.yml) runs goreleaser, which:

• Builds for darwin/linux/windows × amd64/arm64
• Uploads tarballs + checksums to the GitHub release
• Writes a release changelog grouped by Features / Bug Fixes / Refactor / Others (filters out docs:, test:, ci:, chore:)

If the changelog auto-text needs richer notes (highlights, breaking changes, etc.), edit the release after publish:

gh release edit vX.Y.Z --notes "$(cat <<'EOF'
## Highlights
- ...

## Skills
- new: ...
- updated: ...
EOF
)"

Team upgrade path

curl -fsSL https://raw.githubusercontent.com/educlopez/mallard/main/install.sh | bash
mallard update     # re-symlinks skills + commands, backs up any conflicts
mallard doctor     # verify
mallard registry   # see what's installed per agent + versions

Windows: download the latest zip from https://github.com/educlopez/mallard/releases and replace mallard.exe on the PATH.

Gotchas

• NEVER skip the version: field on skill/command frontmatter. Without it, mallard registry reports unversioned.
• Conventional Commits are mandatory — they drive the changelog grouping. chore: commits get filtered out of release notes.
• mallard update makes backups before replacing files. If you blow something away, mallard update --list-backups and --restore <ts> will recover it.
• The first run on a new agent dir (Claude / Codex / OpenCode / generic) appears as missing → installed for every entry. That's expected, not drift.
• Skills only ship via tags. Pushing to main without tagging publishes nothing — GH Actions release workflow only fires on v* tags.

Useful commands

Command	What
./mallard	Interactive TUI (Install / Update / Doctor / Registry / Quit)
./mallard update --dry-run	Show what update would change without touching disk
./mallard update --restore <ts>	Recover from a backup batch
./mallard registry --source	List what the repo ships (without scanning installed)
./mallard registry --all	Include foreign / unmanaged entries from other tooling
./mallard version	Print version (release tag injected at build time)