Skip to content

AGENTS.md

Latest commit

 

History

History
88 lines (62 loc) · 3.84 KB

AGENTS.md

File metadata and controls

88 lines (62 loc) · 3.84 KB

Repository Guidelines

This file provides guidance to Claude Code (claude.ai/code), Codex CLI, and other AI agents when working with code in this repository.

Project Overview

cowork-plugins is a collection of plugins for Claude Cowork — a mode in the Claude desktop app that gives Claude access to files and a sandboxed shell. Plugins extend Cowork with skills (specialized capabilities) and commands (slash-command workflows).

This is a public marketplace installed via Settings > Plugins > Add marketplace using aliasunder/cowork-plugins.

Repository Structure

cowork-plugins/
  README.md                             # Project overview and install instructions
  CONTRIBUTING.md                       # Release process and CI docs
  LICENSE                               # MIT license
  .claude-plugin/marketplace.json       # Marketplace config (version, plugin list)
  .github/workflows/
    auto_release.yml                    # Tag-triggered build + GitHub release
    manual_release.yml                  # UI-triggered version bump + release
  <plugin-name>/
    .claude-plugin/plugin.json          # Required: name, version, description
    skills/<skill-name>/SKILL.md        # Skill definition files
    commands/                           # Slash command files
    assets/                             # Static files (dashboards, templates)

Current Plugins

Plugin Directory Description
Trip Planner trip-planner/ Multi-week trip planning across 15+ sessions with cross-validated research, budget tracking, printable daily cards, and phase-based workflow

Plugin Architecture

Each plugin lives in its own top-level directory. Cowork discovers plugins automatically via .claude-plugin/plugin.json.

plugin.json

Required fields:

  • name — display name
  • version — semver
  • description — short description

Skills (skills/<skill-name>/SKILL.md)

Skills are specialized capabilities loaded by Claude when a task matches the skill's description. Each skill has:

  • A descriptive header
  • Trigger conditions
  • Step-by-step workflow instructions

Commands (commands/)

Slash commands are workflow files invoked explicitly by the user.

Development Guidelines

  • Each plugin is self-contained in its own top-level directory
  • No build system or package manager — plugins are markdown/JSON files
  • Follow existing plugin structure when adding new plugins
  • Use the trip-planner/ plugin as a reference implementation
  • .claude-plugin/plugin.json is required for Cowork discovery

Releasing

All plugins share a single version. Two CI workflows handle releases:

  • /release [patch|minor|major] (.claude/commands/release.md): Bumps version across all config files, commits, tags, and pushes. The Auto Release workflow then handles the build + GitHub release.
  • Manual Release (manual_release.yml): Triggered from Actions UI. Pick patch/minor/major → bumps all version files → commits → tags → builds .skill artifacts → creates GitHub release.
  • Auto Release (auto_release.yml): Triggered by v* tag push. Validates version files match the tag → builds artifacts → creates GitHub release.

Version files (must stay in sync)

  • .claude-plugin/marketplace.json → metadata.version + each plugins[].version
  • <plugin>/.claude-plugin/plugin.json → version

See CONTRIBUTING.md for full details.

Adding a New Plugin

  1. Create a top-level directory: my-plugin/
  2. Add .claude-plugin/plugin.json with name, version, and description matching the current marketplace version
  3. Add skills under skills/<skill-name>/SKILL.md
  4. Add the plugin entry to .claude-plugin/marketplace.json
  5. Add commands under commands/ if needed
  6. Add static assets under assets/ if needed
  7. Document the plugin in the root README.md plugins table