---
title: Skills & Hooks
description: Teaching agents how to work with Sibyl
---

# Skills & Hooks

Sibyl's power comes from two complementary systems: **Skills** teach agents structured workflows,
and **Hooks** inject knowledge automatically. Together, they give Claude structured workflows and
automatic context from your knowledge graph.

## The Two Systems

| System     | Purpose         | When it Runs                | User Action |
| ---------- | --------------- | --------------------------- | ----------- |
| **Skills** | Teach workflows | On `/skill-name` invocation | Manual      |
| **Hooks**  | Inject context  | Automatically on triggers   | None needed |

Think of it this way:

- **Skills** = Training manual (agent reads when invoked)
- **Hooks** = Invisible assistant (works behind the scenes)

---

## Hooks: Automatic Context

Hooks are the magic that makes Sibyl invisible. They run automatically at specific moments:

### SessionStart Hook

**Trigger:** When you start a new Claude Code session

**What it does:**

- Packages a wake-up context bundle (`sibyl session bundle`)
- Loads your active tasks (status: `doing`, `blocked`, `review`)
- Shows your project context
- Reminds the agent about the memory loop

```
┌─────────────────────────────────────────────────────────────┐
│  SESSION START                                               │
│                                                              │
│  Active Tasks:                                               │
│  • task_abc123 [doing] Fix authentication token refresh      │
│  • task_def456 [blocked] Add rate limiting (waiting on API)  │
│                                                              │
│  Project: Authentication System (proj_auth)                  │
│  Remember: Use `sibyl add` to capture learnings!             │
└─────────────────────────────────────────────────────────────┘
```

### What about per-prompt injection?

An earlier `UserPromptSubmit` hook ran on every prompt, generated a semantic search query with
Haiku, and injected a context pack inline. We removed it. The hook gave agents just-enough
sibyl-shaped context to skip invoking the skill or reaching for the CLI on their own, which defeated
the point of the skill. Agents now drive recall and capture explicitly via `sibyl recall`,
`sibyl context pack`, `sibyl remember`, and `sibyl reflect`. The SessionStart bundle remains as a
one-time wake-up nudge.

### Installing Hooks

```bash
# Install hooks to ~/.claude/hooks/sibyl
moon run hooks:install

# Restart Claude Code to activate
```

### Uninstalling Hooks

```bash
moon run hooks:uninstall
# Or: rm -rf ~/.claude/hooks/sibyl
```

---

## Skills: Teaching Workflows

Skills are markdown documents that teach Claude specific workflows. Invoke them with slash commands:

### sibyl

The unified skill for all Sibyl operations:

```
/sibyl
```

**Teaches Claude:**

- CLI command syntax and patterns
- Search-first workflow
- Task lifecycle management
- Knowledge capture best practices
- Project audits and sprint planning
- Common pitfalls to avoid

## Skill File Format

### SKILL.md Structure

```markdown
---
name: skill-name
description: Brief description of what the skill provides
allowed-tools: Bash, Grep, Glob, Read
---

# Skill Title

Detailed content teaching Claude how to use this skill...

## Quick Reference

Command tables, examples...

## Workflows

Step-by-step processes...

## Best Practices

Guidelines and patterns...
```

### Frontmatter

```yaml
---
name: sibyl
description: Graph-RAG knowledge system with CLI interface
allowed-tools: Bash, Grep, Glob, Read
---
```

| Field           | Description                               |
| --------------- | ----------------------------------------- |
| `name`          | Skill identifier (must be unique)         |
| `description`   | Brief description for skill discovery     |
| `allowed-tools` | Tools Claude can use when skill is active |

## Installing Skills

Install the stable `/sibyl` loader skill with:

```bash
sibyl skill install
```

The loader points agents back to the installed CLI. Load the version-matched core guidance with:

```bash
sibyl skill get core
```

Additional bundled markdown packs are available with:

```bash
sibyl skill list
sibyl skill get workflows
sibyl skill get examples
```

Hooks are separate from skills because they execute automatically on prompt and session events.
Install hooks only when that automation is explicitly desired.

### Manual Installation

```bash
# Copy skill directory
cp -r skills/sibyl ~/.claude/skills/

# Or create symlink
ln -s /path/to/sibyl/skills/sibyl ~/.claude/skills/
```

## Skill Location

Skills are stored in:

```
~/.claude/skills/
└── sibyl/
    └── SKILL.md
```

`SKILL.md` is a small loader. The full version-matched guidance is served from the installed CLI
with `sibyl skill get core` and related pack commands.

Codex installs the same skill to:

```
~/.codex/skills/
└── sibyl/
```

## Creating Custom Skills

### 1. Create Directory

```bash
mkdir -p skills/my-skill
```

### 2. Create SKILL.md

```markdown
---
name: my-skill
description: Custom skill for specific workflow
allowed-tools: Bash
---

# My Custom Skill

## Purpose

Explain what this skill helps Claude do...

## Commands

### Primary Command

\`\`\`bash command example \`\`\`

### Secondary Command

\`\`\`bash another command \`\`\`

## Workflows

### Common Workflow

1. First step
2. Second step
3. Third step

## Best Practices

- Guideline one
- Guideline two
```

