agentleFS
taecontroltaecontrol/skills/skills/in-progress/issue/SKILL.md

issue

Skill1 starsChanged 2 months agoMITView on GitHub

Write an issue or ticket that leaves the solution to whoever picks it up, then have a fresh agent check that it decides nothing nobody decided before publishing. Use when filing, writing, or rewriting an issue or ticket, including a plan's slices and work found and left for later.

53 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use branch, commit and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • MindgamesSkill

    branch

    Use when a user asks to create a new local git branch and start issue work (for example, "create branch" or "start working on issue XYZ"). Use this for issue-based branch naming in the `type/scope-short-description` pattern and for always syncing local `main` from `origin/main` before creating the new branch, creating the local tracking `main` branch first when needed.

    Also in 3 projects that use this

  • SentrySkill

    commit

    Create commit messages following Sentry conventions. Use when committing code changes, writing commit messages, or formatting git history. Follows conventional commits with Sentry-specific issue references.

    Also in 19 projects that use this

  • vertz-devSkill

    backlog

    Manages deferred/blocked work items as GitHub Issues with labels and blocker tracking

    Also in 3 projects that use this

  • CodeWithBehnamSkill

    browse

    Fast headless browser for QA testing and site dogfooding. Navigate any URL, interact with elements, verify page state, diff before/after actions, take annotated screenshots, check responsive layouts, test forms and uploads, handle dialogs, and assert element states. ~100ms per command. Use when you need to test a feature, verify a deployment, dogfood a user flow, or file a bug with evidence.

    Also in 3 projects that use this

  • Microsoft AzureSkill

    test

    Also in 7 projects that use this

  • Microsoft AzureSkill

    lint

    Run all linting and spell checking for TypeScript and Rust code. Run this before committing to catch style issues, clippy warnings, and misspellings.

    Also in 4 projects that use this

  • +1 more from Azure

The file

We split this skill into the rules it gives an agent

1 rule. 0 are common, 1 is distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 51 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Decisions nobody made: Every sentence that settles something no person decided and no source shows: a solution, a rule, a limit, a number, …

    line 46

“Common” is measured: kept by at least 6 in 10 of the 51 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Issue

The reader is the implementer, the person or agent who picks the issue up later, and the teammates who follow the work. They know the product, not the conversation that produced the issue. The implementer investigates and chooses the solution, so the issue gives them the whole problem: what we want and why, what we expect once it is done, and what is already known. Whatever the issue states, they take as settled and build on without questioning it, so it states only what is settled: facts with their source, and decisions a person made.

1. Gather

Collect what the implementer cannot recover alone, each item with its source:

  • Observed: a reproduction, a run, a spike, or code you read, with where it shows the fact.
  • Decided: a choice a person made, with who made it by role, such as "the maintainer", when, and why.
  • Reported: what someone told you, such as a bug report, attributed by role.

Everything else you think about the work is your opinion: the fix you would try, the cause you suspect, a rule, a limit, a number, the shape of the code. That is the implementer's to decide after they investigate, so it stays out of the issue. When the issue comes from a spec or a plan, take from it only the problem, the outcome, and the human's decisions; the rest is that design's, and the implementer makes their own.

Done when every item you mean to state is observed, decided, or reported, with its source.

2. Write

Title: the outcome or the symptom, readable on its own.

The issue answers the implementer's questions, in this order. They are questions, not a template: give each the heading and space this issue needs, or none. A small issue answers them in a few short paragraphs, and most read in about a minute.

  1. What we want and why. The problem or goal, who has it, and what it costs them, in a few lines a reader new to the work understands.
  2. What we expect once it is done. What the person with the problem can do, or no longer suffers, in their terms. The outcome is what the implementer must deliver; the behavior that produces it is theirs to design.
  3. Out of scope, and why.
  4. What is known. The facts and the decisions from step 1. A decision carries its reason, so the implementer can see why it holds.

A fact or decision enters only when, without it, the implementer would build something else or spend long finding it. One that another document already states, such as the plan, gets a link instead of a copy.

Name things the way the product names them. A file or function name enters only as a fact, such as where a failure shows, never as the place a change should go.

When the project has an issue template or written conventions, answer these questions inside them. Earlier issues show what the project discusses, not a structure to follow. Write in the language the team reads, with writing-for-people, and within the repository's visibility, as pr-description describes it.

Done when the issue answers each question it has an answer to, and every statement beyond the problem, the outcome, and the scope is a fact or a decision from step 1.

3. Verify

Give a fresh agent only the title, the issue, the items from step 1 with their sources, and this skill's first paragraph. Its review includes writing-for-people's cold read and also returns:

  1. What it understood. In one sentence each, what we want and what we expect once it is done.
  2. Decisions nobody made. Every sentence that settles something no person decided and no source shows: a solution, a rule, a limit, a number, a behavior, an example, a design.
  3. Each fact, traced to its source by opening it.

Cut each sentence under 2, and each fact its source does not show. When its sentences differ from yours, rewrite the parts that misled it. When the harness offers no fresh context, do the review yourself and say so in your report.

Done when the latest review finds no decision nobody made, no unsupported fact, and its sentences match yours.

4. Publish

Show the human the draft, then create the issue from a file, such as gh issue create --body-file, with the project's labels.

Done when the issue shows the verified text.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.