codingthefuturewithai/teamcraft:improve-teamcraft

Why This Skill Exists

Teamcraft only improves if real friction gets back to the people who maintain it — and gets back in a form they can act on. A vague "the planning skill felt off" costs more than it's worth: someone has to reconstruct what happened, guess the cause, and decide if it's even real. A report that names the skill, quotes the line that misled the agent, says what was ruled out, and proposes a fix can be triaged in a minute.

This skill's job is to turn the first kind of feedback into the second. The hard, valuable part isn't writing the issue — it's vetting: deciding whether what frustrated the user is actually a defect in a Teamcraft skill, or something else wearing that costume (the user's own project setup, the harness, the model having a bad moment, or the skill being misused). Filing noise upstream is worse than filing nothing.

So the centre of gravity here is honest triage grounded in the skill's actual source — not transcribing a complaint, and not rubber-stamping the user's diagnosis.

The One Non-Negotiable: Ground the Verdict in the Real Skill Text

Before you form any opinion about cause, open the implicated skill's SKILL.md and read the part that supposedly misbehaved. The skills being critiqued ship in the same installed teamcraft plugin as this one — they're siblings. Read them. Quote them.

This is what separates a useful report from a plausible-sounding wrong one. The best feedback Teamcraft has ever received did exactly this: it read the skill, quoted the offending bullet, and showed how that specific wording produced the bad outcome. You cannot root-cause a skill you haven't read.

Where it showed up is not always where it came from. Feedback isn't really "about a skill" — it's about a point in the user's workflow where something went wrong or could be better. Hold three things apart:

• Manifestation locus — the skill they were running when they noticed it.
• Cause locus — where the root cause actually lives. It may be that same skill, an upstream skill that ran earlier, or neither.
• The seam — Teamcraft skills don't call each other; they coordinate through world state (the work item, INDEX, the branch, the captured docs). So a cross-skill bug is usually a contract bug at the handoff: one skill left the artifact or state in a shape the next didn't expect, or didn't leave something the next needed. The bug is in neither skill's body — it's in the seam.

So when more than one skill is on the path, reading one SKILL.md isn't enough: read every skill the work passed through, and the artifact/state each handed to the next. Otherwise you'll "fix" the skill where it surfaced and miss the one that caused it. "I'm not sure which skill" is a perfectly good starting point — it means investigate the path, not make the user pick.

The reference examples may closely resemble the case in front of you — that's calibration, not a shortcut. Re-derive every verdict from the live source anyway; never transcribe an example's root cause. An example can be wrong, or right about a different version of the skill than the one installed now.

What to Do

Six beats. They're a methodology, not a rigid script — adapt to what the user brings. But don't skip the vetting, and don't skip grounding it in the source.

1. Understand the intent. $ARGUMENTS is what went wrong, an improvement idea, or empty. People arrive three ways, all handled the same:

• "This just happened" — the failure is in the current session. That live context is your best evidence; use it.
• "This keeps annoying me" — a recurring pattern they're recounting from memory. Interview for a concrete instance.
• "I have an idea" — a pure improvement with no failure attached. Legitimate; it routes to a feature-request rather than a bug.

Establish what the user expected and what actually happened. Establish where it showed up — but don't force a single skill out of them. They may name one skill, several, "the build loop," or "validate-issue, but I think it's really upstream in plan-and-implement — or the combination, I'm not sure." All of those are valid; the last is often the most useful, because the seam between skills is where the subtle bugs live. Don't presuppose they hit a defect, and don't presuppose it's confined to one skill — you don't know either yet.

2. Gather evidence. Read the implicated skill's SKILL.md (and any reference files it leans on) from the installed plugin. When more than one skill is on the path, read each one — and read the artifact or world state each hands to the next (the work item file, INDEX, branch, captured docs), because that handoff is where cross-skill bugs hide. Read the teamcraft plugin manifest for the version and the repository URL — both feed the issue and neither should be hardcoded or guessed. Reconstruct the concrete failure: what each skill on the path instructed, what the agent did, what state moved between skills, what the user saw, what they expected instead.

3. Vet — the heart. Root-cause the symptom against the skill text you just read, and sort it honestly:

• Bug — a skill instruction (or a gap in one) led the agent to the wrong outcome. This is the target. Example: a relevance heuristic that trains topic-matching and so skips a cross-cutting decision.
• Feature-request — Teamcraft works as written but is missing coverage, or the user has an idea that would make it better. Also worth filing.
• Misuse — the skill actually handles this; it just wasn't followed (skipped a step, ignored a gate). Not a Teamcraft defect.
• Harness / environment — Claude Code itself, an MCP server, the backend tool, or the model's behavior. Not Teamcraft.
• Project-specific — the user's own CLAUDE.md, repo config, or conventions. Not the plugin.

Actively try to rule out the non-Teamcraft causes — and say what you ruled out and why. "Things that are NOT the cause" is one of the most valuable parts of a report; it stops the maintainer re-doing your investigation.

Then settle scope, which is orthogonal to type — a bug or a feature-request can be any of these:

• single-skill — cause and symptom live in one skill.
• cross-skill (seam) — symptom in one skill, cause in another or in the handoff contract between them. Name both loci and describe the seam: which artifact/state crossed it, and how its actual shape differed from what the consuming skill expected.
• workflow — the feedback is about how several skills fit together (e.g. "the build loop should be designed differently"), not any one of them. Usually a feature-request; the affected-skills list is the set in that workflow.

Don't collapse a cross-skill or workflow issue into the single skill where it surfaced — that's how the wrong skill gets "fixed" while the real seam stays broken.

4. Decide whether to file. Present your verdict plainly, including "I don't think this is a Teamcraft problem — here's what I think actually happened." Then:

• Search existing issues on the repo first (gh issue list --search, scoped to the repo from the manifest) — search across both open and closed issues, and try a couple of phrasings (the skill name, and a few words of the symptom), since a near-duplicate rarely shares your exact wording. If something matches, offer to add a comment to that issue instead of opening a duplicate. An empty backlog is a fine result — don't over-search.
• Recommend based on the verdict. The developer has final say. If you concluded it isn't a skill issue and they still want it filed, file it — framed honestly as what it is, not dressed up as a defect. This skill never refuses the user; it advises and then does what they decide.

5. Structure the issue. Draft it in the shape that references/example-feedback-issue.md shows — read that file before drafting so the output is consistent and agent-ingestible. Show the full draft to the developer and iterate.

Privacy gate. These issues are public. Before anything ships, scan the draft for proprietary specifics — internal repo names, code paths, product/business nouns, anything not safe to publish — and offer to genericize them. Workflow-structural identifiers (skill names, work-item IDs, branch names like feat/<slug>) are generally safe and usually load-bearing for the report; business and product nouns and internal file paths are what to scrub. The technical substance almost never depends on the real names. Get explicit confirmation that the developer is comfortable with what's in the body.

6. Publish. Only on explicit go-ahead. Write the issue body to a scratch temp file (never into the user's project) and create it with the GitHub CLI against the repository from the manifest — title, body file, and the type label (bug or enhancement) plus a teamcraft label. If a label doesn't exist and you can create it, do; if label creation isn't permitted, file without it rather than failing. For the teamcraft label, default to a recognizable color and a short description (e.g. --color 5319e7 --description "Feedback on the Teamcraft plugins") so runs stay consistent. Confirm gh is authenticated first; if it isn't, tell the user how to authenticate and let them do it (e.g. they can run ! gh auth login). Report the issue URL when it's filed.

Constraints

Honesty over volume. A correct "this isn't a Teamcraft bug, here's why" is a better outcome than a filed issue. Don't inflate misuse or harness quirks into skill defects to manufacture a report.

Never auto-publish. Nothing reaches GitHub without the developer seeing the final body and explicitly approving. The publish step is theirs to trigger.

The user is in charge. Your triage is advice. If they overrule it, follow them — file what they want filed, framed for what it actually is.

Don't hardcode what you can read. The version and repo come from the manifest; the cause comes from the skill source. Read them; don't assume them.

When the Skill Is Complete

Either an issue (or comment) is filed and you've handed back the URL, or the developer decided not to file and understands why. In both cases, say plainly what happened and what you concluded. Don't leave a draft dangling as if the work is unfinished when the developer has chosen not to publish — that's a complete, valid outcome.