# Optimise Claude

> Use when auditing, trimming, or restructuring AI skill files to reduce context-window consumption.

- Skill: `ralphcrisostomo/optimise-claude` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add ralphcrisostomo/optimise-claude`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ralphcrisostomo/optimise-claude/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ralphcrisostomo (https://skillmd.com/u/ralphcrisostomo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ralphcrisostomo/optimise-claude

---


# Optimise Claude

Use this skill when auditing AI skill files for size, structure, duplication, or bloated AGENTS.md inline blocks.

## Scope

All operations are strictly limited to **project-level** skill directories:
- `.agents/skills/` (relative to project root)
- `.claude/skills/` (relative to project root)

**NEVER** touch user-level (home directory) skill locations:
- `~/.agents/skills/`
- `~/.claude/skills/`

Never read, write, list, or modify any file outside the current project root (`$PWD`).

## When to Use

- Skill files exceed ~120 lines.
- Frontmatter or section order is non-canonical.
- Multiple skills contain duplicated content.
- An AGENTS.md file has inline instruction blocks >30 lines that should be skills.

## Workflow

Run phases sequentially. Skip any phase that does not apply. Only operate on files within the current project repo.

### Phase 1 — Inventory & Triage

1. List every `SKILL.md` under the project's `.agents/skills/`.
2. For each file, record: name, line count, has frontmatter (y/n), has canonical sections (y/n).
3. Flag violations: >120 lines, missing/incorrect frontmatter, wrong section order.
4. Output a triage table sorted by line count descending.

```
| Skill | Lines | FM | Sections | Violations |
|-------|------:|----|----------|------------|
```

### Phase 2 — Reduce Token Usage

For each flagged skill:

- Trim prose to imperative bullets.
- Collapse verbose examples to minimal code fences.
- Remove redundant explanations already covered by parent AGENTS.md.
- Remove blank lines between list items.
- Target <=120 lines. If still over, split into focused sub-skills.

### Phase 3 — Fix Structure & Frontmatter

For each skill:

- Ensure YAML frontmatter has `name` matching directory and `description` starting with "Use when".
- Enforce canonical section order: H1 title, scope line, When to Use, Rules/Instructions, Quick Reference, Validation.
- Remove empty or placeholder sections.
- Use imperative voice throughout.

### Phase 4 — Cross-Skill Deduplication

1. Identify repeated content blocks across project skills (>5 similar lines).
2. Move shared content to the project's root `AGENTS.md` or a dedicated shared skill within `.agents/skills/`.
3. Replace duplicates with a one-line pointer: "See `<skill-name>` for …".
4. Reword overlapping `description` fields so each skill has a unique trigger.

### Phase 5 — Extract Bloated AGENTS.md Blocks

1. Scan `AGENTS.md` files within the project for inline instruction blocks >30 lines.
2. For each block, create a new skill at `.agents/skills/<name>/SKILL.md` within the project. Never create files outside the project repo.
3. Replace the original block with a slim pointer + Quick Reference.
4. If the project has a skill sync script, run it to sync `.agents/skills/` to `.claude/skills/` within the project.

## Output Format

After all phases, produce a summary report:

```
## Optimisation Report

| Skill | Before | After | Delta |
|-------|-------:|------:|------:|
| ...   |    250 |   110 |  -140 |

Total skills: N
Total lines saved: N
New skills created: N
```

## Quick Reference

- Only operate on project-level `.agents/skills/` and `.claude/skills/` — never `~/.agents/skills/` or `~/.claude/skills/`.
- Source of truth: project's `.agents/skills/` — never edit `.claude/skills/` directly.
- Canonical section order: H1, scope, When to Use, Rules, Quick Reference, Validation.
- Target: <=120 lines per skill.
- Never read, write, list, or modify files outside the project root.

## Validation

- `wc -l .agents/skills/*/SKILL.md` — no file exceeds 120 lines.
- Every `SKILL.md` has valid YAML frontmatter with `name` and `description`.
- No two skills share >5 identical lines.
- No `AGENTS.md` within the project has inline instruction blocks >30 lines without a skill pointer.
- No files outside the project root were modified.
- No files under `~/.agents/skills/` or `~/.claude/skills/` were read or modified.