### 3. Install

```bash
cp -r skills/my-skill ~/.claude/skills/
```

### 4. Use

```
/my-skill
```

## Skill Design Patterns

### Command Reference Pattern

Provide clear command tables:

```markdown
## CLI Reference

| Command                | Description     |
| ---------------------- | --------------- |
| `sibyl search "query"` | Semantic search |
| `sibyl task list`      | List tasks      |
```

### Workflow Pattern

Describe step-by-step processes:

```markdown
## Task Workflow

1. **Find Tasks** \`\`\`bash sibyl task list --status todo \`\`\`

2. **Start Working** \`\`\`bash sibyl task start task_xyz \`\`\`

3. **Complete** \`\`\`bash sibyl task complete task_xyz --learnings "..." \`\`\`
```

### Common Mistakes Pattern

Help Claude avoid errors:

```markdown
## Common Pitfalls

| Wrong                    | Correct                           |
| ------------------------ | --------------------------------- |
| `sibyl task add "..."`   | `sibyl task create --title "..."` |
| `sibyl task list --todo` | `sibyl task list --status todo`   |
```

### Memory Loop Pattern

Teach the recall, act, remember, reflect cycle:

```markdown
## The Memory Loop

\`\`\`

1. RECALL -> sibyl recall "topic"
2. ACT -> sibyl task start <id>
3. REMEMBER -> sibyl remember "Title" "What, why, how"
4. REFLECT -> sibyl reflect --persist --review \`\`\`
```

## Skill Content Guidelines

### Be Specific

```markdown
# GOOD

sibyl task list --status todo,doing,blocked

# LESS GOOD

sibyl task list (various options available)
```

### Show Examples

```markdown
# Search for patterns

sibyl search "authentication" --type pattern

# Result:

# pattern_abc OAuth callback handling 0.95

# pattern_xyz JWT token refresh 0.89
```

### Include Error Handling

```markdown
## Troubleshooting

### Connection Error

If you see "connection refused":

1. Check server is running: `sibyl health`
2. Verify URL in config
```

### Provide Context

```markdown
## When to Use

Use `episode` type for:

- Debugging discoveries
- One-time learnings
- Context-specific insights

Use `pattern` type for:

- Reusable approaches
- Best practices
- Standard solutions
```

## Advanced Skill Features

### Tool Restrictions

Limit tools for safety:

```yaml
allowed-tools: Bash, Read
# Claude can only use Bash and Read when this skill is active
```

### Conditional Guidance

```markdown
## Project-Specific Commands

### If Working in `auth` Project

\`\`\`bash sibyl task list --project proj_auth --status todo \`\`\`

### If Working in `api` Project

\`\`\`bash sibyl task list --project proj_api --status todo \`\`\`
```

### Integration with Other Skills

```markdown
## Related Skills

- `/sibyl` - For all Sibyl operations (also handles auditing)
- `/git-workflow` - For commit patterns
```

## Example: Complete Skill

```markdown
---
name: sibyl-code-review
description: Code review workflow using Sibyl knowledge graph
allowed-tools: Bash, Read, Grep
---

# Sibyl Code Review Skill

Guide Claude through code review using Sibyl's knowledge graph.

## Purpose

Use Sibyl to:

- Find relevant patterns for the code being reviewed
- Check for applicable rules
- Track review tasks

## Quick Start

\`\`\`bash

# 1. Search for relevant patterns

sibyl search "code being reviewed" --type pattern

# 2. Check applicable rules

sibyl entity list --type rule

# 3. Start review task

sibyl task start task_review_xyz \`\`\`

## Review Workflow

### 1. Prepare

\`\`\`bash

# Find patterns for the domain

sibyl search "domain of code" --type pattern

# Check rules

sibyl entity list --type rule --category "domain" \`\`\`

### 2. Review

Check code against:

- Discovered patterns
- Applicable rules
- Past learnings (episodes)

### 3. Document

\`\`\`bash

# Capture new discoveries

sibyl add "Review finding" "What was discovered..."

# Complete review task

sibyl task complete task_xyz --learnings "Key insights from review..." \`\`\`

## Best Practices

- Search before reviewing
- Reference specific patterns in feedback
- Capture reusable insights
- Complete review tasks with learnings
```

## Debugging Skills

### Skill Not Found

1. Check file location: `~/.claude/skills/skill-name/SKILL.md`
2. Verify frontmatter syntax
3. Restart Claude Code

### Skill Not Working as Expected

1. Review skill content for clarity
2. Add more specific examples
3. Include command output examples

### Claude Ignoring Skill Guidance

1. Make instructions more explicit
2. Use numbered steps
3. Add "IMPORTANT" markers for critical points

## Next Steps

- [The Memory Loop](./memory-loop.md) - The cycle hooks support
- [Claude Code Integration](./claude-code.md) - Full MCP setup
- [Agent Collaboration](./agent-collaboration.md) - Shared-assistant patterns
- [Capturing Knowledge](./capturing-knowledge.md) - What to teach Claude
