qiaomu-goal-meta-skill: Turn Vague Task Descriptions into Structured Codex /goal Commands

What qiaomu-goal-meta-skill does and who it is for

Codex and similar agents often fail not because they cannot write code, but because the goal they receive is too loose. Instructions like help me make an app or fix this bug leave the agent without a way to verify success, without a list of things it should not touch, and without a rule for when to stop. The result is either a timeout, a broken environment, or a change set that is larger than intended.

qiaomu-goal-meta-skill addresses this by intercepting vague requests before the agent starts work. It reads the description, applies conservative defaults, and generates a complete /goal command ready to copy and paste. The README lists the output fields: outcome, verification, constraints, boundaries, iteration policy, stop conditions, and pause conditions.

The target user is a developer using Codex or Claude Code for multi-step tasks where correctness, scope control, and safe failure behavior matter: building a web application, running a release, doing a refactor, creating documentation, or automating a workflow. The README explicitly lists tasks that are not a good fit: one-line translations, simple rewrites, single shell commands, and anything that does not require iteration and verification.

The seven-field goal structure and what each field does

The /goal command produced by the skill has seven distinct sections. Each serves a different purpose in controlling the agent's behavior.

The outcome is the stated deliverable: what the agent should produce, described specifically enough to test. The README contrasts this with vague phrases like make it more professional, and shows how those get converted into testable criteria.

The verification section specifies evidence that the outcome was achieved: which commands to run, what logs or screenshots to check, or what file to inspect. The skill replaces vague verification like make sure it works with concrete evidence criteria.

Constraints list what the agent must not do: use copyrighted assets, call paid APIs, deploy to production, modify unrelated files. Boundaries specify exactly which files or directories the agent can write to.

The iteration policy sets how the agent should handle failure: start with a minimum viable version, run checks after each meaningful change, read error logs before retrying, and limit the number of focused improvement rounds. The README defaults to a maximum of three focused improvement rounds.

Stop conditions specify the evidence required for the task to be considered done. Pause conditions list high-risk situations where the agent must stop and wait for human input: credentials, payment systems, production data, legal or medical judgments, copyrighted assets, and official publication or deployment.

Installing qiaomu-goal-meta-skill

The skill installs through npm's npx interface:

npx skills add joeseesun/qiaomu-goal-meta-skill

This requires Node.js and npx to be installed on your system. After installation, verify the skill is in place:

test -f ~/.agents/skills/qiaomu-goal-meta-skill/SKILL.md

If the file exists, the skill is ready. If not, the README troubleshooting table lists two common causes: the runtime environment did not load local skills, or the installation path is incorrect.

The skill requires a runtime that supports agent skills, such as Codex, Claude Code, or a compatible tool. It is not a Python package or a CLI binary; it is a SKILL.md file that agent runtimes read and execute. The manifest.json in the repository root describes the skill's metadata, and the agents/ directory contains the skill implementation.

Conservative defaults and the recommendation logic

A key design decision in the skill is that it does not ask the user to fill out a form. Instead, it makes explicit assumptions, generates a recommended version, explains that recommendation in one sentence, and then offers numbered options for the most important decision points.

For a GTA-like browser game, the README shows the skill choosing a top-down 2D MVP as the default, with the explanation: the minimal 2D MVP verifies the core fun of city movement and driving most quickly while avoiding copyright and the high cost of a 3D open world. It then presents four numbered choices covering project form, visual style, scope, and verification method. The user can reply with option numbers or accept the default without reading the full list.

The README describes three built-in operating principles: default to moving forward when risk is low, require pause for high-risk situations, and go discovery-first for unfamiliar domains. In a discovery-first goal, the agent reads project documentation and existing code before making any changes, and lists its assumptions before writing anything. This pattern applies when the task involves medical, financial, compliance, or other specialized data.

The linter: catching placeholder patterns before submission

The repository includes a Python linter at scripts/lint_goal_command.py. Run it against a saved /goal command to catch problems before passing it to an agent:

python3 ~/.agents/skills/qiaomu-goal-meta-skill/scripts/lint_goal_command.py goal.txt

The linter blocks several categories of problems that the skill is designed to prevent from appearing in the first place, but that can appear if the user modifies the output. It flags the /目标 prefix instead of /goal, which is not executable by the agent. It flags placeholder tokens like [Outcome], TODO, and 待定. It flags vague verification phrasing like make sure it works. It flags unsafe scope patterns like edit anything and keep trying. It also flags stop conditions that cite no specific evidence.

This check is useful when a generated goal is edited manually or when a goal is constructed by combining output from multiple tool calls. It does not evaluate whether the goal is a good fit for the task; it only catches structural problems that would cause the agent to behave incorrectly.

Limitations: skill only creates /goal, does not execute it

qiaomu-goal-meta-skill only creates /goal commands. It does not execute them. After the skill generates a /goal, the user must copy it and submit it to the agent manually, or use a workflow that pipes the skill output directly into an agent run. The README states this boundary explicitly: this skill creates the /goal command, not the default execution of the goal itself.

The skill does not replace professional judgment for regulated domains. The README states the skill will not generate fabricated medical conclusions, compliance claims, or diagnostic purposes. For tasks that involve medical, financial, or legal content, the skill produces a discovery-first goal that reads documentation before acting, but the skill itself provides no domain expertise.

The last push to the repository was on 2026-06-11. There are no GitHub releases, and the repository is not archived. The skill targets Codex specifically, though the README notes compatibility with Claude Code and other tools that support the agent skill format. The troubleshooting table in the README addresses the case where the skill does not trigger in a given runtime environment.

How qiaomu-goal-meta-skill differs from writing /goal commands manually

Writing a /goal command by hand requires knowing all seven fields and filling in reasonable values for each. Most developers skip the verification, boundary, and pause condition fields because they are easy to omit and the immediate cost of omitting them is not obvious until the agent does something unexpected.

qiaomu-goal-meta-skill makes omission harder by generating all seven fields from a one-sentence description. The generated output errs toward narrow scope: it specifies the exact directory the agent can write to, lists specific things it cannot do, and names the commands that count as evidence of completion.

The alternative is a prompt-engineering approach where the developer writes a detailed instruction directly. This works when the developer knows the task well enough to specify it precisely. The skill is most useful for cases where the developer has a rough idea of the outcome but has not thought through verification, safe failure, or scope boundaries in detail. It is not a substitute for thinking through complex or high-stakes tasks; it is a way to make the planning step faster and less likely to omit safety-relevant fields.

Editorial conclusion

qiaomu-goal-meta-skill is useful for anyone using Codex or Claude Code who finds that vague task descriptions produce poor or unsafe agent behavior. The skill handles common cases well: web apps, bug fixes, refactors, and document deliveries. It is not appropriate for one-line tasks, simple translations, or any task where the agent does not need to iterate and verify. Before adopting it, test the /profile command with a task you actually need to complete and check whether the generated stop conditions are narrow enough to prevent unsafe scope expansion.

Frequently asked questions

Official sources

1. Issues
2. joeseesun/qiaomu-goal-meta-skill on GitHub
3. License: MIT
4. README