qiaomu-goal-meta-skill: turning vague Codex requests into executable /goal commands

The failure mode this skill targets: prompts that read well to humans and execute badly

The README opens with a diagnosis that will be familiar to anyone who has handed a long task to a coding agent. Tasks fail, it argues, not because the model cannot write code, but because the goal was too loose from the start. Its examples are the kind of sentence a person types without thinking: make it more high-end, build me an app, fix this problem, make a web game like GTA. Those requests carry intent for a human reader and almost nothing for an agent. There is no statement of how completion will be checked, which files may be touched, how many times to retry after a failure, or when to stop and ask.

The skill's answer is to treat the goal as a contract rather than a wish. Its stated aim is to hand Codex a /goal before work starts that already contains outcome, verification evidence, constraints, write boundaries, an iteration policy, stop conditions and pause conditions. The audience is narrow but real: people who use Codex or a compatible agent host for multi-step work such as building a site, an app, a game, a Chrome extension, an automation script, a refactor, a release, or a research deliverable. The README is equally explicit about the cases it is not for. A one-line translation, a short rewrite, a single shell command, or any small task that needs neither sustained execution nor verification does not benefit from a contract, and running the skill on one is wasted motion.

How the skill turns a sentence into a contract

The mechanism is a generation pipeline, not a runtime. The flowchart in the README runs left to right: the user's vague request goes in, the skill picks conservative defaults, emits a recommended executable /goal, then fills in verification, constraints and boundaries, then iteration, completion and pause conditions, then presents numbered optional adjustments, and finally mirrors the result with English-compatible field labels.

The ordering matters. The skill does not open with a form. It opens with a finished draft the user can copy immediately, followed by a single sentence explaining why those defaults were chosen. In the README's worked example the default is an original top-down 2D browser game MVP, and the stated reason is that this shape tests the core loop of city movement, driving and a mission fastest while avoiding both copyright exposure and the cost of a 3D open world. Only after the draft and its rationale does the skill offer numbered choices, and those choices are deliberately terse: project shape, visual form, first-version scope, verification method, answerable as 1A 2B or similar. That is the whole interaction design. Reduce typing, keep the decision points explicit.

The defaults themselves encode a policy. Low-risk uncertainty does not block the user; the skill makes an explicit assumption and proceeds. High-risk territory is pushed into the pause conditions instead: credentials and accounts, payments, production data, destructive operations, legal, medical or financial judgement, copyrighted assets and official licensing, real deployment or app store submission, and unclear ownership or product direction. For unfamiliar domains the skill does not pretend expertise. It generates a discovery-first goal, and the README's medical imaging annotation example shows the shape: read the workspace documentation, sample data notes and existing scripts first, implement one minimal verifiable slice, and forbid inventing medical conclusions, compliance statements or data semantics. Vague quality words are not deleted either. High-end, professional, looks like an official site get translated into a design direction, screenshot checks, hierarchy, spacing, typography and readability, capped at a small number of focused visual iterations.

Installing qiaomu-goal-meta-skill and writing your first /goal

Installation is a single npx command, and the README lists Node.js plus npx as a prerequisite, along with an Agent Skills capable host such as Codex or Claude Code and an environment that can read ~/.agents/skills.

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

After it finishes, the README gives this check to confirm the skill landed where the host expects it.

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

A silent exit means the file is there. If the command reports a missing file, the skill did not install to the path the host reads, which is the first row of the troubleshooting table.

For a first real use, phrase the request the way the README's usage examples do, naming the skill and the task. Something like asking it to turn a vague app idea into a Codex goal, or to write a goal for an iOS teleprompter MVP. The skill does not execute anything at that point. It returns text, and the text is meant to be pasted into Codex as the /goal command. The README also notes that the output is mirrored with English field labels, Verification, Constraints, Boundaries, Iteration policy, Stop when and Pause if, so the same goal can be dropped into an English-language agent environment or a team document.

The repository ships a linter for checking the draft before you paste it. It is a Python script and the README gives the invocation with a goal file as the argument.

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

