The Problem: Missing Affiliate Links

I was creating a custom skill for Claude Code—a mechanism that automatically generates complete articles from draft content. On this particular day, I was working with an article about philosophy and psychology, specifically covering Stoic philosophy and ACT (Acceptance and Commitment Therapy).

When I ran the skill (/draft-to-article), Claude Code generated the article without any issues. Both Japanese and English versions were created, and related affiliate links were embedded.

"Great, it's done."

That's what I thought when I checked the article, and then I noticed.

"Wait, the links for the Stoic philosophy and ACT books aren't included."

The skill had missed books that were explicitly mentioned in the draft. Honestly, I was stuck at this point.

I asked Claude Code:
"Did you find moshimo-card-rJcAE and moshimo-card-YB58h? I wanted those shortcodes added too."

Claude Code immediately searched using Grep.

grep -i "(moshimo-card-rJcAE|moshimo-card-YB58h)" content/affiliates.yaml

"Found them! These books are perfectly relevant."

Claude Code verified the content of the found affiliate links and added them to the appropriate sections of the article:

The article was complete. But I was puzzled.

"Why couldn't it find them on the first run?"

The First Stumble: Skill Not Recognized

Actually, there was another problem before that. Even though I created the skill, I got an Unknown skill: draft-to-article error.

"I created the skill, but I'm getting Unknown skill: draft-to-article."

When I consulted with Claude Code, it first checked my file structure.

ls -la .claude/skills/
# -rw-r--r-- 1 user 197609 4324  Jan 30 11:39 draft-to-article.md

I had placed the file as .claude/skills/draft-to-article.md. However, this was incorrect.

Claude Code launched the claude-code-guide agent to verify the correct format and taught me how to fix it.

The correct structure is:

.claude/
└── skills/
    └── draft-to-article/
        └── SKILL.md

There are three key points:

  1. The file name should be SKILL.md (uppercase)
  2. Create a directory with the skill name
  3. Include YAML frontmatter
---
name: draft-to-article
description: Generate Japanese and English articles from draft and suggest affiliates
user-invocable: true
---

Claude Code created the directory and placed the file in the correct format. Now the skill was recognized.

This was surprisingly crucial. It's written in the documentation, but you don't notice this structure until you actually try it.

Affiliate Search Failure

Once the skill was working, I ran the article generation.

/draft-to-article

The processing flow of the skill I designed was like this:

graph TD
    A[Load Draft] --> B[Determine Category/Tags]
    B --> C[Affiliate Search]
    C --> D[Generate Article]
    D --> E[Complete]

    C --> F{Search<br/>affiliates.yaml}
    F -->|General Keywords| G[coach, counseling]
    F -->|Proper Nouns| H[Stoic philosophy, ACT]

    G --> I[Coachee<br/>Found]
    H --> J[Book Links<br/>Missed]

    style J fill:#f9f,stroke:#333

The skill was designed to search for related affiliate links from affiliates.yaml. At this time, Claude Code executed searches with general keywords like "coach" and "counseling."

As a result, it found the link for Coachee (a career coaching service).

[📦 商品リンク: moshimo-coachee-banner-728x90]

However, it missed the following that were explicitly mentioned in the draft:

Until I checked the article and pointed this out, the skill couldn't detect these.

Root Cause Analysis: Why Did It Miss Them?

I designed this skill myself, so why did it miss them? Looking back, there were three problems.

1. File Size Limitation

affiliates.yaml is a 416KB file. Claude Code's Read tool has a 256KB limit.

In the skill I initially wrote, I tried to read the entire file with the Read tool. But naturally, it errored. So I changed the skill design to a strategy of "just read the first 100 lines."

This was the mistake. The relevant affiliate links were in the latter part of the file.

2. Insufficient Search Strategy

I had instructed the skill to search with general keywords like "coach" and "counseling."

However, looking at the draft content, these proper nouns were explicitly stated:

These books were registered as affiliate links:

[📦 商品リンク: moshimo-card-rJcAE]

[📦 商品リンク: moshimo-card-YB58h]

I should have instructed the skill to search with these terms.

3. Process Ordering Issue

The skill I designed executed the affiliate search "before determining categories and tags." In other words, it was searching with only superficial keywords before deeply reading the entire draft.

Even though the last section "Ancient and New Wisdom" mentioned these topics in detail, I hadn't designed it to read that carefully.

Improvement: Refining SKILL.md

Once I understood the cause, I asked Claude Code:

