AGENTS.md

Guidelines for AI agents working in this repository.

Project Overview

A curated suite of AI agent skills built around a single thesis: the AI refuses its default role so the human is forced to exercise judgment. Every skill in this library is a behavioral inversion — instead of producing answers, code, or solutions, the AI guides, challenges, and questions until the human arrives at the answer themselves.

These skills are judgment trainers. As vibe coding makes AI-generated output cheaper and more abundant, the scarce resource becomes developer judgment. This library exists to protect and strengthen that resource.

Repository Structure

skills/
├── core-inversions/        # reverse-vibe-coding, socratic-debugger, code-review-challenger, architect-interrogator, test-first-mentor
├── cognitive-forcing/      # first-principles-mode, devils-advocate-mode, rubber-duck-plus, complexity-cop
└── process-quality/        # pre-review-guide, api-design-coach, security-threat-guide, refactor-guide, docs-interrogator

Each skill has a SKILL.md file and optional references/ for detailed content.

The Shared DNA

All skills in this library share three invariants:

1. Memory file — each skill maintains a SKILL_MEMORY.md (or session notes) that tracks context across the conversation
2. Hard refusal layer — each skill explicitly defines what it will never do and why, stated upfront
3. Deviation philosophy — if a skill is about to break its contract, it must: acknowledge the deviation request → assess why the human wants it → guide forward within the contract

Never break these three invariants when writing or updating a skill.

Validation Commands

# Validate markdown formatting (requires markdownlint-cli)
markdownlint skills/**/*.md

# Check skill frontmatter is valid YAML
head -5 skills/core-inversions/reverse-vibe-coding/SKILL.md

# Verify all skills have required sections
grep -rl "## Purpose" skills/ --include="*.md" | wc -l
grep -rl "## Triggers" skills/ --include="*.md" | wc -l
grep -rl "## Workflow" skills/ --include="*.md" | wc -l
grep -rl "## Hard Refusals" skills/ --include="*.md" | wc -l
grep -rl "## Related" skills/ --include="*.md" | wc -l

SKILL.md Format

YAML Frontmatter

---
name: skill-name
description: <skill-name> skill for <domain>. Use when <scenarios>. Activates on <triggers>.
---

• name: Lowercase, hyphen-separated, matches directory name
• description: Must include "Use when" and "Activates on" clauses

Required Sections

Every SKILL.md must have:

1. Purpose (1-2 sentences): What the skill does and what it refuses
2. Hard Refusals (3-6 items): Explicit list of things the skill will never do, with one-line rationale each
3. Triggers (4-6 items): User query patterns that activate this skill
4. Workflow (numbered subsections): Step-by-step guidance with:
   • Decision trees (ASCII in code blocks)
   • Prompt tables (questions the AI asks)
   • Gates (conditions that must be met before moving forward)
   • Memory notes (what to track in SKILL_MEMORY.md)
5. Deviation Protocol (1 subsection): How to handle requests that violate the refusal contract
6. Related skills (2+ references): Cross-references using backtick format

Code Style Guidelines

Markdown

• Maximum body: 500 lines (put exhaustive question banks in references/)
• Code blocks: Always include language tag (```text, ```bash, ```yaml)
• Tables: Pipe syntax with header separator
• Lists: - for unordered, 1. for ordered

Cross-References

Use backticks for skill references:

• Correct: skills/core-inversions/socratic-debugger
• Incorrect: "the socratic-debugger skill" or [socratic-debugger](skills/core-inversions/socratic-debugger)

For internal references: [references/questions.md](references/questions.md)

Naming Conventions

• Skill directories: lowercase, hyphen-separated
• SKILL.md: always uppercase
• Reference files: lowercase with extension (questions.md, gates.md)

Decision Trees

Is the human asking for the answer directly?
├── Yes → Invoke Deviation Protocol
└── No  → Continue workflow step N

Tables

Common Workflows

Adding a New Skill

1. Create skills/<category>/<skill-name>/SKILL.md
2. Add all required sections (Purpose, Hard Refusals, Triggers, Workflow, Deviation Protocol, Related skills)
3. Create references/ if question banks or gate lists exceed 500 lines
4. Update README.md skills table
5. Add cross-references from 2+ related skills

Updating an Existing Skill

1. Keep body under 500 lines
2. Move exhaustive question lists to references/
3. Never weaken the Hard Refusals section
4. Preserve existing cross-references

Quality Checklist

• Frontmatter: name and description fields present
• Description: includes "Use when" and "Activates on"
• Purpose: 1-2 sentences, states what it does AND what it refuses
• Hard Refusals: 3-6 items, each with a rationale
• Triggers: 4-6 user query patterns
• Workflow: numbered subsections with gates
• Deviation Protocol: present and non-empty
• Code blocks: language tags included
• Related skills: 2+ references in backtick format
• Body length: under 500 lines