gilles/claude-code-best-practice
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

tips/claude-thariq: fix off-by-one cascade in thariq-26-3-17 image refs

Browse Source 
Every image reference from section 6 (Code Quality & Review) through
the conclusion pointed to the wrong file (one number too high). Section
6 showed section 7's content, and so on through section 9 and all the
Tips subsections. The Conclusion reference pointed at a non-existent
28.png.

Shifting references 10–28 down to 9–27 restores the 1:1 mapping
between section content and image content. 9.png (which was orphaned)
is now used, and the broken 28.png link is resolved — the directory
only ever had 27 files.

Verified by visually inspecting 9.png/10.png/11.png/12.png/13.png/14.png
and confirming each shows the section content the doc claims.
This commit is contained in:
Shayan Rais
2026-04-19 13:36:24 +05:00
parent d3b61467c4
commit b6970ced5f
1 changed files with 19 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tips/claude-thariq-tips-17-mar-26.md
+19 -19
View File
@@ -91,7 +91,7 @@ Skills that enforce code quality inside of your org and help review code. These
**Examples:** adversarial-review, code-style, testing-practices **Examples:** adversarial-review, code-style, testing-practices
<a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/10.png" alt="Code Quality & Review" width="50%" /></a> <a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/9.png" alt="Code Quality & Review" width="50%" /></a>
--- ---
@@ -101,7 +101,7 @@ Skills that help you fetch, push, and deploy code inside of your codebase. These
**Examples:** babysit-pr, deploy-\<service\>, cherry-pick-prod **Examples:** babysit-pr, deploy-\<service\>, cherry-pick-prod
<a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/11.png" alt="CI/CD & Deployment" width="50%" /></a> <a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/10.png" alt="CI/CD & Deployment" width="50%" /></a>
--- ---
@@ -111,7 +111,7 @@ Skills that take a symptom (such as a Slack thread, alert, or error signature),
**Examples:** \<service\>-debugging, oncall-runner, log-correlator **Examples:** \<service\>-debugging, oncall-runner, log-correlator
<a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/12.png" alt="Runbooks" width="50%" /></a> <a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/11.png" alt="Runbooks" width="50%" /></a>
--- ---
@@ -121,7 +121,7 @@ Skills that perform routine maintenance and operational procedures — some of w
**Examples:** \<resource\>-orphans, dependency-management, cost-investigation **Examples:** \<resource\>-orphans, dependency-management, cost-investigation
<a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/13.png" alt="Infrastructure Operations" width="50%" /></a> <a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/12.png" alt="Infrastructure Operations" width="50%" /></a>
--- ---
@@ -129,7 +129,7 @@ Skills that perform routine maintenance and operational procedures — some of w
9 best practices for writing effective skills, plus guidance on distribution and measurement. 9 best practices for writing effective skills, plus guidance on distribution and measurement.
<a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/14.png" alt="Tips for Making Skills grid" width="50%" /></a> <a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/13.png" alt="Tips for Making Skills grid" width="50%" /></a>
--- ---
@@ -137,7 +137,7 @@ Skills that perform routine maintenance and operational procedures — some of w
Claude Code knows a lot about your codebase, and Claude knows a lot about coding, including many default opinions. If you're publishing a skill that is primarily about knowledge, try to focus on information that pushes Claude out of its normal way of thinking. The frontend design skill is a great example — it was built by iterating with customers on improving Claude's design taste, avoiding classic patterns like the Inter font and purple gradients. Claude Code knows a lot about your codebase, and Claude knows a lot about coding, including many default opinions. If you're publishing a skill that is primarily about knowledge, try to focus on information that pushes Claude out of its normal way of thinking. The frontend design skill is a great example — it was built by iterating with customers on improving Claude's design taste, avoiding classic patterns like the Inter font and purple gradients.
<a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/15.png" alt="Don't State the Obvious" width="50%" /></a> <a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/14.png" alt="Don't State the Obvious" width="50%" /></a>
--- ---
@@ -145,7 +145,7 @@ Claude Code knows a lot about your codebase, and Claude knows a lot about coding
The highest-signal content in any skill is the Gotchas section. These sections should be built up from common failure points that Claude runs into when using your skill. Ideally, you will update your skill over time to capture these gotchas. The highest-signal content in any skill is the Gotchas section. These sections should be built up from common failure points that Claude runs into when using your skill. Ideally, you will update your skill over time to capture these gotchas.
<a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/16.png" alt="Build a Gotchas Section" width="50%" /></a> <a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/15.png" alt="Build a Gotchas Section" width="50%" /></a>
--- ---
@@ -153,7 +153,7 @@ The highest-signal content in any skill is the Gotchas section. These sections s
A skill is a folder, not just a markdown file. You should think of the entire file system as a form of context engineering and progressive disclosure. Tell Claude what files are in your skill, and it will read them at appropriate times. The simplest form is to point to other markdown files — e.g., split detailed function signatures and usage examples into `references/api.md`. You can have folders of references, scripts, examples, etc. A skill is a folder, not just a markdown file. You should think of the entire file system as a form of context engineering and progressive disclosure. Tell Claude what files are in your skill, and it will read them at appropriate times. The simplest form is to point to other markdown files — e.g., split detailed function signatures and usage examples into `references/api.md`. You can have folders of references, scripts, examples, etc.
<a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/17.png" alt="Progressive Disclosure" width="50%" /></a> <a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/16.png" alt="Progressive Disclosure" width="50%" /></a>
--- ---
@@ -161,7 +161,7 @@ A skill is a folder, not just a markdown file. You should think of the entire fi
Claude will generally try to stick to your instructions, and because skills are so reusable you'll want to be careful of being too specific. Give Claude the information it needs, but give it the flexibility to adapt to the situation. Instead of prescriptive step-by-step instructions, give the goal and constraints. Claude will generally try to stick to your instructions, and because skills are so reusable you'll want to be careful of being too specific. Give Claude the information it needs, but give it the flexibility to adapt to the situation. Instead of prescriptive step-by-step instructions, give the goal and constraints.
<a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/18.png" alt="Avoid Railroading Claude" width="50%" /></a> <a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/17.png" alt="Avoid Railroading Claude" width="50%" /></a>
--- ---
@@ -169,7 +169,7 @@ Claude will generally try to stick to your instructions, and because skills are
Some skills may need to be set up with context from the user. A good pattern is to store this setup information in a `config.json` file in the skill directory. If the config is not set up, the agent can then ask the user for information. You can instruct Claude to use the AskUserQuestion tool for structured, multiple choice questions. Some skills may need to be set up with context from the user. A good pattern is to store this setup information in a `config.json` file in the skill directory. If the config is not set up, the agent can then ask the user for information. You can instruct Claude to use the AskUserQuestion tool for structured, multiple choice questions.
<a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/19.png" alt="Think through the Setup" width="50%" /></a> <a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/18.png" alt="Think through the Setup" width="50%" /></a>
--- ---
@@ -177,7 +177,7 @@ Some skills may need to be set up with context from the user. A good pattern is
When Claude Code starts a session, it builds a listing of every available skill with its description. This listing is what Claude scans to decide "is there a skill for this request?" Which means the description field is not a summary — it's a description of **when to trigger** this skill. Write it for the model. When Claude Code starts a session, it builds a listing of every available skill with its description. This listing is what Claude scans to decide "is there a skill for this request?" Which means the description field is not a summary — it's a description of **when to trigger** this skill. Write it for the model.
<a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/20.png" alt="Description = Trigger" width="50%" /></a> <a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/19.png" alt="Description = Trigger" width="50%" /></a>
--- ---
@@ -185,7 +185,7 @@ When Claude Code starts a session, it builds a listing of every available skill
Some skills can include a form of memory by storing data within them. You could store data in anything as simple as an append-only text log file or JSON files, or as complicated as a SQLite database. Data stored in the skill directory may be deleted when you upgrade the skill, so use `${CLAUDE_PLUGIN_DATA}` as a stable folder per plugin to store data in. Some skills can include a form of memory by storing data within them. You could store data in anything as simple as an append-only text log file or JSON files, or as complicated as a SQLite database. Data stored in the skill directory may be deleted when you upgrade the skill, so use `${CLAUDE_PLUGIN_DATA}` as a stable folder per plugin to store data in.
<a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/21.png" alt="Memory & Storing Data" width="50%" /></a> <a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/20.png" alt="Memory & Storing Data" width="50%" /></a>
--- ---
@@ -193,7 +193,7 @@ Some skills can include a form of memory by storing data within them. You could
One of the most powerful tools you can give Claude is code. Giving Claude scripts and libraries lets Claude spend its turns on composition, deciding what to do next rather than reconstructing boilerplate. Claude can then generate scripts on the fly to compose this functionality for more advanced analysis. One of the most powerful tools you can give Claude is code. Giving Claude scripts and libraries lets Claude spend its turns on composition, deciding what to do next rather than reconstructing boilerplate. Claude can then generate scripts on the fly to compose this functionality for more advanced analysis.
<a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/22.png" alt="Store Scripts & Generate Code" width="50%" /></a> <a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/21.png" alt="Store Scripts & Generate Code" width="50%" /></a>
--- ---
@@ -205,7 +205,7 @@ Skills can include hooks that are only activated when the skill is called, and l
- `/careful` — blocks rm -rf, DROP TABLE, force-push, kubectl delete via PreToolUse matcher on Bash - `/careful` — blocks rm -rf, DROP TABLE, force-push, kubectl delete via PreToolUse matcher on Bash
- `/freeze` — blocks any Edit/Write that's not in a specific directory - `/freeze` — blocks any Edit/Write that's not in a specific directory
<a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/23.png" alt="On Demand Hooks" width="50%" /></a> <a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/22.png" alt="On Demand Hooks" width="50%" /></a>
--- ---
@@ -217,7 +217,7 @@ Two ways to share skills with your team:
Every skill that is checked in also adds a little bit to the context of the model. As you scale, an internal plugin marketplace allows you to distribute skills and let your team decide which ones to install. Every skill that is checked in also adds a little bit to the context of the model. As you scale, an internal plugin marketplace allows you to distribute skills and let your team decide which ones to install.
<a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/24.png" alt="Distributing Skills" width="50%" /></a> <a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/23.png" alt="Distributing Skills" width="50%" /></a>
--- ---
@@ -225,7 +225,7 @@ Every skill that is checked in also adds a little bit to the context of the mode
There isn't a centralized team that decides which skills go into a marketplace. Instead, try and find the most useful skills organically. Upload to a sandbox folder in GitHub and point people to it in Slack or other forums. Once a skill has gotten traction (which is up to the skill owner to decide), they can put in a PR to move it into the marketplace. Curation before release is important to avoid redundant skills. There isn't a centralized team that decides which skills go into a marketplace. Instead, try and find the most useful skills organically. Upload to a sandbox folder in GitHub and point people to it in Slack or other forums. Once a skill has gotten traction (which is up to the skill owner to decide), they can put in a PR to move it into the marketplace. Curation before release is important to avoid redundant skills.
<a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/25.png" alt="Managing a Marketplace" width="50%" /></a> <a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/24.png" alt="Managing a Marketplace" width="50%" /></a>
--- ---
@@ -233,7 +233,7 @@ There isn't a centralized team that decides which skills go into a marketplace.
You may want to have skills that depend on each other. For example, a file upload skill that uploads a file, and a CSV generation skill that makes a CSV and uploads it. This sort of dependency management is not natively built into marketplaces or skills yet, but you can just reference other skills by name, and the model will invoke them if they are installed. You may want to have skills that depend on each other. For example, a file upload skill that uploads a file, and a CSV generation skill that makes a CSV and uploads it. This sort of dependency management is not natively built into marketplaces or skills yet, but you can just reference other skills by name, and the model will invoke them if they are installed.
<a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/26.png" alt="Composing Skills" width="50%" /></a> <a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/25.png" alt="Composing Skills" width="50%" /></a>
--- ---
@@ -241,7 +241,7 @@ You may want to have skills that depend on each other. For example, a file uploa
To understand how a skill is doing, use a PreToolUse hook that lets you log skill usage within the company. This means you can find skills that are popular or are undertriggering compared to expectations. To understand how a skill is doing, use a PreToolUse hook that lets you log skill usage within the company. This means you can find skills that are popular or are undertriggering compared to expectations.
<a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/27.png" alt="Measuring Skills" width="50%" /></a> <a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/26.png" alt="Measuring Skills" width="50%" /></a>
--- ---
@@ -249,7 +249,7 @@ To understand how a skill is doing, use a PreToolUse hook that lets you log skil
Skills are incredibly powerful, flexible tools for agents, but it's still early and we're all figuring out how to use them best. Think of this more as a grab bag of useful tips that we've seen work than a definitive guide. The best way to understand skills is to get started, experiment, and see what works for you. Most of ours began as a few lines and a single gotcha, and got better because people kept adding to them as Claude hit new edge cases. Skills are incredibly powerful, flexible tools for agents, but it's still early and we're all figuring out how to use them best. Think of this more as a grab bag of useful tips that we've seen work than a definitive guide. The best way to understand skills is to get started, experiment, and see what works for you. Most of ours began as a few lines and a single gotcha, and got better because people kept adding to them as Claude hit new edge cases.
<a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/28.png" alt="Conclusion" width="50%" /></a> <a href="https://x.com/trq212/status/2033949937936085378"><img src="assets/thariq-26-3-17/27.png" alt="Conclusion" width="50%" /></a>
--- ---