ambient-code · jwm4 · May 28, 2026 · May 28, 2026 · May 28, 2026 · May 28, 2026
diff --git a/.agentready-config.example.yaml b/.agentready-config.example.yaml
@@ -14,7 +14,7 @@ weights:
   # Tier 1 (Essential) - 50% total
   test_execution: 0.10               # Test execution & coverage (highest priority)
   type_annotations: 0.08            # Type hints in code
-  claude_md_file: 0.07              # CLAUDE.md/AGENTS.md configuration files
+  agent_instructions: 0.07           # Agent instruction files (CLAUDE.md/AGENTS.md)
   ci_quality_gates: 0.05            # CI quality gates (lint + type-check + tests)
   single_file_verification: 0.05    # Single-file lint/type-check commands
   readme_structure: 0.05            # README structure and content
@@ -87,5 +87,5 @@ report_theme: default
 # Other attributes are automatically rescaled to maintain sum of 1.0
 #
 # weights:
-#   claude_md_file: 0.15
+#   agent_instructions: 0.15
 #   test_execution: 0.15
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -8,7 +8,7 @@ Assess repositories against evidence-based attributes for AI-assisted developmen
 |------|-------|
 | **Python** | >=3.12 |
 | **Entry Point** | `agentready.cli.main:cli` (or `python -m agentready`) |
-| **Self-Score** | 80.0/100 (Silver) |
+| **Self-Score** | 74.5/100 (Silver) |
 | **Test Coverage** | 37% (target: >80%) |
 
 ## Commands
@@ -69,7 +69,7 @@ src/agentready/
 4. Add tests in `tests/unit/test_assessors_*.py`
 
 **Reference implementations**:
-- Simple: `CLAUDEmdAssessor` at `assessors/documentation.py`
+- Simple: `AgentInstructionsAssessor` at `assessors/documentation.py`
 - Complex: `TypeAnnotationsAssessor` at `assessors/code_quality.py`
 - Conditional: `ContainerSetupAssessor` at `assessors/containers.py`
 

diff --git a/README.md b/README.md
@@ -174,7 +174,7 @@ Create `.agentready-config.yaml` to customize weights:
 
 ```yaml
 weights:
-  claude_md_file: 0.15      # Increase importance (default: 0.07)
+  agent_instructions: 0.15   # Increase importance (default: 0.07)
   test_execution: 0.15      # Increase importance (default: 0.10)
   conventional_commits: 0.01  # Decrease importance (default: 0.03)
   # Other attributes use defaults, rescaled to sum to 1.0

diff --git a/docs/api-reference.md b/docs/api-reference.md
@@ -81,7 +81,7 @@ from agentready.models import Attribute
 class Attribute:
     """Immutable attribute definition."""
 
-    id: str              # Unique identifier (e.g., "claude_md_file")
+    id: str              # Unique identifier (e.g., "agent_instructions")
     name: str            # Display name
     tier: int            # Tier 1-4 (1 = most important)
     weight: float        # Weight in scoring (0.0-1.0, sum to 1.0 across all)
@@ -108,12 +108,12 @@ Attribute(
 
 ```python
 attribute = Attribute(
-    id="claude_md_file",
-    name="CLAUDE.md File",
+    id="agent_instructions",
+    name="Agent Instruction Files",
     tier=1,
     weight=0.10,
     category="Context Window Optimization",
-    description="CLAUDE.md file at repository root",
+    description="Agent instruction file (CLAUDE.md, AGENTS.md, or .claude/CLAUDE.md)",
     rationale="Provides immediate project context to AI agents"
 )
 ```
@@ -1053,7 +1053,7 @@ from agentready.models import Repository
 
 # Override default weights programmatically
 custom_weights = {
-    "claude_md_file": 0.15,      # Increase from 0.10
+    "agent_instructions": 0.15,   # Increase from 0.10
     "readme_structure": 0.12,    # Increase from 0.10
     "type_annotations": 0.08,    # Decrease from 0.10
     # ... other attributes

diff --git a/docs/attributes.md b/docs/attributes.md
@@ -3,7 +3,7 @@ layout: page
 title: Attributes Reference
 ---
 
-Complete reference for all 28 agent-ready attributes assessed by AgentReady.
+Complete reference for all 25 agent-ready attributes assessed by AgentReady.
 
 <div class="feature" style="background-color: #dbeafe; border-left: 4px solid #2563eb; padding: 1rem; margin: 1rem 0;">
   <h3 style="margin-top: 0;">🤖 Bootstrap Automation</h3>
@@ -51,9 +51,9 @@ Missing a Tier 1 attribute (up to 12% weight) has up to 12x the score impact of
 
 *Fundamentals that enable basic AI agent functionality — 55% of total score*
 
-### 1. CLAUDE.md Configuration File
+### 1. Agent Instruction Files
 
-**ID**: `claude_md_file`
+**ID**: `agent_instructions`
 **Weight**: 7%
 **Category**: Context Window Optimization
 **Status**: ✅ Implemented
@@ -68,12 +68,21 @@ Claude Code reads `CLAUDE.md` at the start of every session. Without it, agents
 
 #### Measurable Criteria
 
-**Passes if**:
+**Two-phase scoring:**
+
+1. **Presence (up to 70 points)**: File exists at `CLAUDE.md`, `.claude/CLAUDE.md`, or `AGENTS.md` with at least 50 bytes (direct, symlink, or `@` file reference). `AGENTS.md` is a fully equivalent alternative.
+
+2. **Length (up to 30 points)**: Context file line count determines length credit:
+
+| Lines | Length Credit | Total Score |
+|-------|-------------|-------------|
+| <=150 | 30 (full) | 100 |
+| 151-300 | 15 (partial) | 85 |
+| >300 | 0 (none) | 70 |
 
-- File exists at `CLAUDE.md`, `.claude/CLAUDE.md`, or `AGENTS.md` (all treated as fully equivalent)
-- File is at least 50 bytes, OR is a valid symlink, OR contains an `@` file reference
+For symlinks and `@` references, line count is measured on the resolved target file.
 
-`AGENTS.md` is a fully equivalent alternative and scores identically to `CLAUDE.md`.
+**Agent access documentation** (substantiating evidence): The assessor also checks for agent access sections documenting platform, CLI tool, and authentication requirements. This is recorded as evidence but does not affect the score.
 
 #### Example: Good CLAUDE.md
 
@@ -1019,7 +1028,7 @@ setup:
 **Inline Documentation** (`inline_documentation`, 3%) — Comments and docstrings for functions, classes, modules
 **File Size Limits** (`file_size_limits`, 3%) — Files under threshold to keep context manageable
 **Separation of Concerns** (`separation_of_concerns`, 3%) — Clean module boundaries and single-responsibility
-**Pattern References** (`pattern_references`, 3%) — Documented patterns for common changes
+**Pattern References** (`pattern_references`, 3%) — Documented patterns for common changes. Skills scoring is tiered: 1-2 SKILL.md files earn partial credit (30 pts), 3+ earn full credit (60 pts). Context files >150 lines without skills trigger a warning
 **Design Intent Documentation** (`design_intent`, 3%) — Preconditions, invariants, and rationale in design docs (moved from T3)
 
 *Full details for each attribute available in the [research document](https://github.com/ambient-code/agentready/blob/main/RESEARCH_REPORT.md).*

diff --git a/docs/developer-guide.md b/docs/developer-guide.md
@@ -249,7 +249,7 @@ Orchestration and core algorithms:
 Strategy pattern implementations for each attribute:
 
 - **BaseAssessor**: Abstract base class defining interface
-- Concrete assessors: `CLAUDEmdAssessor`, `READMEAssessor`, etc.
+- Concrete assessors: `AgentInstructionsAssessor`, `READMEAssessor`, etc.
 
 **Design Principles**:
 

diff --git a/docs/user-guide.md b/docs/user-guide.md
@@ -291,7 +291,7 @@ Create `.agentready-config.yaml` to customize:
 ```yaml
 # Custom attribute weights (must sum to 1.0)
 weights:
-  claude_md_file: 0.15      # Increase from default 0.10
+  agent_instructions: 0.15   # Increase from default 0.10
   readme_structure: 0.12
   type_annotations: 0.08
 

diff --git a/experiments/configs/claude-md.yaml b/experiments/configs/claude-md.yaml
@@ -4,4 +4,4 @@ agentready_changes:
   align:
     enabled: true
     attributes:
-      - claude_md_file
+      - agent_instructions
diff --git a/experiments/configs/tier1.yaml b/experiments/configs/tier1.yaml
@@ -4,7 +4,7 @@ agentready_changes:
   align:
     enabled: true
     attributes:
-      - claude_md_file
+      - agent_instructions
       - readme_structure
       - type_annotations
       - standard_layout

diff --git a/scripts/generate_slides.py b/scripts/generate_slides.py
@@ -146,7 +146,7 @@ def create_presentation_slides() -> List[Dict[str, str]]:
 .agentready/eval_harness/
 ├── baseline/summary.json
 ├── assessors/
-│   └── claude_md_file/
+│   └── agent_instructions/
 │       ├── impact.json ← Delta, p-value, effect size
 │       └── run_*.json
 └── summary.json ← Ranked results
@@ -192,7 +192,7 @@ def create_presentation_slides() -> List[Dict[str, str]]:
 
 # 2. Test single assessor
 agentready eval-harness test-assessor \\
-  --assessor-id claude_md_file --iterations 3
+  --assessor-id agent_instructions --iterations 3
 
 # 3. Aggregate all results
 agentready eval-harness summarize

diff --git a/src/agentready/assessors/__init__.py b/src/agentready/assessors/__init__.py
@@ -20,8 +20,8 @@
     DbtProjectStructureAssessor,
 )
 from .documentation import (
+    AgentInstructionsAssessor,
     ArchitectureDecisionsAssessor,
-    CLAUDEmdAssessor,
     InlineDocumentationAssessor,
     OpenAPISpecsAssessor,
     READMEAssessor,
@@ -69,7 +69,7 @@ def create_all_assessors() -> list[BaseAssessor]:
         # Tier 1 Essential — 59% total (9 attributes)
         TestExecutionAssessor(),  # 12%
         TypeAnnotationsAssessor(),  # 10%
-        CLAUDEmdAssessor(),  # 7%
+        AgentInstructionsAssessor(),  # 7%
         CIQualityGatesAssessor(),  # 5%
         SingleFileVerificationAssessor(),  # 5%
         READMEAssessor(),  # 5%

diff --git a/src/agentready/assessors/base.py b/src/agentready/assessors/base.py
@@ -20,7 +20,7 @@ class BaseAssessor(ABC):
     @property
     @abstractmethod
     def attribute_id(self) -> str:
-        """Unique attribute identifier (e.g., 'claude_md_file').
+        """Unique attribute identifier (e.g., 'agent_instructions').
 
         Must be lowercase snake_case matching the attribute ID in the
         research report and default-weights.yaml.