explain-intuition

Explain Intuition

A portable AI-agent skill that turns solved work into simple, reusable intuition.

Use it after debugging, deployment, research, configuration, code changes, or any complex agent-assisted task when you want to understand:

• What actually happened
• The mental model behind the fix
• What the agent did
• How to recognize the same pattern later
• What to ask an AI agent next time

Install

This repository uses the open SKILL.md pattern:

skills/explain-intuition/SKILL.md

Different agents load that file from different folders.

Claude Code

Personal install:

mkdir -p ~/.claude/skills
cp -R skills/explain-intuition ~/.claude/skills/

Project install:

mkdir -p .claude/skills
cp -R skills/explain-intuition .claude/skills/

Plugin marketplace install, after this repo is public:

/plugin marketplace add fahmidhasann/explain-intuition-skill
/plugin install explain-intuition@explain-intuition-skill

Claude Code plugin skills are namespaced, so the slash command may appear as:

/explain-intuition:explain-intuition

OpenAI Codex

Personal install:

mkdir -p ~/.agents/skills
cp -R skills/explain-intuition ~/.agents/skills/

Repo install:

mkdir -p .agents/skills
cp -R skills/explain-intuition .agents/skills/

Codex also supports distributing reusable skills as plugins. This repo includes:

.codex-plugin/plugin.json
.agents/plugins/marketplace.json

After the repo is public, users can add it as a Codex marketplace/source where their Codex version supports plugin marketplaces.

Windsurf Cascade

Workspace skill:

mkdir -p .windsurf/skills
cp -R skills/explain-intuition .windsurf/skills/

Global skill:

mkdir -p ~/.codeium/windsurf/skills
cp -R skills/explain-intuition ~/.codeium/windsurf/skills/

Windsurf also scans .agents/skills and ~/.agents/skills, so the Codex-style install can work for cross-agent setups.

OpenCode

Project install:

mkdir -p .opencode/skills
cp -R skills/explain-intuition .opencode/skills/

Global install:

mkdir -p ~/.config/opencode/skills
cp -R skills/explain-intuition ~/.config/opencode/skills/

OpenCode also scans .claude/skills, ~/.claude/skills, .agents/skills, and ~/.agents/skills.

Adapters

Some popular agents do not currently load SKILL.md as a dynamic skill, but they do support reusable instruction files. Use the files in adapters/ for those agents:

| Agent | Use this file | Put it here | | --- | --- | --- | | Cursor | adapters/cursor-rule.mdc | .cursor/rules/explain-intuition.mdc | | GitHub Copilot | adapters/copilot-instructions.md | .github/copilot-instructions.md or .github/instructions/explain-intuition.instructions.md | | Gemini CLI | adapters/GEMINI.md | GEMINI.md or ~/.gemini/GEMINI.md | | Generic agents | adapters/AGENTS.md | AGENTS.md | | Windsurf rule fallback | adapters/windsurf-rule.md | .windsurf/rules/explain-intuition.md |

Prefer the real SKILL.md install when your agent supports skills. Use adapters only when your agent supports instructions or rules but not skills.

Example Prompt

Use Explain Intuition to explain what we just fixed and the mental model I should remember.

Repository Structure

.
├── skills/
│   └── explain-intuition/
│       └── SKILL.md
├── adapters/
│   ├── AGENTS.md
│   ├── GEMINI.md
│   ├── copilot-instructions.md
│   ├── cursor-rule.mdc
│   └── windsurf-rule.md
├── .claude-plugin/
│   ├── plugin.json
│   └── marketplace.json
├── .codex-plugin/
│   └── plugin.json
└── .agents/plugins/
    └── marketplace.json

Compatibility Notes

• Claude Code, Codex, Windsurf, and OpenCode support SKILL.md style skills.
• Claude.ai supports custom skills for eligible plans through its Skills UI; upload the skills/explain-intuition folder as a skill package if your account has that feature.
• Cursor, GitHub Copilot, and Gemini CLI mainly use rules or instruction files, so this repo includes adapter files for them.
• Always review third-party skills before installing them. This skill is instruction-only and does not include scripts or external tool calls.

References

• Agent Skills open standard
• OpenAI Codex Agent Skills
• OpenAI Codex plugins
• Claude Code skills
• Claude Code plugins
• Windsurf Cascade skills
• OpenCode Agent Skills
• Cursor rules
• GitHub Copilot custom instructions
• Gemini CLI context files

License

MIT