docs(agent-development): improve visibility of tools vs allowed-tools disambiguation

[sjnims]

Summary

• Added prominent callout in Overview section for early visibility
• Added contextual note in tools field section with cross-reference to skill-development skill
• Implements Option C from issue (both locations)

Problem

Fixes #24

The important distinction between tools (agents) and allowed-tools (skills) was buried at line ~385 in the Quick Reference section, making it easy to miss when switching between component types.

Solution

Added the disambiguation in two strategic locations:

1. Overview section (line 19) - Early visibility with warning emoji callout
2. tools field section (line 204) - Contextual help when users are configuring tool restrictions, includes cross-reference to skill-development skill

This dual placement ensures users see the warning whether they're scanning the document from the top or jumping directly to the tools field documentation.

Alternatives Considered

• Option A (tools field only): Would miss users scanning from top
• Option B (Overview only): Would miss users jumping to tools field
• Option C (both): Selected - ensures visibility in both contexts

Changes

• plugins/plugin-dev/skills/agent-development/SKILL.md: Added 2 callout boxes

Testing

• Markdownlint passes
• Both callouts render correctly in markdown
• Cross-reference to skill-development skill included

---

🤖 Generated with Claude Code

[claude]

Claude finished @sjnims's task —— View job

---

PR Review: docs(agent-development): improve visibility of tools vs allowed-tools disambiguation

Tasks

• Get PR diff to understand changes
• Read changed file for context
• Run markdownlint on changed file
• Review against plugin component criteria
• Verify documentation improvements
• Post final review summary

---

Summary

✅ Looks good - This PR effectively addresses issue #24 with well-placed documentation improvements.

What's Good

1. Strategic Placement: The dual-location approach (Option C) is the right choice:

   • Early visibility in Overview section (line 19) catches readers scanning from top
   • Contextual placement in tools field section (line 204) helps users actively configuring agents
   • Both locations work together without being redundant

2. Clear Warning Style: The callout boxes use appropriate markdown blockquote syntax with warning emoji (⚠️), making them visually distinct and hard to miss

3. Helpful Cross-Reference: Line 204 includes a reference to the skill-development skill for users needing more detail on skill tool restrictions - this guides users to the right place for related information

4. Concise Messaging: Both callouts are brief and to-the-point, avoiding over-explanation while clearly stating the key difference

5. Markdown Quality: All changes pass markdownlint with no issues ✓

Checklist Verification

• ✅ Skill component: Changes maintain proper YAML frontmatter (untouched), content follows progressive disclosure pattern
• ✅ Markdown linting: Clean - no style issues detected
• ✅ Documentation quality: Improves clarity without adding verbosity
• ✅ Solves stated problem: Directly addresses the issue of buried disambiguation (was at line ~385, now visible at lines 19 and 204)

Minor Observation (not blocking)

The PR description mentions the warning was previously at "line ~385" but I see it at line 403 in the Quick Reference section. This is just a line number discrepancy - the actual change is correct.

---

Recommendation: ✅ Approve and merge

This is a focused, high-impact documentation improvement that follows markdown best practices and solves the stated problem effectively.