New: 97,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Guidance

by testdouble in testdouble/han

Authoritative guidance for building Claude Code skills, agents, and plugins, plus init and update steps that install and refresh the plugin-building skills in the current repository.

MITAuto-check passedAgent Workflows

Install Guidance

skills CLI
$ npx skills add testdouble/han --skill guidance -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install testdouble/han guidance --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/testdouble/han.git skills-src && mkdir -p .claude/skills && cp -r skills-src/han-plugin-builder/skills/guidance .claude/skills/guidance && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
guidance
GitHub stars
279
Token cost
~1.8k tokens
SKILL.md length
842 words
Files
53 (incl. scripts, references, assets)
Skills in repo
54
Repo updated
First seen
Licence
MIT

At a glance

Authoritative guidance for building Claude Code skills, agents, and plugins, plus init and update steps that install and refresh the plugin-building skills in the current repository.

  • Works in 4 steps: Identify what the user is building or… → List the relevant subdirectory under… → Read only the document(s) that directly… → …
  • You need the rules
  • SKILL.md covers Project Context, Guidance Mode, Initialization Mode and Update Mode
  • Calls bash

What it does

Guidance is an agent skill from testdouble/han. Authoritative guidance for building Claude Code skills, agents, and plugins, plus init and update steps that install and refresh the plugin-building skills in the current repository. Use when you need the rules or best practices for a skill, agent, hook, or plugin — designing, reviewing, hardening, or checking one against the guidance. Run with init to vendor the guidance, skill-builder, and agent-builder skills into the current repository (so they run with no dependency on this plugin) plus a path-scoped rule…

Its SKILL.md is about 1.8k tokens, which your agent loads only when the skill is triggered. The skill folder holds 56 other files, including scripts, reference files and assets (for example `assets/guidance-portable-SKILL.md`, `assets/rule-index-body.md` and `references/agent-building-guidelines/agent-description-length.md`).

It sits in Agent Workflows, covering Building AI agents and Skill authoring. The repository describes itself as: Han: AI skills and agents for "Solo" product engineers and small teams. The licence is MIT.

When your agent uses it

  • You need the rules
  • Best practices for a skill
  • Plugin — designing
  • Checking one against the guidance

Example prompts

  • “/guidance”