"What do you think was the reason you couldn't find them? Analyze it and refine the SKILL.md."

Claude Code received my instruction, analyzed the skill's problems, and proposed improvements.

Search Procedure Before Improvement

### Affiliate Analysis
- Search for related links from affiliates.yaml
- Search with general keywords

That was all. It was too abstract, and the judgment criteria during execution were ambiguous.

Search Procedure After Improvement

This is the improved version that Claude Code proposed:

### Affiliate Analysis (Important)

**STEP 1: Extract Proper Nouns and Technical Terms from Draft**
- Book titles, author names, philosophy/theory names
- Service names, product names, brand names
- Technical terms, framework names, tool names
- List the extracted terms

**STEP 2: Search affiliates.yaml with Grep (Required)**
- affiliates.yaml is too large to read entirely with the Read tool
- Always use the Grep tool to search with extracted proper nouns

**STEP 3: Execute Multiple Searches in Parallel**
- Grep search in parallel for each extracted proper noun
- Also search with general keywords
- Try multiple search patterns to prevent oversights

Furthermore, Claude Code added a specific case study:

## Affiliate Search Example

### Case Study: Philosophy/Psychology Article

Proper nouns to extract from draft:
- Stoic philosophy / ストア哲学
- Epictetus / エピクテトス
- Marcus Aurelius / マルクス・アウレリウス
- ACT / Acceptance and Commitment Therapy
- Coaching / コーチング

Search patterns (parallel execution):
- Grep pattern: "(stoic|ストア|epictetus|エピクテトス|marcus)"
- Grep pattern: "(ACT|acceptance|アクセプタンス|commitment|コミットメント)"
- Grep pattern: "(coach|coaching|counseling|コーチ|カウンセリング)"

Expected results:
- moshimo-card-xxxxx: Introduction to Stoic Philosophy
- moshimo-card-yyyyy: Understanding ACT
- moshimo-coachee-banner: Coachee

"OK. I think it's improved."

I approved Claude Code's proposal.

Comparing Search Strategies

Here's a diagram comparing the search strategies before and after improvement:

graph LR
    subgraph Before
    A1[Load Draft] --> B1[Extract General Keywords]
    B1 --> C1[Read tool<br/>First 100 lines]
    C1 --> D1[Execute Search]
    end

    subgraph After
    A2[Load Draft] --> B2[Extract All Proper Nouns]
    B2 --> C2[Grep tool<br/>Full Search]
    C2 --> D2[Parallel Search]
    D2 --> E2[Search in Both Languages]
    end

    style D1 fill:#fcc,stroke:#333
    style E2 fill:#cfc,stroke:#333

The key point is "use Grep instead of Read."

When handling large files, trying to read everything will hit the size limit. But with the Grep tool, you can efficiently search through the entire file.

Lessons Learned: How to Work with Large Files

From this experience, I learned how to work with large files.

1. Tool Selection

Claude Code's tools each have their strengths and weaknesses.

At first, I thought "if I can't read it with Read, I'll just read part of it." But this was wrong. The correct approach is "if you can't read it with Read, search it with Grep."

2. Don't Miss Proper Nouns

It's important to carefully extract not just general keywords, but proper nouns (book names, service names, technical terms).

When reading the draft, I paid attention to general words like "coaching," but I overlooked specific proper nouns like "Stoic philosophy," "Epictetus," and "ACT."

You need to carefully read all sections of the draft, especially the last section.

3. The Importance of Checklists

Following Claude Code's proposal, I added the following checklist to the skill:

With a checklist, you can prevent the same mistake next time. By not just thinking by myself but having Claude Code propose checklist items, I noticed perspectives I had overlooked.

Summary

Through creating a custom Claude Code skill, I learned "how to work with large files."

What was particularly important:

  1. Understand tool characteristics: Read for small files, Grep for large files
  2. Don't miss proper nouns: Extract concrete nouns, not just general keywords
  3. Formalize the process: Ensure reproducibility with checklists and case studies

Analyzing "why did it fail" together with Claude Code when something fails, and improving the skill. I felt anew that this process itself is the essence of engineering.

Claude Code is not just a code generation tool, but also a thinking partner. When I ask "What do you think was the reason you couldn't find it?", it presents perspectives I had overlooked.

Through such dialogue, the skill evolves.

For those who want to learn more about Claude Code

For practical usage and best practices of Claude Code, the following books are helpful:

[📦 商品リンク: moshimo-book-3CCtM]

[📦 商品リンク: moshimo-book-fb94K]