Skills

Skills are reusable prompts that give the agent specialised capabilities without requiring code. Drop a markdown file in .nano_claude/skills/, define a trigger, and the agent picks it up. Two built-in skills ship out of the box — /commit and /review — so you can see the pattern before writing your own.

The skill system lives in a-mini/skill/:

• loader.py — parse markdown frontmatter into SkillDef.
• builtin.py — /commit and /review.
• executor.py — run a skill inline or as a forked sub-agent.
• tools.py — Skill and SkillList tools.

a-full has the same model with TypeScript types. The vocabulary is identical.

Built-in skills

Trigger	Description
/commit	Review staged git changes and create a structured commit.
/review [PR]	Review code or PR diff with structured feedback.

Use them inside a session:

You: /commit
AI: [reads staged changes, drafts a message, runs git commit]

Skill anatomy

A skill is a markdown file with YAML-ish frontmatter:

---
name: deploy
description: Deploy the workspace to a target environment.
triggers: [/deploy]
allowed-tools: [Bash, Read]
when_to_use: When the user wants to deploy a version to an environment.
argument-hint: [env] [version]
arguments: [env, version]
context: inline
---

Deploy version $VERSION to the $ENV environment.

Steps:
1. Read .env to confirm credentials.
2. Run the build command for the framework.
3. Push to the target.
4. Verify the deploy is healthy.

Full args: $ARGUMENTS

The frontmatter fields:

Argument substitution

Two patterns:

• $ARGUMENTS — the full raw argument string after the trigger.
• $ARG_NAME — positional substitution by named argument. The first word goes to the first name in arguments, etc.

Missing args become empty strings (the skill should handle that gracefully — e.g., default to staging when $ENV is empty).

---
name: hotfix
arguments: [issue, branch]
---
Fix issue $ISSUE on branch $BRANCH.

User runs: /hotfix 123 release-2.1. The prompt substitutes to "Fix issue 123 on branch release-2.1.".

Search paths

Skills are loaded from two paths, in priority order:

./.nano_claude/skills/     # project-level (overrides user-level)
~/.nano_claude/skills/     # user-level

Built-in skills (from skill/builtin.py) are the fallback if neither path defines a matching name.

Inline vs fork

inline skills run in the current conversation. They're cheap (no new agent spawn) and their results are visible in the same thread. Use for short, single-purpose prompts.

fork skills run as sub-agents — separate conversation history, optional model override, optional restricted tools. Use for complex tasks where you don't want the skill's reasoning to clutter the main conversation.

---
name: lint-and-fix
context: fork
model: claude-haiku-4-5-20251001
tools: [Read, Edit, Bash]
---
Run the linter and fix every reported issue.

The fork sub-agent reports back with a summary; the main agent's history stays clean.

Listing and invoking

Inside a REPL session:

/skills              # list all skills with triggers, source, when_to_use
/deploy staging 2.1.0   # invoke a skill via its trigger

From the agent's tool surface (when the model decides to use a skill itself):

{ "tool": "Skill", "input": { "name": "deploy", "args": "staging 2.1.0" } }

SkillList returns the same listing as /skills — the agent uses it to discover available skills.

Writing a skill — checklist

A good skill:

• Has a clear, narrow purpose. Don't write a "do everything" skill.
• Lists allowed-tools if the skill should be sandboxed (e.g., a "review" skill that should never modify files restricts to Read + Grep).
• Documents arguments in argument-hint so users know how to invoke.
• Includes when_to_use for the agent to auto-invoke at the right moment.
• Uses fork when the skill produces noisy intermediate output you don't want in the main thread.

Examples

A code review skill that's read-only:

---
name: review-staged
description: Review staged git changes and report issues.
triggers: [/review-staged]
tools: [Bash, Read, Grep]
context: inline
---
Run `git diff --staged` and review the changes for:
- Correctness and logic errors
- Security issues
- Style violations

Categorize findings as Critical / Warning / Suggestion. Be concise.

A scaffolding skill that forks:

---
name: scaffold-page
description: Create a new page with route + component + tests.
triggers: [/scaffold-page]
arguments: [name]
context: fork
---
Create a new page named "$NAME":
1. Add `src/pages/$NAME.tsx` with a default export.
2. Wire it into the router.
3. Create `src/pages/__tests__/$NAME.test.tsx` with a smoke test.
4. Run the existing test suite to ensure nothing broke.

Report file paths created.

Where skills live in Vibe Studio

Vibe Studio workspaces include a .nano_claude/skills/ folder for project-level skills. Drop markdown files there and the running a-full process picks them up on the next agent turn (no restart required — skills are re-scanned on each turn).

User-level skills (in ~/.nano_claude/skills/) follow the builder across all their workspaces. Useful for personal patterns like /commit-with-jira that you always use.