According to the README, the linter rejects non-executable prefixes such as the Chinese /目标 alias, placeholders like [Outcome], TODO and 待定, vague instructions such as make sure it works, 随便改, edit anything and keep trying, and verification conditions that name no concrete evidence. That list is the closest thing the project has to a specification of what a good goal looks like.

The linter is the real contract, and it is narrower than the pitch

The interesting part of this project is not the prompt template. It is the small Python script that checks the output. A meta skill that only reformats a request is a style guide. A meta skill that ships a checker has an enforceable definition of done, and the banned list in the README reads like a catalogue of real agent failures: placeholder brackets left in a supposedly executable command, instructions that permit editing anything, retry language with no ceiling, and verification that amounts to confirming it works.

That said, the linter's scope is textual. It inspects the goal string for forbidden patterns. It cannot tell you whether the verification step you wrote actually exercises the feature, whether the write boundary you declared matches the files the agent will really need, or whether your pause conditions cover the risk in your particular task. Passing the linter means the goal is well formed, not that it is correct for your job. The README's troubleshooting table implies as much: when verification comes back too thin, the fix it suggests is to ask for commands, logs, screenshots, browser or simulator checks, or artifact paths. That is a human judgement about evidence, made after the linter has already passed the text. Treat the script as a floor.

The second constraint is structural. The README states plainly that the skill only creates /goal instructions and does not execute the goal by default. So it adds a step to your workflow rather than removing one. You still paste, run and watch the agent. What you get in exchange is a goal that names its own stop conditions, which is worth the extra step on long tasks and pure overhead on short ones.

Where it is the wrong tool, and what to use instead

Two failure modes are worth calling out. The first is scope. The README is explicit that the skill generates MVP-level goals by default, and that full product strategy, commercialization, deployment and release require an explicit request. If you hand it a vague request for a production launch, the default output will be narrower than you meant, and the gap is on you to close.

The second is the pause conditions. The README's own troubleshooting table flags an agent that stops too early as a symptom of pause conditions written too broadly, and the recommended fix is to demote low-risk uncertainty into a working assumption while keeping only accounts, payment, production, copyright and release as genuine stops. That is a tuning loop, not a one-time setting. A goal that pauses constantly is as useless as one that never does, and the skill cannot know which side of that line your task sits on.

As an alternative, consider the plain approach: write the /goal by hand, or keep a personal template with the same seven fields and fill it in yourself. The difference in approach is where the defaults come from. This skill picks conservative defaults for you, states its reasoning in one sentence, and offers numbered adjustments; a hand-written template gives you no defaults and no rationale, so every choice is yours to invent. That is more work and more control. If your tasks repeat across a few known shapes, a personal template plus the linter script from this repository is a reasonable middle path, though the linter is the only piece of this project you would be reusing.

Maintenance, licence and what an upgrade would cost you

The repository is not archived. Its last push was on 2026-06-11, which is more than six months before today's date, so there is no basis in the available facts for describing it as actively developed or regularly updated. No releases were retrieved, so there is no versioned upgrade path to plan around. The practical consequence is that you should expect to track the main branch, and that the install command pulls whatever is current rather than a pinned tag.

The licence is MIT, with copyright attributed to 向阳乔木. For a skill consisting of a SKILL.md, reference material, an agents directory and one Python script, that is about as permissive as it gets: you can vendor it, modify the linter's banned pattern list, or fold the prompt structure into an internal tool. The one thing worth checking on your own before relying on it in a company setting is whether your agent host reads skills from the same ~/.agents/skills path the README assumes, because a mismatch there is the documented cause of the skill simply not triggering. That is a configuration question, not a licensing one, and it is the first thing to verify after installation.

Editorial conclusion

Adopt it if you run Codex or a compatible Agent Skills host and keep losing time to goals that are either too loose to verify or too broad to be safe. Skip it for translation, one-line rewrites, or any task that does not need sustained execution and verification. Before trusting it, install it and run the bundled linter on a goal it produced, then confirm the command prefix is still /goal rather than the Chinese alias.

Frequently asked questions

Official sources

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