git:20260622.7371dc6 to git:20260803.af106c2

3 added, 1 removed. Audit A to A.

# 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.

- - **allowed-tools**: read-only → `Read, Grep, Glob`; editing → add `Write, Edit`; automation → add `Bash`.

+ - **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.)