Article Review: Group 6 — Claude Code Skills & Configuration¶

Articles Reviewed¶

Kiro Steering Rules — Hemanth Raju — Persistent project rules in .kiro/steering/ (product.md, tech.md, structure.md)
Claude Code Skills Deep Dive Part 2 — Rick Hightower / Spillwave — Partial Data Automation (PDA), lazy loading, reference files
How Agent Skills Became AI's Most Important Standard — Han HELOIR / AI Advances — Skills as open standard, progressive disclosure architecture
Mastering Agentic Skills — Rick Hightower / Spillwave — Best practices guide: conciseness, degrees of freedom, naming, testing

Key Concepts¶

Kiro Steering Rules vs Our Rules¶

Kiro uses .kiro/steering/ with files like product.md, tech.md, structure.md — persistent rules loaded into AI context. This is conceptually identical to our rules/ directory.

Assessment: We already have a more sophisticated version with 7 rules files covering boundaries, Python standards, events, errors, testing, security, and AI-assisted development. No action needed — Kiro validates our approach.

Progressive Disclosure Architecture (All three skill articles)¶

The core innovation in Skills: three-phase loading.

Startup — Only metadata (name + description) loaded into system prompt. ~50 tokens/skill.
Matching — Agent scans descriptions to find relevant skills for user request.
Loading — Full SKILL.md content loaded on demand. 2,000-5,000 tokens per skill.

This means you can have 100+ skills with only ~5,000 tokens of overhead. Reference files within skills load even more lazily — only when the skill's routing logic requests them.

Partial Data Automation / Lazy Loading (Hightower)¶

Core principle: Skills should be orchestrators that load what they need, not encyclopedias that carry everything.

Three techniques: 1. Reference Files — Skill is a lightweight router (3KB), reference files loaded on demand (8-10KB each). 78% token savings vs monolithic approach. 2. Scripts — Executable code in the skill directory, invoked via Bash tool. 3. AI Reasoning — Let the agent decide what to load based on context.

Reference file organization strategies: - By use case — most intuitive, mirrors user mental model (recommended) - By complexity level — basic → intermediate → advanced (good for educational skills) - By feature area — granular, combinable references (good for complex tools)

Skill Best Practices (Hightower - Mastering Guide)¶

Conciseness is king — Only add context the agent doesn't already have. Every token competes with conversation history.
Degrees of freedom — LOW (exact scripts for fragile ops like DB migrations), MEDIUM (templates for reports), HIGH (heuristics for code review).
Naming — Gerund form: processing-pdfs, analyzing-spreadsheets. Avoid vague names like "helper" or "utils".
Descriptions — What it does AND when to use it. Third person. Include trigger words.
Directory structure — One level deep from SKILL.md. Never more than one link to reach content.
Three scopes — Personal (~/.claude/skills/), Project (.claude/skills/), Plugin (bundled with MCP).

Skills vs MCP (Han HELOIR)¶

MCP = the agent's hands. Connects to external systems (Slack, databases, APIs).
Skills = the agent's training. Teaches workflows, processes, standards.
They're complementary, not competing. Use both together.

Mapping to Our Architecture Repo¶

What We Do Right¶

Rules directory — Our 7 rules files are equivalent to Kiro steering rules, but more sophisticated and domain-specific.
Two working skills — explore-module and write-reference-impl follow the correct structure (SKILL.md with YAML frontmatter).
AI-assisted development rules — Our ai-assisted-development.md covers 7 rules for AI code generation, matching the "architecture first, AI second" philosophy.
Hooks for enforcement — PreCommit boundary check and PostToolUse formatting hooks provide automated guardrails.

Improvements Identified¶

1. Skills Should Use Lazy Loading with Reference Files¶

Our current skills (explore-module, write-reference-impl) contain all instructions inline. They don't leverage lazy loading from reference files.

Current explore-module/SKILL.md: 53 lines, all inline instructions.

Improved pattern: The skill should reference our patterns/ and reference-implementations/ directories lazily:

explore-module/
├── SKILL.md (router — lightweight, ~30 lines)
└── (no local references — reads from patterns/ and reference-implementations/ on demand)

The skill already instructs Claude to read pattern files, but it could be more explicit about the conditional loading pattern — "If NGE Lambda module → read lambda-sqs-integration.md; if ECS module → read ecs-long-running-workloads.md".

2. Skill Descriptions Need "When to Use" Triggers¶

Our current skill descriptions lack trigger words:

# Current
description: Deep architectural exploration of any Nextpoint module

Improved:

description: >
  Deep architectural exploration of any Nextpoint module. Use when
  asked to explore, analyze, understand, or document a module's
  architecture, integration points, or pattern usage.

This helps Claude match the skill to user requests more reliably.

3. Convert Slash Commands to Auto-Triggered Skills Where Appropriate¶

We have 5 slash commands and 2 skills. Some commands would be more useful as auto-triggered skills:

Current Command	Convert to Skill?	Reasoning
`check-boundaries`	No	Explicit action, keep as command
`review-architecture`	Yes	Could auto-trigger on "review" or "check architecture"
`new-adr`	No	Explicit action, keep as command
`new-module`	No	Explicit action, keep as command
`divergence-check`	Yes	Could auto-trigger when touching NGE/Legacy code

4. Add New Skills for Common Workflows¶

Based on the articles' guidance on skill design, potential new skills:

Skill	Description	Degrees of Freedom
`reviewing-pull-request`	Reviews PRs against our patterns, boundaries, and event rules	MEDIUM — templates for what to check, AI judges severity
`debugging-pipeline`	Guides debugging of SQS/Lambda pipeline issues using our exception hierarchy and DLQ patterns	LOW — specific diagnostic steps

5. Skill Naming Should Use Gerund Form¶

Per Hightower's best practices: - explore-module → exploring-module - write-reference-impl → writing-reference-impl

Minor improvement but aligns with emerging convention across Claude Code, Codex, Copilot.

Actionable Changes¶

These go to Claude Code config, not BACKLOG.md:

Change	Target	Priority
Add "when to use" triggers to skill descriptions	`.claude/skills/*/SKILL.md`	HIGH — improves skill matching
Add conditional reference loading to explore-module skill	`.claude/skills/explore-module/SKILL.md`	MEDIUM — reduces context waste
Convert `review-architecture` command to auto-triggered skill	`.claude/skills/reviewing-architecture/SKILL.md`	MEDIUM — auto-triggers on review requests
Update skill names to gerund form	`.claude/skills/`	LOW — convention alignment

Summary¶

Our Claude Code configuration is already more sophisticated than what Kiro Steering Rules describes. The key improvement opportunity is lazy loading with reference files — our skills should be lightweight routers that load from patterns/ and reference-implementations/ on demand, not monolithic instruction sets. Skill descriptions need "when to use" triggers for better auto-matching. Some slash commands (especially review-architecture) would be more useful as auto-triggered skills. The articles validate our overall approach: rules for constraints, skills for workflows, hooks for enforcement.

Ask the Architecture ×

Ask questions about Nextpoint architecture, patterns, rules, or any module. Powered by Claude Opus 4.6.