best-practice

An Agent Skill that makes Claude do your task the way Anthropic's documentation says to do it — and tell you which rule it applied.

Distilled from the complete Best practices section of the Claude Platform docs plus the agent tooling documentation: use-case guides, prompt engineering, model-specific prompting, evaluation, guardrails, tool use, Agent Skills, and long-running agent architecture.

/best-practice write a classifier prompt for routing support tickets

Rewrite this system prompt по лучшим практикам

Both trigger the skill.

What it does

Given a task, the skill runs a fixed workflow instead of improvising:

1. Classifies the task into one of eight buckets, which determines what it reads.
2. States success criteria — specific, measurable, before any work starts.
3. Chooses model and effort and says why in one line.
4. Constructs the prompt using the documented techniques, then runs a removal pass that strips patterns which hurt on current models.
5. Decides on delegation and, if warranted, writes self-contained subagent prompts with explicit return formats.
6. Executes.
7. Verifies against the criteria from step 2, matching method to stakes.
8. Reports what was applied in four to six lines.

If you hand it an existing prompt, the most useful part of the output is usually the list of things it removed. Instructions written to fight older models — emphatic pressure, forced verification, progress-update scaffolding — now cause the opposite failure.

It also runs in advisory mode. Ask "which model should I use for X" or "is this subagent prompt any good" and it answers with the rule and skips the deliverable.

Installation

Claude Code — project scope

Makes the skill available in one repository, and checked into version control so the team gets it.

git clone https://github.com/starsinc1708/best-practice-skill.git
cd best-practice-skill
./scripts/install.sh --project /path/to/your/repo

Claude Code — personal scope

Available in every session on this machine.

./scripts/install.sh --user

Windows (PowerShell):

git clone https://github.com/starsinc1708/best-practice-skill.git
cd best-practice-skill
.\scripts\install.ps1 -Scope User

Or -Scope Project -Path C:\path\to\your\repo.

Both scripts copy skills/best-practice/ into the right place:

Restart Claude Code, or start a new session, and /best-practice becomes available.

Manual install

Copy skills/best-practice/ into either directory above. That is the whole install — there is nothing to build.

Claude API

Package and upload through the Skills API:

./scripts/package.sh                       # produces dist/best-practice.zip
export ANTHROPIC_API_KEY=sk-ant-...
python scripts/upload_skill.py             # uploads, prints the skill id

Then reference it in a request alongside the code execution tool. The uploader prints the exact snippet with your skill id filled in.

For production, pin the version the uploader reports rather than tracking the latest — a skill update should never silently change deployed behavior.

Repository layout

best-practice-skill/
├── README.md
├── LICENSE
├── CHANGELOG.md
├── skills/
│   └── best-practice/
│       ├── SKILL.md                      # workflow, under 500 lines
│       ├── scripts/
│       │   └── lint_prompt.py            # ships with the skill; run, not read
│       └── reference/
│           ├── model-selection.md        # models, pricing, effort, thinking defaults
│           ├── prompting.md              # techniques, format control, removal list
│           ├── subagent-prompts.md       # delegation rules, template, verifiers
│           ├── tool-use.md               # tool design, context management, safety
│           ├── evaluation.md             # criteria, eval design, grading
│           ├── guardrails.md             # hallucination, injection, leak
│           └── agent-architecture.md     # stop reasons, memory, budgets, long runs
├── evaluations/
│   └── best-practice.evals.json          # 9 cases: trigger, no-trigger, ambiguous
└── scripts/                              # repository tooling, not shipped
    ├── install.sh                        # macOS / Linux installer
    ├── install.ps1                       # Windows installer
    ├── package.sh                        # build the upload zip
    ├── upload_skill.py                   # Skills API upload
    ├── validate_skill.py                 # checks the skill against documented rules
    └── test_lint_prompt.py               # tests for the bundled linter

The prompt linter

The most useful thing the skill does to an existing prompt is delete things. That judgment is now mechanical:

python skills/best-practice/scripts/lint_prompt.py my_prompt.txt

my_prompt.txt:1:1  warning  W001  emphatic pressure causes overtriggering
    | CRITICAL: You MUST always use the search tool before answering.
    why: Current models are highly responsive to the system prompt. Language
         written to force older models now overshoots.
    fix: Use neutral phrasing: "Use this tool when..." instead of
         "CRITICAL: You MUST use this tool".

