Examples Gallery

# AGENTS.md

## Project
Modern Next.js 16 + TypeScript + Tailwind + shadcn/ui application. Server Components first, minimal client JS.

## Core Principles
- Small, focused modules and components
- Excellent error messages and logging
- Write tests for any non-trivial logic
- Prefer server actions and streaming over client state when possible
- Update this file when team conventions change

## Available Skills
- advanced-code-reviewer
- test-writer
- multi-file-refactor
- doc-generator
- git-workflow
- debug-analyzer

## Standard Workflow
1. Explore the relevant code first (targeted reads, or the context-builder skill)
2. Write a short plan in scratch.md (never skip)
3. Implement + add or update tests
4. Run the advanced-code-reviewer skill on your changes
5. Create a conventional commit + high-quality PR description

## Handoff Rules
When handing work to another agent or human:
- Include the plan you followed
- List open questions and confidence level
- Point to the exact files changed and tests added

## Forbidden Patterns
- Never use `any` in TypeScript (use unknown + type guards)
- Never mutate props or context directly
- No new dependencies without discussion

{
  "schema": "gitcosmo-skill/v1",
  "id": "advanced-code-reviewer",
  "name": "advanced-code-reviewer",
  "description": "Performs deep, structured code reviews...",
  "instructions": "You are an expert senior engineer... (full prompt from the skill)",
  "category": "Grok Build",
  "compatibleAgents": ["Grok Build", "Claude", "Codex"],
  "difficulty": "Intermediate"
}

You are working on a new feature.

Phase 1 — Research (use web search / fetch MCP + codebase context)
- Gather current best practices and similar implementations in the repo.
- Produce research.md with sources and key decisions.

Phase 2 — Plan
- Write a clear implementation plan in scratch/plan.md
- Identify files that will change and risks.

Phase 3 — Implement
- Use multi-file-refactor or direct edits.
- Add tests as you go (test-writer skill).

Phase 4 — Self Review
- Run advanced-code-reviewer on the entire change set.
- Address all critical and important findings.

Phase 5 — Handoff / Ship
- Write excellent commit messages using git-workflow.
- Create a PR description with testing instructions.

## HANDOFF — Planner to Coder

**Goal**: <one sentence>

**Context**:
- Relevant files already explored: list
- Key decisions already made: list

**Tasks** (in order):
1. ...
2. ...

**Constraints**:
- Must remain backward compatible
- Follow existing patterns in components/ui

**Definition of Done**:
- All tasks complete
- Tests added and passing
- Self-review using advanced-code-reviewer completed

**Open Questions**:
- Question 1 (owner: Coder)

Start by creating scratch/plan.md with your approach.

After producing the main deliverable, perform this loop:

1. Switch to the advanced-code-reviewer (or equivalent) persona.
2. Review your own output using the full checklist.
3. Produce a "Critique" document with:
   - What is excellent
   - What must be fixed (with specific locations)
   - Suggested improvements
4. Go back to the implementer persona and apply the fixes.
5. Repeat once more if the critique still has critical items.

This single pattern is responsible for most of the quality difference between good and great agent output.

Strategy for a 200k+ LOC codebase:

1. Start with a high-level directory summary (tree -L 2 plus the README).
2. Ask the agent to produce a "relevant files" list for the current task.
3. Feed only those files + a 1-2 paragraph summary of the rest of the system.
4. Use scratch files for intermediate reasoning.
5. For very large files, ask the agent to request specific functions or regions instead of the whole file.

The context-builder skill automates a lot of this process.

Team:
- Researcher: web search / fetch MCP + context-builder skill
- Planner: produces detailed plan + task breakdown
- Coder: implements using the plan (never deviates without explicit approval)
- Reviewer: advanced-code-reviewer + test-writer

Handoff protocol (always written to scratch/handoff-xxx.md):
- Summary of work done
- Artifacts created
- Open questions + confidence
- Recommended next agent + any constraints

Coordinator (or human) decides the sequence and can run agents in parallel when safe.

Input (rough idea):
"Users should be able to invite teammates to a workspace via email with role selection."

Step 1: Draft a PRD (doc-generator skill) → workspace-invites.prd.md

Step 2: Use doc-generator + api-designer on the PRD to produce:
- OpenAPI additions
- Data model changes
- Frontend components needed

Step 3: Planner turns the above into a detailed task list in scratch/plan.md

Step 4: Coder + Reviewer execute the plan using the multi-file-refactor and test-writer skills.

This flow consistently produces much higher quality results than "just go build invites".

// .mcp.json — project-scoped MCP servers, checked into git.
// Every teammate running Claude Code in this repo gets them automatically.
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

// CLAUDE.md — one line, so Claude Code and every
// AGENTS.md-reading agent share the same project rules:
//
//   @AGENTS.md

<!-- .claude/skills/code-reviewer/SKILL.md -->
---
name: code-reviewer
description: Use when reviewing diffs, PRs, or staged changes for correctness, security, and missing tests.
---

You are an expert senior engineer performing a rigorous code review.

