prompt-principles
Prompt principles for manifest-dev: how its maintainer wants the shipped skills, references and other prompts written and checked, and why. Use before planning, writing, restructuring, reviewing or verifying a change to a prompt, a skill or an agent in this repository.
How do I install this agent skill?
npx skills add https://github.com/doodledood/manifest-dev --skill prompt-principlesIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides a set of principles and guidelines for authoring, reviewing, and verifying AI agent prompts and skills, focusing on safety, consistency, and reliability.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Edit rule: each line is a principle with its reason and when it yields. Decisions go to the decision records, rules a check can hold go to the check, and a line is added only on a person's yes, after sharpening an existing line is ruled out.
- Show a prompt change working by driving the behavior cases it touches, new or existing eval cases, through
scripts/verify drive— a case the change must catch and one where it must not fire, under a pass rule fixed before the runs — rather than asking the maintainer to judge the words — the maintainer judges a prompt change by what it makes a run do, and a drive is the evidence they rely on; a suite that rewards one direction pulls later tuning further that way; a whole eval suite runs only when they ask, because each run is many paid sessions. Where the change adds something that runs on every use, report each arm's cost and wall time beside its verdict. Yields when the text must be approved as written, such as a public post, or when no case can reach the behavior; then say so. - When a skill grows a flag or a mode, keep what every invocation needs inline in
SKILL.md, move that mode's bulk to a file underreferences/loaded only when the mode resolves, and keep the trigger inSKILL.md, written as an instruction on an event the run can observe, in aModesorWhat loadstable beside the flags; after adding a reference, check that the default path reaches it — otherwise the default invocation carries the whole file to use a fraction of it, and a trigger inside the deferred file can only be read after the load it was meant to gate; a passive mention or a bare pointer does not load, and the miss is silent. Yields when a mode's mechanics run to a paragraph: an indirection costs a load and a reader's place, and can strand a subtle trigger. - A shipped skill carries its own copy of every term, step, rule and probe its behavior depends on, defined where it first uses it, and defers none to the glossary, another skill, its caller, a host-shipped skill or a section a reader may never reach — a skill installed in someone else's project gets its own
SKILL.mdand the references its loading layer names, never this repository'sCONTEXT.md, and the misses were found on standalone runs: a completion path named a skill that did not ship;figure-out's gloss of fog at first use is the pattern. Yields for plain words that carry no project meaning, and inside one skill or between files a run loads together: there a rule has one owning section and the others point to it, because copies drift — one review found 29 defects, most of them one rule changed in one file while another still stated the old one. - A shipped skill names the capability it needs, never how one setup reaches it — a fixed path, a tool list, an API or MCP server, another CLI — and says nothing only this repository needs — everyone has a different setup, and the skills run on other harnesses. Hard limit, no trade-off.
- A shipped prompt states what the work owes, the maintainer's rulings, what a run cannot read elsewhere, and corrections of defaults a run was seen to take; how to get there is the run's, and the text holds nothing its own reader does not act on — no account of what a caller, a sibling skill or an earlier version owns. A thin result is the correct one — spelled-out method spends attention on every run, overfits it to one path and holds a better model to today's method. Yields when a drive or session shows a run missing something: it goes back in as an outcome, not as steps.
- When a shipped rule is stated and still broken, first place the cause — data the run lacked, a safeguard missing from code, knowledge it was handed, or the text itself — and repair that layer, naming it in the change; do not state it more firmly or add a sibling beside it: replace the failed text with something a run can execute and a reviewer can check (a shape, a named standard, a bound with a rule for what to cut), make it a gate or a check, remove the choice, or give the output one cold reading by a context that did not write it — models comply reliably with a concrete output shape and unreliably with quality adjectives, more words in a layer nothing verifies change nothing, and words added to cover a wiring fault are paid on every run and cure nothing. Yields when output reads as padded to fill the shape: then the shape is the suspect.
- Write an instruction for the class of cases it governs — the condition and what is owed under it — never around the incident that prompted it, and where a prompt needs a call made, name what to weigh and let the model judge; do not stand a size threshold, a per-mode matrix, a closed list, a fixed template, a required tool or a numeric score in for the judgment, and correct a model's default by naming the specific pattern, as a default it may still choose — stand-ins are brittle and game-able, force-fit the novel case and claim precision nobody has, a general exhortation only swaps one default for its neighbour, and wording fitted to one case fails on its neighbour. Yields when a prose hint was seen to make a model invent the mechanism (then give the literal action), and when an interaction grammar must survive intact (then ship an executable example).
- Write a prompt's limits so they do not rest on the reading model's temperament: a loop pushed against stopping early states the condition at which it stops, a bar says what a finding must name to count, and a property that decides behavior is declared, never inferred — the prompt that corrects one model's bias amplifies the opposite bias in another: an unstated finish line had runs re-verifying passing gates for two to four times as long. No yield has been stated.
- Put a correction in the file that loads only for the shape of work that showed the failure, folded into the line that already owns that moment before a new one is added, and settled against every other instruction the run receives that overlaps it, each one it was settled against edited or named in the change — a line in an always-loaded body tilts and weighs down every run, including the small asks that never had the problem, and when two instructions disagree the model picks one. Yields when the same failure is seen in work that file does not load for.
- A restructure, slim or merge of a prompt accounts for every rule it removes or adds — each carried, or dropped or added for a named reason, line by line rather than by section — rewrites here have repeatedly lost load-bearing rules along with the scaffold they meant to cut, and merges have added lines that caused regressions. Yields when a dropped rule shows no need on a drive: record it as dropped rather than restore it.
- An instruction turns only on facts and tools the run actually has — a distinction the model's input cannot show cannot be acted on. Holds without a yield.
- Every example a prompt gives obeys every instruction around it — models imitate examples, so one example that bends a rule trains the model to bend it. Holds without a yield.
- What a model is shown is chosen one field at a time, keeping out whatever it neither needs nor may repeat — a model passes on what it reads. Yields where the model has to know something it must never pass on; then an instruction and a code check both guard that fact.
- A model holds only the tools and permissions its task needs — whatever a model holds, it will in time use. Yields inside a sandbox whose effects are discarded.
- An action a model starts that cannot be undone passes a check outside the model — in code, or a person's confirmation — before it runs — instructions steer a model, they do not guarantee what it does. Holds without a yield.
- When the model behind a feature changes, the checks its prompts passed run again before that change ships, and their results are shown with it — a prompt tuned on one model can behave differently on the next. Yields when no such check exists yet; then the change states that the prompts are unverified on the new model.
Before calling prompt work done, check it against these principles from a fresh start — a new session, or a reviewer who did not do the work. Fix what departs unless the person chose the departure, and check again only after a fix, until a check finds none. Name each departure kept, with the principle and why.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/doodledood/manifest-dev/prompt-principles">View prompt-principles on skillZs</a>