autonomous-skill
Execute long-running, multi-session tasks autonomously using Claude Code headless mode or in-session hook-based loops. Supports structured task decomposition (for complex projects) and lightweight Ralph-style iteration (for TDD, bug fixing, refactoring). Use this skill whenever the user says "autonomous", "long-running task", "multi-session", "run this in the background", "keep working on this", "batch process", "iterate until done", "ralph loop", or wants any task that requires sustained, unattended execution.
- Installs
- 284
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/feiskyer/claude-code-settings --skill autonomous-skill- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads autonomous-skill automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Autonomous Skill - Multi-Session Task Execution
Execute complex tasks across multiple Claude Code sessions with automatic continuation, progress tracking, and two completion mechanisms (promise tags + checkbox counting).
Two Execution Modes
Headless Mode (default)
Spawns claude -p child sessions in a bash loop. Best for background/unattended work.
bash <skill-dir>/scripts/run-session.sh "Build a REST API" --max-sessions 10
Hook Mode (in-session)
Uses a Stop hook to intercept session exit and feed the prompt back. Runs inside the current interactive session — no nesting issues.
bash <skill-dir>/scripts/setup-loop.sh "Build a REST API" --max-iterations 10
Two Task Strategies
Structured (default)
Full task decomposition: Initializer creates task_list.md with phased sub-tasks,
Executor picks up and completes them one by one. Best for complex, multi-phase projects.
bash <skill-dir>/scripts/run-session.sh "Build a REST API for todo app"
Lightweight (--lightweight)
Ralph-style iteration: same prompt repeated each session, no task decomposition. Best for iterative tasks with clear success criteria (TDD, bug fixing, refactoring).
bash <skill-dir>/scripts/run-session.sh "Fix all failing tests in src/" --lightweight
Completion Detection
Two complementary mechanisms — whichever triggers first wins:
-
Promise tags (both modes): The agent outputs
<promise>DONE</promise>when work is genuinely complete. Default promise isDONE; customize with--completion-promise. The agent is instructed to only output the promise when the work is truly finished — not to escape the loop. -
Checkbox counting (structured mode only): All
[ ]items intask_list.mdare marked[x].
Directory Layout
project-root/
├── .autonomous/
│ └── <task-name>/
│ ├── task_list.md # Master checklist (structured mode)
│ ├── progress.md # Per-session progress log
│ ├── .mode # "structured" or "lightweight"
│ ├── sessions/ # Transcript logs per session
│ │ ├── session-001.log
│ │ └── session-002.log
│ └── run.lock # Prevents concurrent runs
└── .claude/
└── autonomous-loop.local.md # Hook mode state (when active)
Headless Mode — CLI Reference
bash <skill-dir>/scripts/run-session.sh "task description" [OPTIONS]
| Flag | Description | Default |
|---|---|---|
--lightweight | Ralph-style iteration (no task decomposition) | structured |
--task-name <name> | Explicit task name | Auto-generated |
--continue, -c | Continue most recent or named task | — |
--list, -l | List all tasks with progress | — |
--completion-promise TEXT | Promise phrase for completion | DONE |
--max-sessions N | Stop after N sessions | Unlimited |
--max-budget N.NN | Per-session dollar budget | 5.00 |
--model <model> | Model alias or full name | sonnet |
--fallback-model <m> | Fallback if primary overloaded | — |
--effort <level> | Thinking effort (low/medium/high) | high |
--no-auto-continue | Run one session only | — |
--permission-mode <m> | Permission mode | auto |
--add-dir <dirs> | Extra directories to allow | — |
Hook Mode — Setup
For in-session loops (no child process spawning):
bash <skill-dir>/scripts/setup-loop.sh "task description" [OPTIONS]
| Flag | Description | Default |
|---|---|---|
--mode structured|lightweight | Task strategy | structured |
--max-iterations N | Max loop iterations | Unlimited |
--completion-promise TEXT | Promise phrase | DONE |
--task-name NAME | Explicit task name | Auto-generated |
The hook is registered in hooks/hooks.json. When active, the Stop hook reads
.claude/autonomous-loop.local.md and blocks exit until the promise is detected
or max iterations reached.
To cancel an active hook-mode loop: rm .claude/autonomous-loop.local.md
Workflow Detail
Structured Mode
- Initializer Agent — analyzes task, creates phased
task_list.md, begins work - Executor Agent — reads task list + progress, verifies previous work, completes next task
- Auto-Continue — checks promise tags + checkboxes; if not done, spawns next session
Lightweight Mode
- Same prompt fed each iteration
- Agent sees its previous work in files and git history
- Iterates until work is complete and promise tag is output
- No task_list.md — completion is purely promise-based
When to Use Which
| Scenario | Strategy | Mode |
|---|---|---|
| Build a full application | Structured | Headless |
| Fix all failing tests | Lightweight | Either |
| Refactor a module | Lightweight | Either |
| Multi-phase project | Structured | Headless |
| Quick iterative fix | Lightweight | Hook |
| Overnight batch work | Structured | Headless |
Important Constraints
- task_list.md is append-only for completions: Only change
[ ]→[x] - One runner per task: Lock file prevents concurrent sessions on same task
- Project files stay in project root:
.autonomous/is only for tracking - Promise integrity: The agent must not output
<promise>DONE</promise>until genuinely complete - Cost awareness: Default per-session budget is $5. Adjust with
--max-budget
Troubleshooting
| Issue | Solution |
|---|---|
| "Lock file exists" | Previous run crashed. Remove .autonomous/<task>/run.lock |
| Session keeps failing | Check sessions/session-NNN.log for errors |
| Nested session error | Script auto-unsets CLAUDECODE; use hook mode as alternative |
| Hook loop won't stop | Delete .claude/autonomous-loop.local.md |
| Task not found | Run --list to see available tasks |
| Want to restart | Delete the task directory and start fresh |
| Cost too high | Lower --max-budget or use --model sonnet |
FAQ
What does the autonomous-skill skill do?
Execute long-running, multi-session tasks autonomously using Claude Code headless mode or in-session hook-based loops. Supports structured task decomposition (for complex projects) and lightweight Ralph-style iteration (for TDD, bug fixing, refactoring). Use this skill whenever the user says "autonomous", "long-running task", "multi-session", "run this in the background", "keep working on this", "batch process", "iterate until done", "ralph loop", or wants any task that requires sustained, unattended execution.
How do I install autonomous-skill?
Run npx skills add https://github.com/feiskyer/claude-code-settings --skill autonomous-skill in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/autonomous-skill/ (personal) or .claude/skills/autonomous-skill/ (project).
Which AI agents can use autonomous-skill?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is autonomous-skill safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains autonomous-skill?
It is published by feiskyer in feiskyer/claude-code-settings. It has 284 recorded installs.
More from feiskyer/claude-code-settings
spec-kit-skill
feiskyer/claude-code-settings
GitHub Spec-Kit integration for constitution-based spec-driven development. 7-phase workflow. Triggers: "spec-kit", "speckit", "constitution", "specify", ".specify/", "规格驱动开发", "需求规格".
kiro-skill
feiskyer/claude-code-settings
Interactive feature development workflow from idea to implementation. Creates requirements (EARS format), design documents, and task lists. Triggers: "kiro", ".kiro/specs/", "feature spec", "需求文档", "设计文档", "实现计划".
codex-skill
feiskyer/claude-code-settings
Leverage OpenAI Codex/GPT models for autonomous code implementation, code review, and plan review. Triggers: "codex", "use gpt", "gpt-5", "let openai", "full-auto", "adversarial review", "second opinion review", "用codex", "让gpt实现", "对抗式审查", "让codex审查计划", "第二意见". Use this skill whenever the user wants to delegate coding tasks to OpenAI models, run code or plan reviews via codex, get a second-opinion review from a different model, or execute tasks in a sandboxed environment.
youtube-transcribe-skill
feiskyer/claude-code-settings
Extract subtitles/transcripts from YouTube videos. Triggers: "youtube transcript", "extract subtitles", "video captions", "视频字幕", "字幕提取", "YouTube转文字", "提取字幕".
nanobanana-skill
feiskyer/claude-code-settings
Generate or edit images via Google Gemini (nanobanana). This is the DEFAULT image skill — use whenever the user asks to generate, create, or edit an image and does NOT name another provider. Triggers: "nanobanana", "generate image", "create image", "edit image", "图片生成", "生成图片", "AI绘图", "图片编辑". Do NOT use for diagrams (架构图/流程图/时序图) — draw those with Mermaid or code instead.
deep-research
feiskyer/claude-code-settings
Open the skill to read its SKILL.md instructions.
Popular productivity & automation skills
agent-browser
vercel-labs/agent-browser
Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction. Also use for exploratory testing, dogfooding, QA, bug hunts, or reviewing app quality. Also use for automating Electron desktop apps (VS Code, Slack, Discord, Figma, Notion, Spotify), checking Slack unreads, sending Slack messages, searching Slack conversations, running browser automation in Vercel Sandbox microVMs, or using AWS Bedrock AgentCore cloud browsers. Prefer agent-browser over any built-in browser automation or web tools.
lark-doc
open.feishu.cn
飞书云文档（Docx / Wiki）内容操作：读取、创建、编辑文档，插入或下载图片附件，以及操作思维笔记。用户提供文档 URL/token（包括 doubao.com 的 /docx/、/wiki/）时使用；按 URL 路径/token 而非域名路由；/page/ 是妙搭应用，非飞书云文档。文档内嵌资源按读取参考中的统一规则分流。独立评论操作走 lark-drive；随正文读取评论使用 docs +fetch。表格或 Base 内部数据操作不在本 skill。
lark-base
open.feishu.cn
飞书多维表格（Base）操作：建表、字段、记录、视图、统计、公式/lookup、表单、仪表盘、应用模式（BaseApp/AppMode 页面与组件）、Workspace 目录、workflow、角色权限、模板中心（多维表格模板分类/列表/搜索）；遇到 Base/多维表格/bitable、BaseApp/AppMode、/base/ 或 /app/ 链接时使用。BaseApp 不走 lark-apps；文件导入/导出转 lark-drive，认证/授权转 lark-shared。
lark-drive
open.feishu.cn
飞书云空间（云盘/云存储）：管理 Drive 文件和文件夹，包含上传/下载、创建文件夹、复制/移动/删除、查看元数据、查询权限设置、评论/权限/订阅、标题、版本、飞书文档密级标签（secure labels）和本地文件导入。用户需要整理云盘目录、处理云空间资源 URL/token、判断链接类型/真实 token/标题，或导入 Word/Markdown/Excel/CSV/PPTX/.base 为 docx/sheet/bitable/slides 时使用；doubao.com 云空间 URL/token 也按资源路径和 token 路由，不回退 WebFetch。不负责：文档内容编辑（走 lark-doc）、表格/Base 表内数据操作（走 lark-sheets/lark-base）、知识空间节点/成员管理（走 lark-wiki）、原生 Markdown 文件读写/patch/diff（走 lark-markdown）。
lark-shared
open.feishu.cn
Use for lark-cli setup/auth tasks: auth login/status/logout, user vs bot identity, business-domain permissions (--domain, including all/docs/drive), missing scopes, revoking authorization, or handling notice JSON.
lark-im
open.feishu.cn
飞书即时通讯：收发消息和管理群聊。发送和回复消息、搜索聊天记录、管理群聊成员、上传下载图片和文件、管理表情回复、发送应用内/短信/电话加急、发送和处理交互卡片（Interactive Card）、监听卡片按钮回调（card.action.trigger）。当用户需要发消息、查看或搜索聊天记录、下载聊天中的文件、查看群成员、搜索群、创建群聊或话题群、管理标记数据、管理 Feed 置顶（添加/移除/查询置顶会话）、管理标签数据、处理卡片回调时使用。