Twenty rules in three severities. Errors correspond to an HTTP 400 on current models — budget_tokens, extended thinking, sampling parameters, prefilled assistant turns. Warnings still run but produce worse output: emphatic pressure, verification instructions, forced progress scaffolding, instructions to expose reasoning, conservative review filters, untrusted content interpolated into instructions. Info is structural advice — a long prompt with no XML tags, no examples, or a document placeholder with no quote grounding.

Accepts a file, a directory, or stdin. --json for machine-readable output, --fail-on warning to gate CI, --min-severity warning to hide structural advice. Suppress a deliberate exception inline with lint-prompt: ignore=W001.

It ships inside the skill bundle, so an installed skill can run it. A regression test asserts that the linter never flags a prompt this skill itself recommends — if a rule starts firing on one of those, the rule is wrong, not the prompt.

How it is built

The skill follows the authoring rules it teaches. That is deliberate — a skill about best practices that violates the skill-authoring guidance would not be worth much.

Progressive disclosure. Only the name and description sit in context permanently. SKILL.md loads when the skill triggers. The seven reference files load only when the task classification calls for them — reading all seven would defeat the point.

One level deep. Every reference file is linked directly from SKILL.md, never from another reference file. Nested references get partially read, which produces incomplete information.

Under 500 lines. SKILL.md stays inside the documented body budget; everything longer lives in reference/.

Tables of contents. Every reference file over 100 lines opens with one, so a partial read still reveals the full scope of what is available.

No time-sensitive statements. Anything version-dependent lives in an "Old patterns" collapsible block rather than inline conditionals that quietly become wrong.

Third-person description with explicit triggers. The description states what the skill does and when to use it, including the literal phrases users type — in English and Russian.

Run python scripts/validate_skill.py to check all of this mechanically.

Verifying the skill

The evaluations/ directory holds nine cases in three groups:

• Should trigger — direct invocation, an English quality qualifier, a Russian quality qualifier.
• Should not trigger — ordinary task requests with no quality qualifier, where triggering would be overtriggering.
• Ambiguous — cases near the boundary, where either behavior is defensible but the reasoning should be visible.

Each case lists observable expected behaviors rather than a target output, so a human or an LLM grader can mark each one satisfied or not.

There is no built-in runner. Read a case, run the query in a fresh session with the skill installed, and check the behaviors. Test on more than one model tier — what reads as sufficient guidance for the largest model may be too terse for the fastest one.

Scope and honest limits

This skill encodes what Anthropic's documentation states. It does not encode field wisdom that contradicts the documentation, and it does not invent recommendations where the documentation is silent.

Two consequences worth knowing:

It goes stale. Model names, prices, effort levels, and API constraints change. The reference files carry concrete figures because vague ones are useless, and concrete figures date. Check CHANGELOG.md for what the content was current as of, and re-verify anything load-bearing against the live docs before betting on it.

It is opinionated where the docs are opinionated, and only there. Where guidance genuinely differs by model — subagent delegation is the clearest case, where the correct advice inverts between model generations — the reference files say so rather than picking a side.

Contributing

Corrections against the official documentation are the most valuable contribution. If a figure is wrong or a recommendation has changed, open a correction issue — the template asks for the doc URL, which is what makes the fix verifiable.

When changing SKILL.md, keep it under 500 lines and keep references one level deep.

CI runs on every push and pull request. It checks:

• the skill against the documented authoring rules (scripts/validate_skill.py)
• the prompt linter's own test suite, 29 cases including a false-positive guard
• the evaluation cases for structure and group coverage
• that shell scripts are committed with the executable bit set — Windows git does not track it, so this is easy to break
• that no file that must use LF was committed with CRLF
• shellcheck on the shell scripts, plus a real dry run of both installers on Linux and Windows
• that the packaged archive has the single top-level directory the Skills API requires

Run the first check locally before opening a pull request:

python scripts/validate_skill.py

License

MIT. See LICENSE.

This is an independent, unofficial distillation of publicly available documentation. Not affiliated with or endorsed by Anthropic.