> ## Documentation Index
> Fetch the complete documentation index at: https://docs.entire.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Tutorial

> Learn how to use Entire Skills to explain code, investigate changes, search history, and hand work off between agents

This tutorial shows how to use [Entire Skills](https://github.com/entireio/skills) to explain code, investigate changes, search history, and hand work off between agents.

<Note>
  Entire Skills are most useful once Entire has recorded session context and Checkpoints. This tutorial creates that history as you go, so you can try the Skills even if you are starting fresh.
</Note>

By the end, you will:

1. Understand what each Skill does
2. Install the Skills locally
3. Practice the exact prompts and commands to use
4. Build a tiny app so the Skills have real code to work against

## Skills

<AccordionGroup>
  <Accordion title="session-handoff skill">
    Best for cross-agent handoffs, moving work to another agent, and summarizing recent session context.

    Example prompts:

    ```text theme={null}
    hand off this session
    hand off the codex session
    prepare a handoff for another agent
    ```

    Why it helps: saves time, prevents duplicate work, and preserves context.
  </Accordion>

  <Accordion title="explain skill">
    Best for understanding why a function, file, or change exists.

    Example prompts:

    ```text theme={null}
    /explain src/main.ts
    /explain parseConfig
    Explain why auth.ts exists
    ```

    Why it helps: great for onboarding, reveals intent, and separates design decisions from accidental complexity.
  </Accordion>

  <Accordion title="what-happened skill">
    Best for investigating a specific block of code or recent change.

    Example prompts:

    ```text theme={null}
    what happened here: src/app.ts:15-32
    what happened at src/app.ts:21
    tell me why this code is like this
    ```

    Why it helps: useful in review, helps debug regressions, and gives targeted provenance.
  </Accordion>

  <Accordion title="search skill">
    Best for finding prior work, earlier prompts, Checkpoints, or similar implementations.

    Example prompts:

    ```text theme={null}
    search past work for rate limiting
    find checkpoints about auth
    have we done this before?
    ```

    Why it helps: helps reuse prior work, surfaces decisions, and turns old history into something searchable.
  </Accordion>
</AccordionGroup>

## Prerequisites

Before using these Skills, make sure you have:

1. [Git installed](/cli/installation)
2. A supported AI agent: [Claude Code](/integrations/claude-code), [Codex](/integrations/codex), [Copilot CLI](/integrations/copilot-cli), [Cursor](/integrations/cursor), [Factory Droid](/integrations/factory-droid), [Gemini CLI](/integrations/gemini-cli), [OpenCode](/integrations/opencode), or [Pi](/integrations/pi)
3. The [Entire CLI installed](/cli/installation)

<Note>
  This tutorial uses [Codex](/integrations/codex) for the examples because it is one of the simplest ways to try these Skills from this repo. If you use [Claude Code](/integrations/claude-code), [Gemini CLI](/integrations/gemini-cli), or another supported tool, the same Skill terms still apply.
</Note>

## Install Skills

Choose the setup path that matches your tool:

<AccordionGroup>
  <Accordion title="Codex">
    See the [Codex integration guide](/integrations/codex).

    ```bash theme={null}
    mkdir -p ~/.agents/skills
    cd ~/.agents/skills
    git clone https://github.com/entireio/skills.git entire
    ```
  </Accordion>

  <Accordion title="Agent Skills">
    See the [Agent Skills homepage](https://agentskills.io/home).

    ```bash theme={null}
    npx skills add https://github.com/entireio/skills --all
    ```
  </Accordion>

  <Accordion title="Claude Code">
    See the [Claude Code integration guide](/integrations/claude-code).

    ```text theme={null}
    /plugin marketplace add entireio/skills
    /plugin install entire
    ```
  </Accordion>

  <Accordion title="Gemini CLI">
    See the [Gemini CLI integration guide](/integrations/gemini-cli).

    ```bash theme={null}
    gemini extensions install https://github.com/entireio/skills
    ```
  </Accordion>
</AccordionGroup>

## Install Entire

Install Entire by following the main [CLI installation guide](/cli/installation).

## Create a Project

We are going to build a tiny app called `bug-notes`.

This project is enough to:

* generate history
* make changes worth explaining
* create [Checkpoints](/cli/checkpoints) worth searching

Create the project:

```bash theme={null}
mkdir bug-notes
cd bug-notes
npm create vite@latest . -- --template vanilla
npm install
```

Run it:

```bash theme={null}
npm run dev
```

## Enable Entire

From inside `bug-notes`, run [`entire enable`](/cli/commands) for Codex and sign in:

```bash theme={null}
entire enable -y
entire login
```

When run in a fresh project folder, `entire enable -y` initializes Git, creates the initial commit, creates a GitHub repo, and pushes it so Checkpoints can be indexed.

<Tip>
  If you are using a different agent, use the corresponding integration flow instead. See [Codex](/integrations/codex), [Claude Code](/integrations/claude-code), or [Gemini CLI](/integrations/gemini-cli).
</Tip>

At this point, your project is ready to record [session](/glossary#session) context and [Checkpoints](/cli/checkpoints).

## Build the App

Open the repo in your AI agent and give it a focused task.

Suggested prompt:

```text theme={null}
Build a tiny bug tracker in this Vite app.
Requirements:
- Add a form with title and status
- Save bugs in local state
- Show a list of bug notes
- Allow filtering by open and fixed
- Keep the code simple and readable
```

Once the agent finishes, commit the result:

```bash theme={null}
git add .
git commit -m "Build bug notes app"
git push
```

That commit is important because the Skills become much more useful once there is committed and pushed history plus [Entire Checkpoint data](/cli/checkpoints).

## Add History

The `search` skill is most valuable when there are multiple [sessions](/glossary#session) with distinct concepts, not just one generic feature. Do these as separate chunks of work, then commit and push after each one.

### Persistence

Suggested prompt:

```text theme={null}
Add localStorage persistence so bug notes survive refresh.
Also add a small empty state when no notes exist.
```

Commit:

```bash theme={null}
git add .
git commit -m "Add persistence and empty state"
git push
```

### Duplicate Detection

Suggested prompt:

```text theme={null}
Add duplicate bug detection.
If a user tries to add a bug note with the same title as an existing one, show an inline validation message and prevent the duplicate.
```

Commit:

```bash theme={null}
git add .
git commit -m "Prevent duplicate bug entries"
git push
```

### Severity Badges

Suggested prompt:

```text theme={null}
Add a severity field with values low, medium, and high.
Show a colored severity badge in the bug list and allow filtering by severity.
```

Commit:

```bash theme={null}
git add .
git commit -m "Add severity badges and filter"
git push
```

Now you have three distinct stories in history:

* persistence
* duplicate detection
* severity filtering

That gives `search` much better material than a single vague feature.

## Practice Skills

### Explain

Ask:

```text theme={null}
/explain src/main.js
```

Or:

```text theme={null}
Explain why the persistence logic exists
```

What you should notice:

* the skill is trying to connect the code to the original session context
* this is different from a normal code explanation, which only describes current behavior

### What Happened

Find a specific code range first:

```bash theme={null}
nl -ba src/main.js | sed -n '1,220p'
```

Then ask:

```text theme={null}
what happened here: src/main.js:40-85
```

What you should notice:

* this is block-focused
* it is about provenance of a specific region
* it is ideal when a few lines look strange or surprising

### Search

Before this exercise, make sure `entire login` already worked in Terminal. `search` uses indexed Checkpoint history, so give Entire a moment to index your pushed Checkpoints before trying these queries.

Start with a very specific query:

```text theme={null}
search past work for duplicate validation
```

If that is too narrow, try:

```text theme={null}
search past work for duplicate bug detection
```

Then try:

```text theme={null}
search past work for severity badges
```

Only after that, try the broader question:

```text theme={null}
have we done this before with persistence?
```

What you should notice:

* it searches [Checkpoints](/cli/checkpoints), not just files
* it helps with memory across [sessions](/glossary#session)
* it works best with concrete nouns and feature phrases, not broad words like `persistence` by itself
* the best demo queries are feature names, validation behavior, bug text, file names, or ticket IDs

### Session Handoff

Start with the summary request:

```text theme={null}
hand off this session
```

Or:

```text theme={null}
hand off the codex session
```

What you should notice:

* the skill creates a concise handoff summary so another agent can pick up the next task
* it is especially useful after a long build or debug session

For a more intentional transfer, use a two-step workflow. This example hands work to Claude Code, but you can replace Claude Code with any supported agent.

Step 1: generate the handoff summary in your current agent:

```text theme={null}
Prepare a handoff for Claude Code. The next task is to add edit and delete actions for bug notes. Preserve the current vanilla JS structure and localStorage behavior.
```

Step 2: open the receiving agent and paste the handoff plus an explicit task brief:

```text theme={null}
Continue this project from the handoff below.

Your next task:
- add edit and delete actions for bug notes
- keep the app in plain vanilla JS
- preserve the existing localStorage behavior
- keep the code simple and readable
- make one commit when the feature is complete

Handoff:
[paste the handoff summary here]
```

This is the best tutorial pattern because it shows that:

* `session-handoff` packages the important context
* the user still controls the next objective
* the receiving agent gets both history and clear execution instructions

If you want the receiving agent to stay narrowly scoped, make the brief even more explicit:

```text theme={null}
Continue from this handoff.
Only do the next task: add delete support for bug notes.
Do not add tests or extra refactors.
Make one commit when done.

Handoff:
[paste handoff]
```

## Why Skills Help

In this tutorial, Skill prompting is stronger than normal prompting because it gives the agent a defined workflow instead of a vague question.

<AccordionGroup>
  <Accordion title="Explain code intent">
    `/explain src/main.js` is stronger than `Why is this code here?` because it tells the agent to investigate code intent with transcript-aware context.
  </Accordion>

  <Accordion title="Trace a code block">
    `what happened here: src/main.js:40-85` is stronger than `Why is this weird?` because it points to a specific block and asks for provenance.
  </Accordion>

  <Accordion title="Search prior work">
    `search past work for duplicate bug detection` is stronger than `Have we done this before?` because it gives the search Skill specific feature language to match.
  </Accordion>

  <Accordion title="Hand work off">
    `Prepare a handoff for Claude Code...` is stronger than `summarize this` because it names the receiving agent, the next task, and the key constraints.
  </Accordion>
</AccordionGroup>

The general pattern is simple:

* Normal prompting asks the agent to guess the method
* Skill prompting gives the agent both the goal and the method

That usually leads to better structure, better use of Entire history, and less back-and-forth.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Skills are installed but do not trigger">
    Make sure:

    * the repo is installed in the right discovery path for your tool
    * the tool supports Skills or plugins
    * you are using prompts that clearly invoke the skill
  </Accordion>

  <Accordion title="`search` or `explain` returns no transcript">
    Possible reasons:

    * the code was created outside an Entire-tracked session
    * you have not committed yet, or have not pushed yet for `search`
    * you have not enabled Entire in the repo
    * authentication or Checkpoint configuration is incomplete
  </Accordion>

  <Accordion title="`search` works but feels underwhelming">
    That usually means one of these:

    * the query is too broad, like `persistence` or `auth`
    * there are not enough prior sessions yet
    * your earlier sessions did not use distinctive feature language

    To improve results:

    * use more specific queries like `duplicate bug detection` or `severity badge filter`
    * build 2 or 3 distinct features before testing the skill
    * commit and push after each feature so the history is easier to traverse and index
  </Accordion>

  <Accordion title="`session-handoff` is not useful yet">
    That usually means the project has too little tracked history. Do another meaningful work session, then commit it.
  </Accordion>
</AccordionGroup>