agent-skills: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build Commands

• Build all packages: pnpm build
• Build specific package: cd packages/<name> && pnpm build
• Dev mode (watch): pnpm dev or cd packages/<name> && pnpm dev
• Type check: pnpm typecheck
• Lint: pnpm lint
• Test: pnpm test
• Clean: pnpm clean

Project Structure

This is a pnpm monorepo containing Claude Code extensions:

claude-skills/
├── packages/          # MCP servers (TypeScript, builds to dist/)
│   ├── mcp-github-issues/
│   └── mcp-debug-cycle/
├── skills/           # Agent Skills (SKILL.md format)
│   └── code-review/
└── hooks/            # Claude Code hooks (Node.js scripts)
    ├── cost-monitor/
    ├── notify-complete/
    └── tdd-enforcement/

Architecture

MCP Servers (packages/)

TypeScript packages following MCP SDK patterns:

• Entry: src/index.ts exports Server from @modelcontextprotocol/sdk/server/index.js
• Tools: src/tools/*.ts export Tool definitions and implementation functions
• Utils: src/utils/*.ts for shared logic (e.g., gh-cli.ts wraps GitHub CLI)
• Build: TypeScript compiles src/ → dist/, using tsconfig.base.json + package-level tsconfig.json
• Execution: dist/index.js is the MCP server entry point (runs via node)

Tool implementations follow this pattern:

export const toolName: Tool = {
  name: "mcp_tool_name",
  description: "...",
  inputSchema: { /* Zod or JSON Schema */ }
}

export async function toolName(args: ArgsType): Promise<ToolResponse> {
  // Implementation
}

Agent Skills (skills/)

Agent Skills Specification (agentskills.io) compliant format:

• Structure: Each skill is a directory with SKILL.md as the manifest
• Frontmatter: YAML with required fields name (lowercase-hyphen only) and description
• Content: Markdown body with skill instructions, using XML-style tags for structure:
  • <essential_principles> - Core philosophy and rules
  • <intake> - User-facing prompt for skill invocation
  • <routing> - Pattern matching to workflow files
  • <reference_index> - Links to reference docs
  • <workflows_index> - Available workflow files
• Supporting files:
  • references/ - On-demand docs (e.g., checklists, common issues)
  • workflows/ - Step-by-step procedures (e.g., review-diff.md)
  • scripts/ - Executable code (if needed)
  • assets/ - Templates, data files