# Tutorial Check

> |

- **Type:** Skill
- **Install:** `agentstack add skill-bearded-illirian-trailmark-tutorial-check`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [bearded-illirian](https://agentstack.voostack.com/s/bearded-illirian)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [bearded-illirian](https://github.com/bearded-illirian)
- **Source:** https://github.com/bearded-illirian/trailmark/tree/main/aihub/.claude/skills/tutorial-check

## Install

```sh
agentstack add skill-bearded-illirian-trailmark-tutorial-check
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Tutorial-Check Protocol

Homework validator for the QUICKSTART walkthrough. Runs 5 checks against
the user's workspace to confirm they set up their first real project
correctly. Reports ✅/❌ per step with a one-line remediation hint.

Read-only — never modifies files or DB.

---

## When to invoke

After the user completes the 5-step homework in `docs/QUICKSTART.md` § 5:

1. Create a project named `my-tutorial`
2. Start a task in that project (`/go-start` + `/go-fast`)
3. Approve the full chain (ok, ok, 1)
4. Verify 5 artifact files exist in `tasks/log/{slug}/`
5. Confirm the task appears in Flow UI

Then the user runs `/tutorial-check` and gets pass/fail per step.

---

## Step 0 — Detect workspace root

Find the workspace root by walking up from CWD until we find `framework.yml`
or `manifest.yml` at the same level. If none found within 5 levels — abort:

```
⚠️ Not inside a framework workspace. Run this from anywhere inside your
   framework directory (where framework.yml lives).
```

Set `{workspace_root}` for all subsequent checks.

---

## Step 1 — Run the 5 checks

Each check is independent — a failure in one doesn't skip the others.

### Check 1: Project `my-tutorial` created

```bash
test -d "{workspace_root}/projects/my-tutorial" && D1=✅ || D1=❌
grep -q "id: my-tutorial" "{workspace_root}/aihub/projects.yml" && D2=✅ || D2=❌
test -L "{workspace_root}/projects/my-tutorial/.claude/skills" && D3=✅ || D3=❌
```

Pass = D1 AND D2 AND D3.
Remediation: `bash bin/new-project my-tutorial`

### Check 2: Task started in that project

```bash
COUNT=$(sqlite3 "{workspace_root}/tasks/routing.db" \
  "SELECT COUNT(*) FROM artifacts WHERE project = 'my-tutorial'")
test "$COUNT" -gt 0 && CHECK2=✅ || CHECK2=❌
```

Pass = at least one artifact row exists.
Remediation: `cd projects/my-tutorial && claude`, then `/go-start` and `/go-fast "..."`.

### Check 3: Chain approved (plan-first artifact exists)

```bash
COUNT=$(sqlite3 "{workspace_root}/tasks/routing.db" \
  "SELECT COUNT(*) FROM task_artifacts ta
   JOIN artifacts a ON ta.task_id = a.id
   WHERE a.project = 'my-tutorial' AND ta.artifact_type = 'plan-first'")
test "$COUNT" -gt 0 && CHECK3=✅ || CHECK3=❌
```

Pass = plan-first ran, meaning user approved flow-first + library-first gates.
Remediation: rerun `/go-fast` and reply `ok`/`ok`/`1` at each gate.

### Check 4: 5 artifact files exist on disk

For each task folder under `{workspace_root}/tasks/log/` where task belongs to
project `my-tutorial`, count files matching these 5 patterns:

- `flow-first-*.md`
- `library-first-*.md`
- `plan-first-*.md`
- `report-*.md`
- `user-note-*.md`

Pass = all 5 files present.
Remediation: chain likely errored mid-execution. Check for empty/missing artifacts, rerun /go-fast.

### Check 5: Task visible in Flow UI

Flow UI reads from `routing.db`. If the task registered → it's visible.

```bash
COUNT=$(sqlite3 "{workspace_root}/tasks/routing.db" \
  "SELECT COUNT(*) FROM artifacts
   WHERE project = 'my-tutorial'
   AND datetime(created_at) > datetime('now', '-24 hours')")
test "$COUNT" -gt 0 && CHECK5=✅ || CHECK5=❌
```

Pass = recent activity registered in DB → Flow UI will show it.
Remediation: check `sqlite3 tasks/routing.db "SELECT * FROM artifacts WHERE project='my-tutorial'"`. If empty — task never registered. Rerun `/go-start`.

### Check 6 (optional): Self-audit — tutorial-check invocation logged

```bash
COUNT=$(sqlite3 "{workspace_root}/tasks/routing.db" \
  "SELECT COUNT(*) FROM skill_invocations
   WHERE skill_name = 'tutorial-check'
   AND datetime(invoked_at) > datetime('now', '-5 minutes')")
test "$COUNT" -gt 0 && CHECK6=✅ || CHECK6=⚠️
```

Not required for pass — informational only.

---

## Step 2 — Report

Output a compact table:

```
╭──────────────────────────────────────────────────────────╮
│  Tutorial-Check Report                                   │
├──────────────────────────────────────────────────────────┤
│  ✅ 1. Project my-tutorial created                       │
│  ✅ 2. Task started                                      │
│  ❌ 3. Chain approved       — plan-first missing         │
│  ❌ 4. Artifacts exist      — 3/5 found                  │
│  ✅ 5. Task in Flow UI                                   │
│  ✅ 6. Self-audit (invocation logged)                    │
├──────────────────────────────────────────────────────────┤
│  Score: 3/5 core checks + 1 self-audit                   │
│  Status: ❌ Homework incomplete                          │
╰──────────────────────────────────────────────────────────╯
```

If all 5 pass — congratulate the user and point at CONCEPTS.md +
next-step suggestion (try `/go-fast` on a real change).

---

## Step 3 — Exit

Don't invoke other skills. Don't modify files. Report only.

---

## Anti-patterns

### ❌ Auto-fixing failures

The skill diagnoses; it doesn't repair. Auto-remediation hides the learning
opportunity — the user needs to see what step failed and do it themselves.

**Rule:** report only. Suggest commands, don't run them.

### ❌ Running on non-my-tutorial projects

Someone runs `/tutorial-check` in a real production project — the skill
reports 5 ❌ because it hardcodes `my-tutorial`. Confusing.

**Rule:** the report explicitly names `my-tutorial` and mentions
QUICKSTART.md § 5 so context is unambiguous.

### ❌ Silent failure on missing DB

If `tasks/routing.db` doesn't exist yet (fresh workspace, never ran
init-demo or any task) — each SQL check will error, and users see raw
sqlite errors.

**Rule:** Step 0 detects workspace root; if `tasks/routing.db` missing,
show explicit "Workspace not initialized — run `bash bin/init` first"
message.

### ❌ Modifying routing.db during check

Read-only guarantee. Never `INSERT`, never `UPDATE`, never `DELETE`
except the Step 99 self-invocation log.

---

## Related skills

- **plan-first** — the skill that produces the artifact Check 3 verifies
- **flow-first**, **library-first** — sibling skills the tutorial exercises
- **ship-first** — closes tasks the tutorial creates
- **check-first** — sibling coverage validator with similar report-and-exit shape

---

## Step 99 — Log invocation

```bash
sqlite3 "{workspace_root}/tasks/routing.db" \
  "INSERT INTO skill_invocations (task_id, block_num, skill_name, invoked_at)
   VALUES ('tutorial-check', NULL, 'tutorial-check', datetime('now'))" 2>/dev/null || true
```

The `|| true` guard prevents failure if DB is missing or table doesn't
exist yet (fresh workspace).

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [bearded-illirian](https://github.com/bearded-illirian)
- **Source:** [bearded-illirian/trailmark](https://github.com/bearded-illirian/trailmark)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-bearded-illirian-trailmark-tutorial-check
- Seller: https://agentstack.voostack.com/s/bearded-illirian
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.