Requirements

  • Pre-approved tools (allowed-tools): Read, Glob, Grep, Bash(find *), Bash(bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh")

Workflow steps

4 steps, taken from the first numbered list in SKILL.md.

  1. Identify what the user is building or asking about.
  2. List the relevant subdirectory under ${CLAUDE_SKILL_DIR}/references/ to see the available documents, using the map
  3. Read only the document(s) that directly apply.
  4. Apply the guidance to the user's situation. Cite the document you used so the user can read it in full if they want.

What it can do on your machine

Read from SKILL.md and the folder at commit abba73a. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves these tools, so the agent can use them without asking each time:

    • Read
    • Glob
    • Grep
    • Bash(find *)
    • Bash(bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh")

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 1 file in scripts/, which the agent can run.

    Shell commands in SKILL.md call:

    • bash

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Guidance loads about 1.8k tokens when it runs, and up to ~96k if it reads all its reference files. Until then it costs about 193 tokens; SKILL.md has 842 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~193
When it runs · the whole SKILL.md, loaded when a task matches
~1.8k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~96k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from testdouble/han at commit abba73a, republished under its MIT licence (© testdouble). 842 words, ~1,847 tokens.

Download SKILL.mdSave it as .claude/skills/guidance/SKILL.md (or your agent's skills folder). This skill also uses 52 other files; get the full folder from GitHub.
name
guidance
description
Authoritative guidance for building Claude Code skills, agents, and plugins, plus init and update steps that install and refresh the plugin-building skills in the current repository. Use when you need the rules or best practices for a skill, agent, hook, or plugin — designing, reviewing, hardening, or checking one against the guidance. Run with `init` to vendor the guidance, skill-builder, and agent-builder skills into the current repository (so they run with no dependency on this plugin) plus a path-scoped rule index, or `update` to refresh an already-vendored copy. Does not run an interview to build a new skill or agent from scratch — use skill-builder or agent-builder. Does not write feature code, review application code, or build non-plugin features.
allowed-tools
Read, Glob, Grep, Bash(find *), Bash(bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh")

Project Context

  • personal config directory: !bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"
  • project .han/config.md: !cat .han/config.md 2>/dev/null || echo ""

As your first action, use the Read tool on .han/config.md inside the personal config directory path above. A read that returns no file is no personal configuration: continue silently. When that file or the project .han/config.md probe supplies content, apply it per config-rule.md, which governs precedence between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.

This skill has three modes. Pick the mode from how it was invoked, then follow only that mode's steps.

  • If the invocation argument is init or initialize (any case), run Initialization Mode.
  • If the invocation argument is update or refresh (any case), run Update Mode.
  • Otherwise, run Guidance Mode.

Guidance Mode

Serve the relevant guidance for what the user is building. Do not read every guidance document — that defeats the purpose. Find the one or two that apply, read them, and apply them.

The guidance documents live in this skill's own references/ directory. Use this map to choose, then read only the specific file(s) you need:

  • Deciding whether something should be a skill, agent, or hook → ${CLAUDE_SKILL_DIR}/references/plugin-entity-taxonomy.md.
  • Authoring or hardening a skill (descriptions, frontmatter, progressive disclosure, allowed-tools, scripts, composition, testing, troubleshooting) → the files under ${CLAUDE_SKILL_DIR}/references/skill-building-guidance/.
  • Authoring an agent (domain focus, self-containment, model selection, multi-agent economics, graceful degradation) → the files under ${CLAUDE_SKILL_DIR}/references/agent-building-guidelines/.
  • Plugin or marketplace configuration files (plugin.json, marketplace.json, monitors.json, themes.json) → the files under ${CLAUDE_SKILL_DIR}/references/claude-marketplace-and-plugin-configuration/.
  • Versioning, README structure, local development, the iterative development process, and specialization-versus-model-tier reasoning → the top-level files in ${CLAUDE_SKILL_DIR}/references/.
  • Writing the instructions for a target model (how Sonnet 5, Opus 5, and Fable 5 differ in following instructions, which instructions to leave out, and how to calibrate length, narration, and scope) → ${CLAUDE_SKILL_DIR}/references/per-model-authoring.md.
  • Copyable starter files → ${CLAUDE_SKILL_DIR}/references/templates/.

Steps:

  1. Identify what the user is building or asking about.
  2. List the relevant subdirectory under ${CLAUDE_SKILL_DIR}/references/ to see the available documents, using the map above.
  3. Read only the document(s) that directly apply.
  4. Apply the guidance to the user's situation. Cite the document you used so the user can read it in full if they want.

Initialization Mode

Install the plugin-building skills into the current repository so anyone using the repo can run them and consult the guidance, with no dependency on this plugin remaining installed.

  1. Run ${CLAUDE_SKILL_DIR}/scripts/init-guidance.sh from the repository root. The script vendors three skills into .claude/skills/ under a plugin- prefix so they never collide with this plugin's own slash commands: a guidance-only plugin-guidance skill (whose references/ directory is the single in-repo copy of the guidance documents), plugin-skill-builder, and plugin-agent-builder (with their names, cross-references, and guidance paths rewritten to that vendored copy). It then writes the path-scoped rule index at .claude/rules/plugin-building-guidance.md. Capture its output.
  2. Report to the user what was written: the three vendored skills, the total file count, the rule index path, and the paths: globs. Explain that the three skills are now available directly in the repo (/plugin-guidance, /plugin-skill-builder, /plugin-agent-builder) and that the rule index is an index only — Claude Code loads it when a matching skill or agent file is touched, and it points to the vendored guidance so only the documents the current file needs are loaded, not all of them.
  3. Do not commit. Leave the new files staged for the user to review.
Show full SKILL.md (287 more words)Show less

Update Mode

Refresh the vendored skills and their rule index in a repository that already has them, so contributors get the current skills and guidance after this plugin has been updated. Updating is the same vendoring operation as Initialization Mode — it replaces every vendored skill in full (each SKILL.md and the guidance documents under plugin-guidance/references/, removing any files that the plugin source has since dropped) and regenerates the rule index — but it first confirms the skills are actually installed before touching anything.

  1. Check whether the skills are already installed at the expected location. Run find .claude -maxdepth 3 \( -path '*/skills/plugin-guidance' -o -name plugin-building-guidance.md \) from the repository root. The skills are installed only when both the .claude/skills/plugin-guidance directory and the .claude/rules/plugin-building-guidance.md rule index turn up.
  2. If the skills are not installed (the find turns up neither, or only one of the two), do not update. Tell the user the skills are not installed at the expected location (.claude/skills/plugin-guidance/ and .claude/rules/plugin-building-guidance.md) and ask whether they want to install them now. If they confirm, switch to Initialization Mode and run its steps. If they decline, stop without writing anything.
  3. If the skills are installed, run ${CLAUDE_SKILL_DIR}/scripts/init-guidance.sh from the repository root. The script removes each vendored skill directory and re-copies it fresh from the plugin source, so every SKILL.md and every guidance document under plugin-guidance/references/ is replaced with the current version (and any file the plugin has since removed is dropped), then regenerates the rule index at .claude/rules/plugin-building-guidance.md. Capture its output.
  4. Report to the user what was refreshed: the three vendored skills, the total file count, the rule index path, and the paths: globs.
  5. Do not commit. Leave the changes staged for the user to review.

© testdouble, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 52 other files (scripts, references, assets) in han-plugin-builder/skills/guidance of testdouble/han.

  • SKILL.md
  • assets/guidance-portable-SKILL.md
  • assets/rule-index-body.md
  • references/agent-building-guidelines/agent-description-length.md
  • references/agent-building-guidelines/agent-domain-focus.md
  • references/agent-building-guidelines/agent-external-files.md
  • references/agent-building-guidelines/agent-model-selection.md
  • references/agent-building-guidelines/graceful-degradation.md
  • references/agent-building-guidelines/multi-agent-economics.md
  • references/claude-marketplace-and-plugin-configuration/marketplace-json-options.md
  • references/claude-marketplace-and-plugin-configuration/monitors-json-options.md
  • references/claude-marketplace-and-plugin-configuration/plugin-json-options.md
  • references/claude-marketplace-and-plugin-configuration/plugin-naming.md
  • references/claude-marketplace-and-plugin-configuration/themes-json-options.md
  • references/iterative-plugin-development.md
  • references/per-model-authoring.md
  • references/plugin-entity-taxonomy.md
  • … and 36 more

Open the folder on GitHubat commit abba73a

Compare with similar skills

Guidance next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Guidance compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Guidance this skilltestdouble/han279—~1.8kAutomated safety check: PassMIT
Agent Creatorjdforsythe/forge151—~4.5kAutomated safety check: PassMIT
Skill Scoutericrisco/rsc-harness156—~3.9kAutomated safety check: PassMIT
Author Skillericrisco/rsc-harness156—~4.3kAutomated safety check: PassMIT
Microsoft Skill CreatorMicrosoftDocs/mcp1.9k3 repos~2.1kAutomated safety check: PassCC-BY-4.0
Skill Creatorjdforsythe/forge151—~4.1kAutomated safety check: PassMIT

Similar skills

  • Agent Creator

    jdforsythe/forge

    Creates structured agent definitions using the 7-component format grounded in persona science (the alignment-accuracy tradeoff), vocabulary routing, and the MAST failure taxonomy + Forge watchlist.

    151 GitHub stars~4.5k tokensUpdated 3 mo ago
    Agent WorkflowsAuto-check passed

  • Skill Scout

    ericrisco/rsc-harness

    A skill your agent uses when a specialized skill probably exists but is not loaded, when a task feels harder than it should because generic reasoning is doing a domain skill's job, when the work…

    156 GitHub stars~3.9k tokensUpdated yesterday
    Agent WorkflowsAuto-check passed

  • Author Skill

    ericrisco/rsc-harness

    A skill your agent uses when authoring a NEW rsc skill or editing an existing one — scoping it to one job, writing the description that decides whether it ever loads, splitting the body into…

    156 GitHub stars~4.3k tokensUpdated yesterday
    Agent WorkflowsAuto-check passed

  • Microsoft Skill Creator

    MicrosoftDocs/mcp

    Official

    Create agent skills for Microsoft technologies using official documentation.

    1.9k GitHub starsUsed in 3 repos~2.1k tokens
    Agent WorkflowsAuto-check passed

  • Skill Creator

    jdforsythe/forge

    Creates high-quality Claude Code and Cowork skills using evidence-based principles: expert vocabulary payloads for knowledge routing, dual-register descriptions for reliable triggering, named…

    151 GitHub stars~4.1k tokensUpdated 3 mo ago
    Agent WorkflowsAuto-check passed

  • Add Skill

    coralogix/cx-cli

    A skill your agent uses when the user asks to "add a skill", "create a skill", "new skill", "write a skill for", "skill for cx <something", "add a user-facing skill", "create a SKILL.md", "teach an…

    121 GitHub stars~1.8k tokensUpdated 2 days ago
    Agent WorkflowsAuto-check passed

More from testdouble/han

All 54 skills in this repo

  • HTML Summary

    testdouble/han

    Convert a stakeholder summary markdown file into a single self-contained HTML executive report — bottom line and decision asks up front, supporting detail later — styled with a Test Double-derived…

    279 GitHub stars~2.9k tokensUpdated 6 days ago
    Auto-check passed

  • Han Update Documentation

    testdouble/han

    Update Han plugin documentation so every skill, agent, guidance doc, index, and cross-reference is current and accurate.

    279 GitHub stars~3.4k tokensUpdated 6 days ago
    Auto-check passed

  • Han Release

    testdouble/han

    Cut a Han release: update CHANGELOG.md with the changes since the last release, bump and tag every plugin that changed as {plugin-name}--v{version} so a version-constrained dependency can resolve…

    279 GitHub stars~8.6k tokensUpdated 6 days ago
    Auto-check passed

  • Plan Implementation

    testdouble/han

    Builds a feature implementation plan from an existing feature specification (or equivalent context) through a facilitated team conversation.

    279 GitHub stars~9.5k tokensUpdated 6 days ago
    Auto-check passed

  • Refactor

    testdouble/han

    Restructure existing code without changing its behavior, through a test-gated refactoring loop: a named target, a green suite over that target before any edit, a planned sequence of small named…

    279 GitHub stars~3.1k tokensUpdated 6 days ago
    Auto-check passed

  • Update PR Description

    testdouble/han

    Generate a PR description from the current branch's changes against a GitHub PR, using the gh CLI.

    279 GitHub stars~4.7k tokensUpdated 6 days ago
    Auto-check passed

Categories

Questions about Guidance

What does Guidance do?

Authoritative guidance for building Claude Code skills, agents, and plugins, plus init and update steps that install and refresh the plugin-building skills in the current repository. Guidance is an agent skill from testdouble/han. Authoritative guidance for building Claude Code skills, agents, and plugins, plus init and update steps that install and refresh the plugin-building skills in the current repository.

When should I use Guidance?

Guidance fits situations like: you need the rules; best practices for a skill; plugin — designing; checking one against the guidance.

How do I install Guidance in Claude Code?

Run `npx skills add testdouble/han --skill guidance -a claude-code`. Or copy the skill folder (han-plugin-builder/skills/guidance in testdouble/han) into .claude/skills/guidance in your project. Claude Code loads it when a task matches its description.

How do I install Guidance in Codex?

Run `npx skills add testdouble/han --skill guidance -a codex`. Or copy the skill folder (han-plugin-builder/skills/guidance in testdouble/han) into .agents/skills/guidance in your project. Codex loads it when a task matches its description.

Can I use Guidance in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add testdouble/han --skill guidance -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/guidance, .gemini/skills/guidance, .github/skills/guidance and .opencode/skills/guidance in your project.

What does Guidance need to run?

Going by SKILL.md and its folder, Guidance needs the command-line tools its instructions call (bash). Its frontmatter pre-approves these tools: Read, Glob, Grep, Bash(find *), Bash(bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh").

Does Guidance access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Guidance safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Guidance use?

Guidance is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Guidance use?

About 1.8k tokens (SKILL.md is roughly 7.4k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 94k tokens, read only when the agent opens those files.

What are the alternatives to Guidance?

Skills that share tags, products or a category with Guidance: Agent Creator (jdforsythe/forge, 151 stars), Skill Scout (ericrisco/rsc-harness, 156 stars), Author Skill (ericrisco/rsc-harness, 156 stars) and Microsoft Skill Creator (MicrosoftDocs/mcp, 1.9k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Guidance?

testdouble (a GitHub organization) maintains it in testdouble/han, which has 279 GitHub stars. The repository holds 54 skills in this directory. The repository was last updated on October 1, 2026.

Source: testdouble/han on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.