How do I install the Explain State skill?

Run npx skillmds@latest add thettwe/explain-state in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Explain State safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Explain State?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Explain State free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Explain State?

thettwe (@thettwe) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Explain State by thettwe — Agent Skill

Name: Explain State
Author: thettwe

Explain State

Summarize what nyann currently sees in this repo: stack detection, active profile, branching strategy, hook status, CLAUDE.md, and recent commits. TRIGGER when the user says "what does nyann think is set up here", "show nyann state", "explain the setup", "what's the current config", "what's the active profile", "describe this repo's nyann setup", "what's wired up", "show me the repo state", "/nyann:explain-state". Do NOT trigger on "what does this repo do" (that's a docs intent — route to CLAUDE.md / README), "is this repo healthy" (that's the `doctor` skill), or "what's in the X profile" (that's `inspect-profile`).

thettwe b13d545 3.3 KB Updated Sep 17, 2026

File contents

explain-state

Read-only. Never mutates. Wraps bin/explain-state.sh.

1. Invoke

bin/explain-state.sh --target <cwd> [--json] [--profile <name>]

No args → human-readable table, easy to read back to the user.
--json → machine-readable JSON when the user wants to pipe it or you need structured fields for a follow-up operation.
--profile <name> → override profile inference when the user names one explicitly.

2. Read the output aloud

The JSON has six blocks. When the user asks a general "what's the state", summarize the highlights rather than dumping the whole structure:

stack → "Detected <primary_language>" + framework + package manager. Call out confidence < 0.5 as "weak detection — might be worth confirming".
profile → "Active profile: <name> (source: <starter|user| team|unknown>)". When source is unknown, say "couldn't infer the profile; CLAUDE.md doesn't reference one".
branching → "Strategy: <strategy>; base branches: <list>". If null, profile isn't resolved.
hooks → "Husky: <bool> / pre-commit.com: <bool> / nyann core hooks: <bool>". These are presence signals only — they tell you whether something's wired, not whether it's healthy. For health, route to doctor.
claude_md → "CLAUDE.md present, <bytes> bytes, router markers <bool>". Mention the 3 KB soft / 8 KB hard budget if bytes > 3072.
recent_commits → Mention the count; read back the 1-2 most recent subjects.

3. Follow-up routing

The whole point of explain-state is to help the user decide what to do next. Offer one or two next steps based on what's present:

Stack but no profile → suggest bootstrap-project with a matching profile name.
Profile but no hooks wired → suggest re-running /nyann:retrofit to install the hook bundle.
CLAUDE.md missing router markers → note it can be regenerated via /nyann:retrofit.
Everything present and clean → "Looks set up. Want a deeper audit? Run doctor for drift checks."

4. When the profile field shows `(unknown)`

CLAUDE.md wasn't generated by nyann (or the marker block has been removed). Don't treat this as a bug — some users intentionally hand- curate CLAUDE.md. Ask whether they want to re-bootstrap or leave it manually-maintained.

When to hand off

"Is it healthy?" / "What's drifted?" → doctor skill.
"What does nextjs-prototype do?" → inspect-profile.
"Set this up with the right profile" → bootstrap-project.
"I want to change the branching strategy" → edit the profile (or pick a different one) and re-bootstrap.

---name: explain-statedescription: Summarize what nyann currently sees in this repo: stack detection, active profile, branching strategy, hook status, CLAUDE.md, and recent commits. TRIGGER when the user says "what does nyann think is set up here", "show nyann state", "explain the setup", "what's the current config", "what's the active profile", "describe this repo's nyann setup", "what's wired up", "show me the repo state", "/nyann:explain-state". Do NOT trigger on "what does this repo do" (that's a docs intent — route to CLAUDE.md / README), "is this repo healthy" (that's the `doctor` skill), or "what's in the X profile" (that's `inspect-profile`).---# explain-stateRead-only. Never mutates. Wraps `bin/explain-state.sh`.## 1. Invoke```bin/explain-state.sh --target <cwd> [--json] [--profile <name>]```- **No args** → human-readable table, easy to read back to the user.- **`--json`** → machine-readable JSON when the user wants to pipe it or you need structured fields for a follow-up operation.- **`--profile <name>`** → override profile inference when the user names one explicitly.## 2. Read the output aloudThe JSON has six blocks. When the user asks a general "what's thestate", summarize the highlights rather than dumping the wholestructure:- **stack** → "Detected `<primary_language>`" + framework + package manager. Call out `confidence < 0.5` as "weak detection — might be worth confirming".- **profile** → "Active profile: `<name>` (source: `<starter|user| team|unknown>`)". When source is `unknown`, say "couldn't infer the profile; CLAUDE.md doesn't reference one".- **branching** → "Strategy: `<strategy>`; base branches: `<list>`". If null, profile isn't resolved.- **hooks** → "Husky: `<bool>` / pre-commit.com: `<bool>` / nyann core hooks: `<bool>`". These are presence signals only — they tell you whether something's wired, not whether it's healthy. For health, route to `doctor`.- **claude_md** → "CLAUDE.md present, `<bytes>` bytes, router markers `<bool>`". Mention the 3 KB soft / 8 KB hard budget if bytes > 3072.- **recent_commits** → Mention the count; read back the 1-2 most recent subjects.## 3. Follow-up routingThe whole point of explain-state is to help the user decide what todo next. Offer one or two next steps based on what's present:- Stack but no profile → suggest `bootstrap-project` with a matching profile name.- Profile but no hooks wired → suggest re-running `/nyann:retrofit` to install the hook bundle.- CLAUDE.md missing router markers → note it can be regenerated via `/nyann:retrofit`.- Everything present and clean → "Looks set up. Want a deeper audit? Run `doctor` for drift checks."## 4. When the profile field shows `(unknown)`CLAUDE.md wasn't generated by nyann (or the marker block has beenremoved). Don't treat this as a bug — some users intentionally hand-curate CLAUDE.md. Ask whether they want to re-bootstrap or leave itmanually-maintained.## When to hand off- "Is it healthy?" / "What's drifted?" → `doctor` skill.- "What does `nextjs-prototype` do?" → `inspect-profile`.- "Set this up with the right profile" → `bootstrap-project`.- "I want to change the branching strategy" → edit the profile (or pick a different one) and re-bootstrap.

Frequently asked questions