Apex Learn

APEX Learn

Analyze what happened during a task, extract reusable knowledge, and persist it to AGENTS.md so the entire agent team improves over time.

When to Use

Run this skill in any of these situations:

• After completing a Tier 1, 2, or 3 task
• When the human corrected you on the same issue twice (two-strike rule)
• When you discovered a non-obvious pattern or convention
• When a task took significantly longer than expected
• When the human explicitly asks to update the rules

The Two-Strike Rule

This is the core mechanism. If you are corrected on the same type of issue twice:

1. First correction — Fix the issue, note it mentally 2. Second correction — Fix the issue AND run apex-learn to add a permanent rule

This prevents the same mistake from recurring across sessions.

Workflow

1. Identify friction points 2. Classify the learning 3. Draft the rule 4. Append to AGENTS.md 5. Verify the update

Step 1: Identify Friction Points

Ask yourself these questions about the completed task:

## Friction Analysis

1. Where did I get stuck or make mistakes?
2. What did the human correct me on?
3. What took longer than expected and why?
4. What assumptions did I make that were wrong?
5. What patterns did I discover that aren't documented?

Step 2: Classify the Learning

Each learning falls into one of these categories:

Step 3: Draft the Rule

Write the rule in imperative form. Be specific and actionable:

Good rules:

- Always use `pnpm` instead of `npm` for package management
- Never modify files in `src/auth/` without explicit approval
- When creating API endpoints, always include rate limiting middleware

Bad rules:

- Be careful with packages (too vague)
- Try to write good code (not actionable)
- Remember the auth thing (not specific)

Step 4: Append to AGENTS.md

Run the learning script to safely append the new rule:

Linux/Mac:

bash "${CLAUDE_SKILL_DIR}/scripts/append-learning.sh" "<category>" "<rule-text>"

Windows:

powershell -File "${CLAUDE_SKILL_DIR}/scripts/append-learning.ps1" "<category>" "<rule-text>"

If AGENTS.md does not exist, create it using the template in references/agents-template.md.

Step 5: Verify the Update

Read AGENTS.md after the update. Confirm:

• The new rule is in the correct section
• It does not duplicate an existing rule
• It does not contradict an existing rule
• The file is still well-formatted

If a contradiction is found, present both rules to the human and ask which takes priority.

Output

An updated AGENTS.md file with the new rule appended to the correct section, committed with message docs: apex-learn — add rule for {category}.

Example diff:

 ## Tools

+- Always use `pnpm` instead of `npm` for package management
+- Run `pnpm install --frozen-lockfile` in CI environments

 ## Learnings Log

+### 2026-03-14: Package Manager
+- Agent used npm twice before this rule was added
+- Root cause: default behavior, no explicit instruction

Example commit:

docs: apex-learn — add rule for tools

Added package manager preference after two-strike correction.
Agent was defaulting to npm instead of pnpm.

AGENTS.md — Project Intelligence

This file is the project's living memory. It is read by AI agents before every task.

Rules are added automatically via apex-learn when patterns are discovered.

Do not delete rules without understanding why they were added.

Identity

• Project: {PROJECT_NAME}
• Stack: {TECH_STACK}
• Package Manager: {PACKAGE_MANAGER}

The Two-Strike Rule

If you are corrected on the same issue twice:

1. First correction — Fix the issue, note it mentally 2. Second correction — Fix it AND add a permanent rule to this file

This prevents the same mistake from recurring across sessions. When adding a rule, place it in the appropriate section below.

Self-Improvement

After any task where you struggled or were corrected, ask yourself:

1. What did I learn? 2. Should anything be added to this file?

If the human corrects you twice on the same thing, immediately add a rule using apex-learn.

Tone

• Never claim you are "absolutely right" about something
• Do not be a yes-man — push back respectfully when you disagree or see problems
• Admit uncertainty when you're not confident
• If you made a mistake, acknowledge it directly without excessive apology

Code Style

Architecture Rules

Workflow

• Always create a feature branch before making changes
• Run the full validation chain (lint, types, tests, build) before committing
• Run the formatter before committing
• Always create a new commit rather than amending an existing one (preserves history for review)
• Open draft PRs for review — never push directly to main
• Write descriptive commit messages: type(scope): description

Boundaries

• Never modify files outside the assigned task scope
• Never commit secrets, API keys, or credentials
• Never remove failing tests — fix them or flag for review
• Never push to main or production branches directly

Preferences

Tools

Learnings Log

<!-- New learnings are appended here by apex-learn -->