nagent
Launch a new bb worker thread with the right project, model, worktree, and task brief. Use for nagent, launching a bb session, or a standalone bb agent. Covers thread creation; use bb-cli for managing existing threads.
Install / Use
npx skills add davidondrej/skills --skill nagentInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
AI & Machine LearningSupported Platforms
Tags
Our assessment of nagent
nagent scores 94/100 on our quality scale, 188th of 947 AI & Machine Learning skills we index (top 20%).
Its SKILL.md is 6.5 KB long, well organised into 11 sections with 5 code examples: a thorough specification that gives an agent plenty to work with.
With 4,079 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so nagent is actively maintained.
- Our last check on 2026-11-16 could not reach the source (HTTP 404); it may have been moved or deleted.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit β read the skill file before letting an agent act on it.
nagent compared with similar skills
All 4 of these similar skills score higher than nagent; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| nagent (this skill)by davidondrej | 94 | 4.1k | 53d ago | SKILL.md |
| claude-memby thedotmack | 100 | 117.6k | today | CLAUDE.md |
| Understand-Anythingby Egonex-AI | 100 | 92.8k | 1d ago | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.8k | today | CLAUDE.md |
| CowAgentby zhayujie | 100 | 48.0k | today | CLAUDE.md |
Frequently asked questions
- How do I install nagent?
- Run
npx skills add davidondrej/skills --skill nagent. The install tabs above show the steps for each supported agent. - Which AI agents does nagent work with?
- It is written for OpenAI Codex, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is nagent safe to use?
- It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is nagent still maintained?
- The repository was last updated about 2 months ago, so nagent is actively maintained.
Skill content
View source on GitHubname: nagent description: Launch a new bb worker thread with the right project, model, worktree, and task brief. Use for nagent, launching a bb session, or a standalone bb agent. Covers thread creation; use bb-cli for managing existing threads.
nagent
Read this before bb thread spawn. Use bb-cli for other thread operations.
Defaults
Use Codex gpt-5.6-sol, reasoning high, service tier fast ("GPT 5.6 Sol High Fast"). Use xhigh for larger refactors. The user's explicit choices override these defaults.
For a different requested model, use its catalog defaultReasoningEffort when unspecified, and enable fast only when asked. Do not infer a higher reasoning level from the model name.
Prefer bare bb; "$BB_CLI" is also valid when set.
Look Up the Target
bb project list --json
bb provider list --json
bb provider models <provider-id> --json
- Project: Match the name and confirm
sources[].pathis the requested repository. Always pass--project; never hardcode an ID. - Provider: Look it up. Common mappings are Cursor CLI β
acp-cursor, Codex/ChatGPT subscription βcodex, and Claude Code βclaude-code. Grok via Cursor is notacp-grok, which is Grok Build. - Model: Use the catalog ID. Match both
displayNameandsupportedReasoningEfforts[].description; model IDs, reasoning labels, and service tiers are separate.
For Cursor/Grok or Codex Max naming traps, read provider details. Verify examples against the current catalog; do not guess IDs or substitute a different provider.
Pi Agent: billing safety
--provider pi selects the harness; the full --model provider/model selects the inference and billing route. ChatGPT subscription example:
--provider pi --model openai-codex/gpt-6-astra --reasoning-level xhigh
Query Pi's catalog on the target --machine or --environment. openai-codex uses the ChatGPT subscription; OpenRouter and Vercel AI Gateway bill separately. Never substitute routes without the user's approval; stop if unavailable. After spawning, verify the full model ID and reasoning in the client/turn/requested execution metadata, not just the display name.
Permission Checks
The user's investigation/build workers default to full. A child cannot exceed the parent's permission mode, so verify the parent before requesting it and the child after spawning.
Run the bundled script relative to this skill's directory:
scripts/permission-mode.sh "$BB_THREAD_ID"
For a full worker, this must print full. Otherwise, stop and report that the requested mode is unavailable under the parent's limits. Do not bypass those limits. If the user requests another mode, confirm the provider supports it.
The modes are accept-edits (sandbox, human-reviewed escalations), auto (sandbox, automatic review), and full (no sandbox). A read-only brief must forbid writes regardless of mode. For Cursor permission issues, use the provider-details reference.
Spawn
Use the resolved IDs and chosen settings. This example shows the default worker's reasoning, tier, and permissions; replace them when the user requests different settings.
bb thread spawn --json \
--project <project-id> \
--new-environment worktree \
--provider <provider-id> \
--model <model-id> \
--reasoning-level high \
--service-tier fast \
--permission-mode full \
--title "Short title" \
--prompt "$(cat <<'EOF'
Objective: ...
Constraints: ...
Skills and files: ...
Deliverable: ...
Validation: ...
Report back: ...
EOF
)"
Always include --json, --title, and a complete prompt. The quoted heredoc preserves quotes in the brief.
Parent and Sidebar Placement
- Omit parent flags for a standalone, top-level thread: "not as your own subagent".
- Use
--parent-selfwhen this thread coordinates the worker or the job is its subtask. - Use
--parent-thread <id>to nest under another thread. Never combine the two parent flags.
Do not nest unrelated one-off work by default.
Worktree
Use --new-environment worktree for a bb-managed worktree. Do not create one manually unless the user asks.
- Worktrees start with tracked files. Include required untracked files such as
.envthrough the repo's.worktreeinclude; setup may also use.bb-env-setup.sh. Seebb guide environments. - Omit
--base-branchfor the project default; specify it only when needed. - Do not combine
--machinewith an existing--environmentID. - A null
environmentIdin the spawn response can mean the worktree is still being created.
Task Brief
Preserve the userβs scope
- Write a focused assignment preserving intent, constraints, and corrections. Never invent requirements, deliverables, permissions, or approval.
- Model, machine, repository, and thread placement guide the launcher. Give each worker only its task and necessary context.
- Before sending, remove copied conversation, launcher instructions, and unrelated assignments. Never prepend the full user prompt; quote exact wording only when explicitly requested.
The worker does not see this conversation. State the objective, constraints, relevant skills/files, deliverable, validation, and expected report. Name the skills it must read rather than assuming your context carries over.
For read-only jobs, explicitly say no code changes, no Git writes, no database writes. For implementation, specify the allowed scope and any Git or production restrictions. Ask for a concise report, including changed files and validation when relevant.
Verify and Report
scripts/permission-mode.sh <child-thread-id>
Confirm the child received the requested mode. If it differs or is unknown, report the mismatch rather than claiming a successful setup.
Report the thread ID, title, project, provider/model/reasoning/tier, worktree yes/no, and read-only versus implementation scope. Then stop. Do not dump the prompt, open/focus the thread, poll, wait, or read work logs unless the user asks.
Blocked Workers and Lifecycle
If bb reports a blocker, inspect it with bb thread interactions list <id> --json. Resolve routine input within the brief, and approve an action with bb thread interactions approve <interactionId> <id> only when it is authorized and safe. Ask the user about destructive actions, production access, unclear decisions, or work outside the brief. Do not monitor just to look for blockers.
Use bb-cli for lifecycle commands. Archive only when the user asks, then stop the thread to release its runtime. Never delete without an explicit request, and do not use hiding as a substitute for archiving.
Related Skills
claude-mem
117.6kPersistent Context Across Sessions for Every Agent β Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More
Understand-Anything
92.8kGraphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.
headroom
79.8kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
CowAgent
48.0kOpen-source personal AI assistant & Agent Harness. Plans tasks, runs tools and skills, self-evolves with memory and knowledge. Multi-agent, multi-model, multi-channel. Lightweight, extensible, one-line install.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit β see the Safety scan above for what the skill file itself contains.
