---
name: first-agent
description: Help an AI beginner complete their first real file inspection in an explicitly selected workspace, distinguish tool evidence from chat, and save a verifiable directory report. Use for the first level of the newbieskill learning path.
---

# Meet your Agent: your first real action

Turn “can this AI actually see my project?” into an answer backed by a real tool call.
This is level 1 of the newbieskill main quest, not a general installation or system administration tool.

## What the learner receives

- A list of the visible items directly inside the selected folder.
- `workspace-report.json`, a machine-readable inventory of that folder.
- A plain-language explanation of what was inspected, what was skipped, and what has not been tested.
- The next task: create and revise a small file with `first-task`.

## Start from the learner's situation

If no Agent is installed, direct the learner to the installation instructions on the learning page.
Ask them to complete account login and open a folder in the Agent before continuing.
Do not invent installation success or assume access to their desktop from an ordinary chat window.
If they already opened an Agent in a folder, use that folder instead of repeating setup.

## The only required input

An explicitly selected working folder is sufficient.
Ask “Which folder should I inspect?” if the current workspace is unknown.
Do not request an API key, email address, or the contents of private documents.
Do not change the user's Agent settings or install another tool to complete this lesson.

## Workflow

1. Identify the current workspace with an available file or shell tool.
2. Tell the learner the folder you will inspect. Resolve an ambiguous path before continuing.
3. Read `references/inspection-boundaries.md` when deciding what may appear in the report.
4. Run the bundled script using Node.js 18 or newer:

   ```text
   node <installed-skill-directory>/scripts/inspect-workspace.mjs <selected-folder> <report-file>
   ```

5. Put the report in a task output folder chosen by the learner, outside the folder being listed when practical.
6. Read the actual generated JSON. Summarize its items and skipped-item counts without pretending to have opened their contents.
7. Explain that this run inspected one selected folder, not the whole computer. Other locations require their own access and authorization.
8. Give the actual report path and continue to the next lesson if the learner wants to create a file.

Paths containing spaces must be passed as separate, correctly quoted command arguments.
Resolve the script relative to this installed Skill, not relative to the learner's project.
If Node.js is unavailable, use the Agent's existing directory-listing tool and save the same report fields.
Clearly identify that alternative; do not say the bundled script ran.

## Read the result correctly

`items` contains names and types observed in this run.
`skipped` reports hidden files, sensitive filenames and symbolic links without exposing their names.
`scope` is always `direct-children-only`; nested folders have not been recursively inspected.
An empty `items` array can be a correct result for an empty folder.
The report does not prove the Agent can edit files, run every command, or access other folders.
Those are separate tasks with separate evidence.

## Failure and recovery

- Missing folder: explain the failed path and ask for a real folder; do not create it silently.
- File supplied instead of a folder: ask for its containing folder.
- Permission denied: ask for a folder already accessible to the Agent; do not elevate permissions automatically.
- Existing report destination: choose a new filename or ask before replacing it; the script refuses overwrite.
- Tool unavailable: explain what is missing and stop before claiming an inventory.
- Only hidden or sensitive items: explain the omission policy, not “the directory contains no files”.

## Quality boundaries

- Never infer a folder listing from the conversation or an example.
- Never open `.env`, credentials, browser profiles or private documents for this lesson.
- Do not follow symbolic links or recurse outside the selected folder.
- Do not scan a home directory or a whole drive merely to find an example project.
- Preserve all existing files. This lesson's sole write is its explicitly named new report.
- Distinguish what a tool actually did from what the Agent might be able to do later.
- Explain the result in familiar words; do not require the learner to understand JSON.

## Self-tests and failure criteria

Run `node scripts/self-test.mjs` from this package.
It executes the inspection script against fresh temporary folders rather than rechecking a saved report.

1. Normal material: two visible files and one folder produce exactly three named items; hidden and sensitive files are omitted.
2. Different material: a Unicode filename and an empty directory retain their exact names; counts match independently observed contents.
3. Missing material: a nonexistent folder fails, produces no report and explains the missing-folder error.
4. Existing output: a second write to the same destination fails and preserves the original bytes.

Any mismatch, unexpected write, missing error or invented item is a failure.
Keep outputs, executable commands and results in `demo/`; a test pass establishes these cases only.

## Learning route

Main quest: `/path/first-agent/`.
Next: `/path/first-task/` — create a file, then make a precise change in the same conversation.
This Skill can also support later project-context and troubleshooting tasks.

## Rights

Original newbieskill workflow and scripts. See `LICENSE` for reuse terms.