Skip to content

AGENTS.md

Latest commit

 

History

History
171 lines (111 loc) · 5.06 KB

AGENTS.md

File metadata and controls

171 lines (111 loc) · 5.06 KB

AGENTS.md

This file provides guidance to AI coding agents (Claude Code, Cursor, Copilot, Antigravity, etc.) when working with code in this repository.

Repository Overview

A collection of skills for Claude.ai and Claude Code for senior software engineers. Skills are packaged instructions and scripts that extend Claude and your coding agents capabilities.

OpenCode Integration

OpenCode uses a skill-driven execution model powered by the skill tool and this repository's /skills directory.

Core Rules

  • If a task matches a skill, you MUST invoke it
  • Skills are located in skills/<skill-name>/SKILL.md
  • Never implement directly if a skill applies
  • Always follow the skill instructions exactly (do not partially apply them)

Intent → Skill Mapping

The agent should automatically map user intent to skills:

  • Feature / new functionality → spec-driven-development, then incremental-implementation
  • Planning / breakdown → planning-and-task-breakdown
  • Bug / failure / unexpected behavior → debugging-and-error-recovery
  • Code review → code-review-and-quality
  • Refactoring / simplification → code-simplification
  • API or interface design → api-and-interface-design
  • UI work → frontend-ui-engineering

Lifecycle Mapping (Implicit Commands)

OpenCode does not support slash commands like /spec or /plan.

Instead, the agent must internally follow this lifecycle:

  • DEFINE → spec-driven-development
  • PLAN → planning-and-task-breakdown
  • BUILD → incremental-implementation
  • VERIFY → debugging-and-error-recovery
  • REVIEW → code-review-and-quality

Execution Model

For every request:

  1. Determine if any skill applies (even 1% chance)
  2. Invoke the appropriate skill using the skill tool
  3. Follow the skill workflow strictly
  4. Only proceed to implementation after required steps (spec, plan, etc.) are complete

Anti-Rationalization

The following thoughts are incorrect and must be ignored:

  • "This is too small for a skill"
  • "I can just quickly implement this"
  • "I’ll gather context first"

Correct behavior:

  • Always check for and use skills first

This ensures OpenCode behaves similarly to Claude Code with full workflow enforcement.

Creating a New Skill

Directory Structure

skills/
  {skill-name}/           # kebab-case directory name
    SKILL.md              # Required: skill definition
    scripts/              # Required: executable scripts
      {script-name}.sh    # Bash scripts (preferred)
  {skill-name}.zip        # Required: packaged for distribution

Naming Conventions

  • Skill directory: kebab-case (e.g. web-quality)
  • SKILL.md: Always uppercase, always this exact filename
  • Scripts: kebab-case.sh (e.g., deploy.sh, fetch-logs.sh)
  • Zip file: Must match directory name exactly: {skill-name}.zip

SKILL.md Format

---
name: {skill-name}
description: {One sentence describing when to use this skill. Include trigger phrases like "Deploy my app", "Check logs", etc.}
---

# {Skill Title}

{Brief description of what the skill does.}

## How It Works

{Numbered list explaining the skill's workflow}

## Usage

```bash
bash /mnt/skills/user/{skill-name}/scripts/{script}.sh [args]

Arguments:

  • arg1 - Description (defaults to X)

Examples: {Show 2-3 common usage patterns}

Output

{Show example output users will see}

Present Results to User

{Template for how Claude should format results when presenting to users}

Troubleshooting

{Common issues and solutions, especially network/permissions errors}


### Best Practices for Context Efficiency

Skills are loaded on-demand — only the skill name and description are loaded at startup. The full `SKILL.md` loads into context only when the agent decides the skill is relevant. To minimize context usage:

- **Keep SKILL.md under 500 lines** — put detailed reference material in separate files
- **Write specific descriptions** — helps the agent know exactly when to activate the skill
- **Use progressive disclosure** — reference supporting files that get read only when needed
- **Prefer scripts over inline code** — script execution doesn't consume context (only output does)
- **File references work one level deep** — link directly from SKILL.md to supporting files

### Script Requirements

- Use `#!/bin/bash` shebang
- Use `set -e` for fail-fast behavior
- Write status messages to stderr: `echo "Message" >&2`
- Write machine-readable output (JSON) to stdout
- Include a cleanup trap for temp files
- Reference the script path as `/mnt/skills/user/{skill-name}/scripts/{script}.sh`

### Creating the Zip Package

After creating or updating a skill:

```bash
cd skills
zip -r {skill-name}.zip {skill-name}/

End-User Installation

Document these two installation methods for users:

Claude Code:

cp -r skills/{skill-name} ~/.claude/skills/

claude.ai: Add the skill to project knowledge or paste SKILL.md contents into the conversation.

If the skill requires network access, instruct users to add required domains at claude.ai/settings/capabilities.