Skills

// Level 1: List all skills (metadata only)
const skills = yield* skillService.listSkills();
// Returns: [{ name: "deep-research", description: "...", path: "..." }]

// Level 2: Load core skill content (when skill is invoked)
const skill = yield* skillService.loadSkill("deep-research");
// Returns: { metadata, core: "# Deep Research\n...", sections: Map }

// Level 3: Load specific sections (on-demand)
const section = yield* skillService.loadSkillSection(
  "deep-research",
  "references/verification-patterns.md"
);

---
name: deep-research
description: Conduct comprehensive multi-source research for complex questions. Use when the user asks a complicated question requiring multiple sources, in-depth analysis, cross-referencing, or expert-level research reports.
---

# Deep Research

Autonomous research agent for complex, multi-source questions...

## When to Activate

- Complex questions requiring multiple sources
- Topics with conflicting or nuanced information
...

jazz
> Research the impact of AI on healthcare costs in the next decade

# Agent sees "deep-research" skill in its context
# Decides it matches the task
# Loads the skill and follows its methodology

> Use the code-review skill to review the last commit

jazz /skills

---
name: tech-digest
schedule: "0 8 * * *"
skills:
  - deep-research
  - digest
---

Create a daily digest of AI and tech news from the last 24 hours.

## Research Pipeline

Execute these phases sequentially. Each phase builds on the previous.

## Quality Checklist

Before delivering final report:

- [ ] All sub-questions addressed
- [ ] Every claim has citation
- [ ] Contradictions acknowledged
- [ ] Confidence levels stated
- [ ] Limitations documented
- [ ] Sources are diverse and credible
- [ ] Recency appropriate for topic
- [ ] Sources used are shown

## Anti-Patterns to Avoid

- ❌ Single-source conclusions for complex topics
- ❌ Ignoring contradictory evidence
- ❌ Treating all sources as equally credible
- ❌ Stopping after first search round without verification
- ❌ Presenting uncertain claims as facts

## Workflow

1. **Understand context**: What is the change for?
2. **Read the diff**: What actually changed?
3. **Collect all issues—never stop at first error**
4. **Gather usage context**: 
   - Surrounding code
   - Call sites & usage
   - Integration points
   - Tests
5. **Run checklist**: Logic, security, performance, style, tests
6. **Prioritize**: Critical → must fix; Suggestion → consider
7. **Respond**: Summary + categorized comments + what was done well

### Correctness & Logic
- [ ] Does it do what it claims? Edge cases?
- [ ] Off-by-one, null/undefined, empty inputs?
- [ ] Error handling: failures caught and handled?
- [ ] Concurrency: races, deadlocks, shared state?

### Security
- [ ] User input validated and sanitized?
- [ ] No secrets in code or logs?
- [ ] Auth/authz checked where needed?

## Code Review: [PR/File name]

### Summary
[Overall assessment]

### Well done
- [Specific things done well]

### Critical (must address)
- **[Location]** [Issue]. [Fix suggestion.]

### Suggestions (consider)
- **[Location]** [Optional improvement.]

npx skills add

mkdir -p ~/.jazz/skills/my-skill
cd ~/.jazz/skills/my-skill
# Create SKILL.md

mkdir -p ./skills/my-skill
cd ./skills/my-skill  
# Create SKILL.md

mkdir -p ~/.agents/skills/my-skill
cd ~/.agents/skills/my-skill
# Create SKILL.md

---
name: my-skill
description: When to use this skill and what it does
---

# Skill Name

One-sentence purpose.

## When to Activate

- Trigger condition 1
- Trigger condition 2

## Workflow

1. Step 1
2. Step 2
3. Step 3

## Output Format

[Specify exact format]

## Quality Checklist

- [ ] Requirement 1
- [ ] Requirement 2

my-skill/
  SKILL.md              # Core instructions
  references/
    examples.md         # Code examples
    templates.md        # Output templates
  workflows/
    advanced.md         # Advanced workflows

For advanced usage, see [workflows/advanced.md]

For deep analysis, load the `deep-research` skill.

jazz
> Use the skill-creator skill to help me build a skill for API documentation

description: Use when the user asks to "research", "investigate", "deep dive", or requests comprehensive analysis with multiple sources.

## Phase 1: Decomposition
[Clear instructions]

## Phase 2: Execution
[Clear instructions]

## Phase 3: Verification
[Clear instructions]

## Report Structure

```markdown
# Title

## Executive Summary
[2-3 sentences]

## Key Findings
[Findings with citations]

## Sources
[Complete source list]

### Quality checklists

Provide verification checklists:

```markdown
Before delivering:

- [ ] All requirements met
- [ ] Format matches specification
- [ ] Sources cited

## Anti-Patterns to Avoid

- ❌ Stopping after first attempt
- ❌ Skipping verification
- ❌ Omitting sources

import { SkillServiceTag } from "@/core/skills/skill-service";

// List all skills
const skills = yield* SkillServiceTag.pipe(
  Effect.flatMap((service) => service.listSkills())
);

// Load a skill
const skill = yield* SkillServiceTag.pipe(
  Effect.flatMap((service) => service.loadSkill("deep-research"))
);

// Load a section
const section = yield* SkillServiceTag.pipe(
  Effect.flatMap((service) => 
    service.loadSkillSection("deep-research", "references/examples.md")
  )
);