skill-module-example

Imported from xinyuehtx/skill-module-example (AGENTS.md). Install upstream with npx skills add xinyuehtx/skill-module-example. Copyright stays with the author.

AGENTS.md — skill-module-example

A validation and example repository for the npm package skillmodule — verifying CLI workflows, dependency resolution, and multi-platform installation through real-world scenarios.

Project Overview

skill-module-example is a companion repository for the skillmodule CLI tool. Its purpose is to:

• Validate correctness — Verify that skillmodule init, skillmodule install, skillmodule validate, skillmodule tree, and skillmodule publish work as expected across various scenarios
• Provide atomic skills — Curate a library of reusable SKILL.md files that serve as building blocks for AI Agent workflows
• Demonstrate usage patterns — Showcase real-world scenarios including basic usage, monorepo setups, duplicate name handling, multi-version coexistence, and cross-platform installation

Project Structure

skill-module-example/
├── AGENTS.md                       # AI Agent collaboration guide (this file)
├── skills/                         # Atomic skill definitions (@skill-module-example/*)
│   ├── brainstorming/              # Explores user intent, requirements and design before implementation
│   ├── dispatching-parallel-agents/# Dispatch independent tasks to parallel agents
│   ├── executing-plans/            # Execute written implementation plans with review checkpoints
│   ├── finishing-a-development-branch/ # Guide completion of development work (merge, PR, cleanup)
│   ├── receiving-code-review/      # Technical evaluation of code review feedback
│   ├── requesting-code-review/     # Dispatch code review to catch issues early
│   ├── subagent-driven-development/# Execute plans via fresh subagent per task with two-stage review
│   ├── systematic-debugging/       # Root cause investigation before proposing fixes
│   ├── test-driven-development/    # Red-Green-Refactor TDD cycle
│   ├── using-git-worktrees/        # Isolated git worktrees for feature work
│   ├── using-superpowers/          # Skill discovery and invocation guide
│   ├── verification-before-completion/ # Evidence before completion claims
│   ├── writing-plans/              # Comprehensive implementation plan authoring
│   └── writing-skills/             # TDD-based skill creation methodology
├── examples/                       # Usage scenario demonstrations
│   ├── basic/                      # Simplest single-skill workflow
│   ├── monorepo/                   # Monorepo with layered dependencies
│   ├── duplicate-name/             # Same skill name from different scopes
│   ├── multi-version/              # Multiple versions of the same skill
│   ├── platform-install/           # Cross-platform installation (.claude/, .cursor/, etc.)
│   └── ...
└── package.json                    # Root package metadata

Skills Directory (skills/)

The skills/ directory contains atomic skill definitions — each skill is a self-contained unit with a SKILL.md file and an optional package.json.

Skill Structure

Each skill follows this layout:

skills/<skill-name>/
├── SKILL.md          # Skill content with YAML frontmatter
└── package.json      # Package metadata (auto-generated via `skillmodule init`)

SKILL.md Format

Every SKILL.md must include YAML frontmatter with metadata:

---
name: my-skill
version: 1.0.0
description: A brief description of what this skill does
dependencies:
  other-skill: ^1.0.0
---

## Skill Content

The actual skill instructions for the AI Agent go here.

Available Skills

All skills are published under the @skill-module-example npm scope:

Dependency Graph

brainstorming ──► writing-plans ──► subagent-driven-development ──► using-git-worktrees
                                │                                ├── writing-plans (circular)
                                │                                ├── requesting-code-review
                                │                                ├── finishing-a-development-branch ──► using-git-worktrees
                                │                                └── test-driven-development
                                └── executing-plans ──► using-git-worktrees
                                                     └── finishing-a-development-branch

systematic-debugging ──► test-driven-development
                      └── verification-before-completion

writing-skills ──► test-driven-development

Guidelines for Writing Skills

• One responsibility per skill — Each skill should focus on a single, well-defined capability
• Clear instructions — Write skill content as actionable instructions an AI Agent can follow
• Declare dependencies explicitly — If a skill relies on another skill, declare it in the dependencies frontmatter
• Use kebab-case naming — Skill names and directory names use kebab-case (e.g., code-review, tdd-workflow)

Examples Directory (examples/)

The examples/ directory contains end-to-end scenario demonstrations that validate specific skillmodule features. Each example is a self-contained project.

Example Structure

Every example must include:

examples/<scenario-name>/
├── README.md              # Scenario description, steps, and expected output
├── SKILL.md               # Root skill (if applicable)
├── package.json            # Dependencies and workspace config (if applicable)
└── <sub-directories>/      # Additional skills, packages, etc.

Example Categories

Writing an Example README

Each example README.md should follow this structure:

1. Title and description — What scenario this demonstrates
2. Dependency graph — Visual representation of skill relationships (if applicable)
3. Steps — Numbered bash commands to reproduce the scenario
4. Expected output — What the resulting file structure or CLI output should look like

Validation Workflow

Use the following workflow to validate skillmodule features against this repository:

Quick Validation

# 1. Install skillmodule globally (or use npx)
npm install -g skillmodule

# 2. Navigate to an example
cd examples/basic

# 3. Initialize skill packages
skillmodule init ./my-skill

# 4. Validate skill format
skillmodule validate ./my-skill

Full Workflow Validation

# 1. Navigate to a multi-dependency example
cd examples/monorepo

# 2. Install npm dependencies
pnpm install

# 3. Initialize all skill packages
skillmodule init --all ./packages

# 4. Install and resolve skill dependencies
skillmodule install

# 5. View the dependency tree
skillmodule tree

# 6. Verify .skills/ output structure
ls -la .skills/

Adding a New Validation Scenario

1. Create a new directory under examples/<scenario-name>/
2. Add a README.md describing the scenario, steps, and expected output
3. Add the necessary SKILL.md and package.json files
4. Run through the steps manually to verify correctness
5. Commit the example with a descriptive commit message

File Conventions

Naming

Markdown Style

• Use ## and ### headings — never #
• Use YAML frontmatter for skill metadata
• Use fenced code blocks with language tags for all code snippets
• Keep lines under 120 characters where possible

Commit Messages

• Use conventional commit format: feat:, fix:, docs:, test:
• Reference the specific skill or example: feat(skills): add code-review skill
• Keep the subject line under 72 characters