agent-instructions

Files (6)

• SKILL.md
• openai.yaml · agents/
• evals.json · evals/
• trigger-queries.json · evals/
• discoverability-filter.md · references/
• instruction-examples.md · references/

SKILL.md (first lines)

# agent-instructions Skill

**Purpose:** Create or refresh instruction files that guide agent behavior and reduce repeated mistakes without rewriting the repository or enforcing tool choices that contradict the codebase.

## Use this skill when

- Instruction files are missing, incomplete, or stale (no recent audit or updates)
- Agents repeatedly make the same mistake in a repository (e.g., always choosing a tool not suitable for this codebase, using wrong file paths, or using anti-patterns)
- A file-type or path-specific instruction file does not exist but the codebase has clear conventions (e.g., a TypeScript project with strict tsconfig, or a Terraform repo with specific backend patterns)
- Agent instruction files (AGENTS.md for Pi, copilot-instructions.md for Copilot) have grown large or overly generic and need to be split into focused per-path guides
- You need to document non-obvious operational constraints (signing requirements, security policies, deployment gates, testing procedures, environment setup)
- A repository has learned rules (lessons from prior corrections) that should be captured proactively

## Do not use this skill when

- The instructions already exist and are current (recent audit, regular updates)
- The guidance needed is already enforced by tooling (linters, type checkers, build config)
- The task is to change the actual repository code, configuration, or behavior (use other skills for that)
- The instructions would just be a tutorial or generic best-practice collection (not repository-specific)
- You are authoring for a role or context outside agent work (e.g., end-user documentation)

## Discoverability Filter

> **Before adding any line to an instruction file, ask:** "Can an agent discover this by reading the repo — README, code, config, scripts, directory tree?"
>
> If YES: do not include. If NO, and it materially affects task success: include.

This filter ensures instruction files stay focused, reduce duplication, and remain a source of truth for the non-obvious and operationally critical.

### What earns a line in the instruction file

1. **Non-discoverable from repository files alone**
   - Patterns not visible in code or config (e.g., an undocumented deployment gate, a security signing requirement, a hidden per-repository convention)
   - Lessons from prior agent mistakes that are not baked into tooling or naming

2. **Operationally significant**
   - Changes which commands agents run, which tools they reach for, or how they validate work
   - Affects the outcome of the task or the safety of the work
   - Alters the priority of conflicting tools or approaches in this specific repository

3. **Actionable and specific**
   - Concrete enough to execute; not a general principle or philosophy
   - References actual file paths, tool names, or specific repository state
   - Includes enough context that an agent can act on it immediately

### What to exclude (anti-patterns)

- Tech stack summaries or directory structure overviews (discoverable from README and filesystem)
- Architecture descriptions or design rationale (belongs in ADR or design documents, not instruction files)
- Generic best-practice advice (e.g., "write clean code," "test thoroughly")
- Rules already enforced by tooling (linters, type checkers, CI gates)
- Tutorials, examples, or learning resources (use project docs for that)
- Motivational statements or explanations of why something matters (keep instructions direct)

See [discoverability-filter.md](references/discoverability-filter.md) for deeper guidance and worked examples.

## Routing Boundary

| Signal | Route to this skill | Route elsewhere |
|--------|---------------------|-----------------|
| "Instructions need auditing" | ✓ | Review existing files first |
| "Agents keep doing X wrong" | ✓ | Check if a skill already addresses this |
| "I need a new instruction file" | ✓ | If the instruction is about code changes, use the relevant coding skill |
| "Update the README" | ✗ | User documentation belongs in README or project docs |
| "Enforce a linter or rule" | ✗ | Use tsconfig, eslint config, tooling setup (not instructions) |
| "Change the actual code" | ✗ | Use a coding or debugging skill |
| "Create or revise a reusable skill package" | ✗ | [`skill-creator`](../skill-creator/SKILL.md) |

## Inputs to gather

Before starting, clarify:

1. **Scope:** Which instruction files are in scope?
   - Project-level agent instruction files (commonly `AGENTS.md`, `Claude.md`, or harness-specific names in the repo root or parents)
   - User-level instruction files (paths are harness-specific; examples below)
   - Per-path or per-file-type guides when the harness supports them
   - Examples by harness:
     - **Pi Coding Agent:** user-level `~/.pi/agent/AGENTS.md` or `~/.pi/agent/CLAUDE.md`; project-level `AGENTS.md` / `CLAUDE.md`
     - **GitHub Copilot:** user-level `~/.copilot/copilot-instructions.md`; project-level `.github/copilot-instructions.md`; per-path `.github/instructions/*.md` (YAML frontmatter `description` and `applyTo`)
   - **Other harnesses / coding agents:** check that harness's docs for instruction-file conventions rather than assuming one layout
   - `AGENTS.md` (agent roster and routing) when used as a project router
   - Per-project files (if this is a multi-project workspace)

2. **Problem:** What mistake or gap triggers this work?
   - Give a concrete example of an agent mistake or missing guidance
   - How often does it happen?
   - Does it block work or just create extra review cycles?

3. **Constraints:** What is off-limits?
   - Are there existing tool choices or conventions that must not be overridden?
   - Does the repository have security, signing, or deployment gates that must be preserved?
   - Are there previous decisions documented elsewhere that should not be repeated?

## First move

1. **Audit current state:**
   - List all existing instruction files and their last update date
   - Skim each for stale or overly generic sections
   - Note any gaps (e.g., a TypeScript project with no typescript.instructions.md)

2. **Identify patterns:**
   - What mistakes or questions do agents keep hitting?
   - What non-obvious repository conventions exist?
   - Are there learned rules from past corrections that are not yet captured?

3. **Apply the Discoverability Filter:**
   - For each candidate instruction, ask: "Is this discoverable from the repository itself?"
   - Mark each line as keep, archive, or move-to-docs

## Workflow

### Phase 1: Audit
- Read all existing instruction files
- Identify duplicates, stale content, and gaps
- Gather examples of agent mistakes (from task history, prior sessions, or explicit user report)

### Phase 2: Filter
- For each instruction candidate: Apply the Discoverability Filter
- Group related instructions by file (global vs. per-path)

From matt-riley/agent-skills, GPL-3.0.

More from matt-riley/agent-skills