# denfry/claude-skills architecture

> Architecture diagram of the GitHub repository denfry/claude-skills, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/denfry/claude-skills
- Repository: https://github.com/denfry/claude-skills

## Overview

claude-skills is a collection of Claude agent skills; its featured token-efficiency skill shapes responses across coding, writing, research, and chat. The main path is a user request handled under the skill’s guidance, with optional Claude Code hooks reinforcing the guidance, flagging inefficient tool use, and reporting session metrics. The repository also provides worked examples and an A/B evaluation harness. Hook implementation details are sampled; relationships for the unsampled skill content and examples are limited to README documentation.

Main entry points: [`skills/token-efficiency/hooks/install.py`](https://github.com/denfry/claude-skills/blob/main/skills/token-efficiency/hooks/install.py) (Hook installer), [`skills/token-efficiency/hooks/efficiency_core.py`](https://github.com/denfry/claude-skills/blob/main/skills/token-efficiency/hooks/efficiency_core.py) (Prompt reinforcement), [`skills/token-efficiency/hooks/session_report.py`](https://github.com/denfry/claude-skills/blob/main/skills/token-efficiency/hooks/session_report.py) (Session report), [`skills/token-efficiency/hooks/_state.py`](https://github.com/denfry/claude-skills/blob/main/skills/token-efficiency/hooks/_state.py) (Session state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_skill["Skill guidance"]
  node_skill_body["Response guidance<br/>[SKILL.md]"]
  node_core_contract["Core contract<br/>[CORE.md]"]
  node_short_contract["Short contract<br/>[CORE_SHORT.md]"]
  node_examples["Worked examples<br/>[examples.md]"]
end

subgraph group_hooks["Claude Code hooks"]
  node_installer["Hook installer<br/>[install.py]"]
  node_budget_hook["Context budget<br/>[context_budget.py]"]
  node_prompt_hook["Prompt reinforcement<br/>[efficiency_core.py]"]
  node_trajectory_hook["Trajectory guard"]
  node_report_hook["Session report<br/>[session_report.py]"]
  node_state[("Session state<br/>[_state.py]")]
end

subgraph group_evaluation["Evaluation resources"]
  node_eval_harness["A/B eval harness<br/>[measure.py]"]
  node_eval_cases["Eval tasks<br/>[evals.json]"]
end

node_user(("User"))
node_claude(("Claude surface"))

node_user -->|"submits request"| node_claude
node_skill_body -->|"guides responses"| node_claude
node_claude -->|"returns response"| node_user
node_claude -.->|"consults examples"| node_examples
node_installer -->|"registers hook"| node_budget_hook
node_installer -->|"registers hook"| node_prompt_hook
node_installer -->|"registers hook"| node_trajectory_hook
node_installer -->|"registers hook"| node_report_hook
node_prompt_hook -->|"reads contract"| node_core_contract
node_prompt_hook -->|"reads contract"| node_short_contract
node_budget_hook -->|"reads event"| node_state
node_trajectory_hook -->|"loads and saves"| node_state
node_report_hook -->|"loads and saves"| node_state
node_report_hook -->|"writes metrics for"| node_eval_harness
node_eval_harness -->|"loads tasks"| node_eval_cases

click node_skill_body "https://github.com/denfry/claude-skills/blob/main/skills/token-efficiency/SKILL.md"
click node_core_contract "https://github.com/denfry/claude-skills/blob/main/skills/token-efficiency/CORE.md"
click node_short_contract "https://github.com/denfry/claude-skills/blob/main/skills/token-efficiency/CORE_SHORT.md"
click node_examples "https://github.com/denfry/claude-skills/blob/main/skills/token-efficiency/references/examples.md"
click node_installer "https://github.com/denfry/claude-skills/blob/main/skills/token-efficiency/hooks/install.py"
click node_budget_hook "https://github.com/denfry/claude-skills/blob/main/skills/token-efficiency/hooks/context_budget.py"
click node_prompt_hook "https://github.com/denfry/claude-skills/blob/main/skills/token-efficiency/hooks/efficiency_core.py"
click node_trajectory_hook "https://github.com/denfry/claude-skills/blob/main/skills/token-efficiency/hooks/trajectory_guard.py"
click node_report_hook "https://github.com/denfry/claude-skills/blob/main/skills/token-efficiency/hooks/session_report.py"
click node_state "https://github.com/denfry/claude-skills/blob/main/skills/token-efficiency/hooks/_state.py"
click node_eval_harness "https://github.com/denfry/claude-skills/blob/main/skills/token-efficiency/evals/measure.py"
click node_eval_cases "https://github.com/denfry/claude-skills/blob/main/skills/token-efficiency/evals/evals.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_skill_body,node_core_contract,node_short_contract,node_examples,node_user toneBlue
class node_installer,node_budget_hook,node_prompt_hook,node_trajectory_hook,node_report_hook,node_state toneAmber
class node_eval_harness,node_eval_cases toneMint
class node_claude toneIndigo
```

## Components

### Skill guidance

- [Response guidance](https://github.com/denfry/claude-skills/blob/main/skills/token-efficiency/SKILL.md): `skills/token-efficiency/SKILL.md`
- [Core contract](https://github.com/denfry/claude-skills/blob/main/skills/token-efficiency/CORE.md): `skills/token-efficiency/CORE.md`
- [Short contract](https://github.com/denfry/claude-skills/blob/main/skills/token-efficiency/CORE_SHORT.md): `skills/token-efficiency/CORE_SHORT.md`
- [Worked examples](https://github.com/denfry/claude-skills/blob/main/skills/token-efficiency/references/examples.md): `skills/token-efficiency/references/examples.md`

### Claude Code hooks

- [Hook installer](https://github.com/denfry/claude-skills/blob/main/skills/token-efficiency/hooks/install.py): `skills/token-efficiency/hooks/install.py`
- [Context budget](https://github.com/denfry/claude-skills/blob/main/skills/token-efficiency/hooks/context_budget.py): `skills/token-efficiency/hooks/context_budget.py`
- [Prompt reinforcement](https://github.com/denfry/claude-skills/blob/main/skills/token-efficiency/hooks/efficiency_core.py): `skills/token-efficiency/hooks/efficiency_core.py`
- [Trajectory guard](https://github.com/denfry/claude-skills/blob/main/skills/token-efficiency/hooks/trajectory_guard.py): `skills/token-efficiency/hooks/trajectory_guard.py`
- [Session report](https://github.com/denfry/claude-skills/blob/main/skills/token-efficiency/hooks/session_report.py): `skills/token-efficiency/hooks/session_report.py`
- [Session state](https://github.com/denfry/claude-skills/blob/main/skills/token-efficiency/hooks/_state.py): `skills/token-efficiency/hooks/_state.py`

### Evaluation resources

- [A/B eval harness](https://github.com/denfry/claude-skills/blob/main/skills/token-efficiency/evals/measure.py): `skills/token-efficiency/evals/measure.py`
- [Eval tasks](https://github.com/denfry/claude-skills/blob/main/skills/token-efficiency/evals/evals.json): `skills/token-efficiency/evals/evals.json`

### Other components

- **User**
- **Claude surface**

## Connections

- User → Claude surface: submits request (evidence: `README.md`)
- Response guidance → Claude surface: guides responses (evidence: `README.md`)
- Claude surface → User: returns response (evidence: `README.md`)
- Claude surface → Worked examples: consults examples (evidence: `README.md`)
- Hook installer → Context budget: registers hook (evidence: `skills/token-efficiency/hooks/install.py`)
- Hook installer → Prompt reinforcement: registers hook (evidence: `skills/token-efficiency/hooks/install.py`)
- Hook installer → Trajectory guard: registers hook (evidence: `skills/token-efficiency/hooks/install.py`)
- Hook installer → Session report: registers hook (evidence: `skills/token-efficiency/hooks/install.py`)
- Prompt reinforcement → Core contract: reads contract (evidence: `skills/token-efficiency/hooks/efficiency_core.py`)
- Prompt reinforcement → Short contract: reads contract (evidence: `skills/token-efficiency/hooks/efficiency_core.py`)
- Context budget → Session state: reads event (evidence: `skills/token-efficiency/hooks/context_budget.py`)
- Trajectory guard → Session state: loads and saves (evidence: `skills/token-efficiency/hooks/trajectory_guard.py`)
- Session report → Session state: loads and saves (evidence: `skills/token-efficiency/hooks/session_report.py`)
- Session report → A/B eval harness: writes metrics for (evidence: `skills/token-efficiency/hooks/session_report.py`)
- A/B eval harness → Eval tasks: loads tasks (evidence: `skills/token-efficiency/evals/measure.py`)