CLAUDE.md git:20260803.af106c2A

Immutable. This exact content is served forever at /api/v1/blob/3819a7f35202856b.

# CLAUDE.md

Guidance for AI coding agents working in this repository.

## Project

**cortex** — a Claude Code plugin providing AI coding skills. Pure markdown + YAML, no build system. Plugin manifest: `.claude-plugin/plugin.json`. Skills invoke as `/cortex:<skill-name>`.

## Skill Structure

```text
skills/<skill-name>/
├── SKILL.md        # skill definition + YAML frontmatter
└── references/     # optional, loaded conditionally by SKILL.md
```

## Skill Authoring — `/skill-creator` Required

Creating, editing, condensing, or auditing any `SKILL.md` or its `references/` **requires the [`skill-creator` plugin](https://claude.com/plugins/skill-creator)**. It is the single source of truth for frontmatter fields, body-section order, progressive-disclosure conventions, reference-file layout, and token efficiency — this repo intentionally does not duplicate those rules.

Install it once:

```bash
claude plugin install skill-creator@claude-plugins-official
```

Then invoke `/skill-creator:skill-creator` for any skill-authoring task.

**If `/skill-creator:skill-creator` is not installed, stop and ask the user to install it before running the prompt.** Do not fall back to hand-authoring a skill from memory or from this file — the conventions drift quickly and the plugin is the authority.

## Git

- **Never commit unless explicitly asked.** Stage, show the diff, wait for confirmation.
- **Conventional Commits**: `<type>(<scope>): <description>`
  - Types: `feat`, `fix`, `docs`, `refactor`, `chore`
  - Scope: skill name, or `plugin` for plugin-wide changes
- No triple backticks in commit messages.

## Versioning

**Bump as part of the change, not after.** Classify the change (patch / minor / major), then update `.claude-plugin/plugin.json` in the same diff. A commit without a matching bump is incomplete.

Bump `plugin.json` to the highest level present in the diff:

- **patch**: typos, wording, formatting, config adjustments
- **minor**: expanded skill content, new references, new/removed skill
- **major**: rewritten role/workflow, breaking structural change

Mixed changes take the highest level (2 patches + 1 minor = minor).

### Review (every review task)

Every review — code review, audit, PR, self-check — must verify the version bump:

1. Determine the actual semver level of the diff.
2. Compare against the bump in `plugin.json`.
3. **Missing or under-bumped**: fix in the same pass; note the change and reason to the user.
4. **Over-bumped**: flag with a suggested downgrade; don't silently edit (may be intentional).

## Markdown Formatting

Run `./lint.sh` until it exits clean before completing any markdown task — see the script header for usage. Configs: `.prettierrc`, `.prettierignore`, `.markdownlint-cli2.jsonc`.

Add a markdownlint disable only when the rule is genuinely wrong for this codebase, with a comment explaining why.

## Conventions

- **Naming**: kebab-case for skill directories and files.
- **Formatting**: UTF-8, LF, 2-space indent — see `.editorconfig`.
- **Reference files**: conditionally loaded by SKILL.md — never standalone skills.
- **Frontmatter**: `name` and `description` only. Do not add `allowed-tools`.

  `allowed-tools` is not a capability declaration — it pre-approves tools so they run **without a permission prompt** for the turn that invokes the skill. Adding it means these skills silently bypass the consumer's own permission settings, which is not ours to decide for someone installing a plugin. Leaving it out means every tool call goes through their configured permissions. (The field that actually restricts is `disallowed-tools`, which removes tools from the pool while a skill is active — only justified for a skill that must never call something, and none of ours qualify.)