Process:
1. Read the diff and the surrounding context of every changed file.
2. Check correctness, security, performance, maintainability, and tests — in that order.
3. Cite file:line for every finding.

Output (exact sections):
## Summary
## Critical Issues
## Important Improvements
## Suggested Tests

Rules:
- Never be vague. Every finding needs a concrete fix.
- If something is excellent, say so.

<!--
Folder layout:
.claude/skills/code-reviewer/
├── SKILL.md          ← this file (required)
├── checklist.md      ← optional supporting docs, loaded on demand
└── scripts/          ← optional executable helpers

Project skills: .claude/skills/   Personal skills: ~/.claude/skills/
The frontmatter description is how the agent decides to load the skill —
write it as "Use when…" with concrete triggers.
-->

<!-- .claude/agents/reviewer.md -->
---
name: reviewer
description: Reviews code changes for quality and security. Use proactively after completing any feature or fix.
tools: Read, Grep, Glob, Bash
---

You are a code reviewer with read-only intent: you inspect, you never fix.

When invoked:
1. Run `git diff` to see recent changes.
2. Read every modified file plus enough context to judge the change.
3. Review against: correctness, security, performance, tests.

Report findings as:
- [CRITICAL] file:line — issue and the concrete fix the main agent should apply
- [IMPORTANT] …
- [MINOR] …

Never edit files yourself — your value is an independent second opinion
from a clean context, free of the implementer's assumptions.

<!--
Why subagents for review:
- Fresh context = no anchoring on the implementation's own reasoning
- Restricted tools (no Edit/Write) = review stays review
- The main agent applies fixes, keeping one consistent author
Project: .claude/agents/   Personal: ~/.claude/agents/
-->

# 1. Install Grok Build (xAI's terminal coding agent)
curl -fsSL https://x.ai/cli/install.sh | bash

# 2. Start it in your project — it auto-reads AGENTS.md from the git root down
cd your-project
grok

# 3. Grok Build is MCP-native: servers you already use just work.
#    The same AGENTS.md, skills, and MCP servers carry over from
#    Claude Code / Codex — no reconfiguration.

# Plan Mode is on by default: Grok writes a file-by-file plan and
# waits for approval before editing. It can run up to 8 subagents in
# parallel, each in its own git worktree.

# Per-directory override for local-only tweaks (not committed):
#   AGENTS.override.md   # wins over AGENTS.md in that directory

# The model is grok-build-0.1 (256K context). Everything below is the
# same AGENTS.md you'd use with any other runner:
#
#   ## Commands
#   - Test: pnpm test
#   - Lint + typecheck: pnpm lint && pnpm exec tsc --noEmit
#   ## Conventions
#   - Never use `any`; use `unknown` + type guards

# .github/workflows/agent-triage.yml
# Runs a coding agent non-interactively on new issues.
# Works the same way across Claude Code, Codex, and Grok Build —
# each exposes a headless "-p" / print mode for automation.

name: Agent triage
on:
  issues:
    types: [opened]

jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install agent
        run: npm install -g @anthropic-ai/claude-code
        # Grok Build: curl -fsSL https://x.ai/cli/install.sh | bash
        # Codex CLI:  npm install -g @openai/codex

      - name: Run agent headless
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          # XAI_API_KEY for Grok Build, OPENAI_API_KEY for Codex
        run: |
          claude -p "Read AGENTS.md, then reproduce and root-cause the bug in
          issue #${{ github.event.issue.number }}. Post findings as a comment.
          Do NOT push code." \
            --allowedTools "Read,Grep,Bash(gh issue comment:*)"

# Safety in CI: grant the narrowest tool/permission scope possible,
# never expose write/deploy access, and keep secrets in the CI vault.

feat(auth): add magic link login with rate limiting

## Why
Users requested passwordless login. Magic links reduce friction while maintaining security.

## What changed
- New /api/auth/magic-link endpoint (rate limited + signed tokens)
- Email template + send abstraction
- Frontend magic link form in login page
- Added tests for rate limiting and token expiry

## Testing
- Run the new magic link e2e test
- Try the flow locally with Mailpit

## Screenshots
[attached]

Refs: #284

// Shared error model (use this everywhere)
export class ApiError extends Error {
  constructor(
    public code: string,           // MACHINE_READABLE e.g. "VALIDATION_ERROR"
    message: string,               // Human friendly
    public details?: Record<string, unknown>,
    public requestId?: string,
  ) {
    super(message);
    this.name = 'ApiError';
  }
}

// Client helper
export async function handleApiResponse<T>(res: Response): Promise<T> {
  if (res.ok) return res.json();
  const err = await res.json().catch(() => ({}));
  throw new ApiError(err.code || 'UNKNOWN', err.message || res.statusText, err.details, err.requestId);
}

Rule: Before you touch any source file or run any command that has side effects, create or update scratch/current.md with:

- The user request (verbatim)
- Your current understanding / assumptions
- The plan (even if rough)
- What you will do first

This externalizes reasoning, makes recovery trivial when the agent gets confused, and gives humans full visibility.

Many of the highest-performing teams treat the scratch directory as sacred.