Where Agent Instructions and Skill Definitions Are Stored in the AI Website Cloner Template

Agent instructions and skill definitions are stored as plain markdown files in the AGENTS.md file and platform-specific SKILL.md files across .github/, .claude/, and .codex/ directories, synchronized by scripts/sync-agent-rules.sh.

The JCodesMore/ai-website-cloner-template repository separates AI configuration into two distinct artifact types: high-level agent instructions that govern behavior, and concrete skill definitions that define executable commands. Understanding where these files live and how they interact is essential for customizing the cloning pipeline or adding new capabilities. This guide maps the exact storage locations and loading mechanisms used by the runtime.

Agent Instructions Storage Location

Central Configuration in AGENTS.md

The primary source for agent instructions is the AGENTS.md file at the repository root. This human-readable markdown document defines the overall behavior, rules, and high-level workflow for the cloning agents, including the pipeline stages (recon, foundation, component spec, dispatch, merge, QA).

Platform-Specific Rule Synchronization

Raw instructions from AGENTS.md are not consumed directly by the runtime. Instead, the scripts/sync-agent-rules.sh helper script copies these markdown rules into platform-specific instruction files. When executed, this script generates copies in directories like .claude/, .cursor/, and .continue/, ensuring each AI platform receives properly formatted rules.

When a new clone job starts, the CLI loads rules from these generated files rather than the source document. The orchestration layer also consults these rules to determine which worktree or branch each builder agent should run in.

Skill Definitions Storage Location

Canonical Skill Files

Skill definitions describe concrete capabilities that users can invoke, such as the clone-website skill. Each skill bundles a name, description, argument hints, and a markdown body containing the step-by-step workflow. The canonical definition resides in .github/skills/clone-website/SKILL.md, which serves as the primary reference for GitHub-based agents.

Platform-Specific Skill Variants

The repository maintains platform-specific copies to handle formatting differences between AI providers. The Claude-compatible version lives in .claude/skills/clone-website/SKILL.md, while the Codex-compatible variant is stored in .codex/skills/clone-website/SKILL.md.

The CLI discovers available skills by scanning the */skills/*/SKILL.md glob pattern. When a user triggers a command like /clone-website <url>, the runtime parses the matching SKILL.md file and feeds its body to the appropriate agent.

Runtime Loading Patterns

The system loads these artifacts at runtime using straightforward file system operations. For agent rules, the runtime resolves platform-specific paths generated by the sync script.

// Example: loading an agent rule at runtime (Node)
import { readFileSync } from 'fs';
import path from 'path';

// Resolve the rule generated for the current platform (e.g., Claude)
const rulePath = path.join(
  __dirname,
  '..',
  '.claude',
  'agents',
  'nextjs-agent-rules.md'   // produced by scripts/sync-agent-rules.sh
);
const agentRules = readFileSync(rulePath, 'utf-8');
console.log(agentRules);

For skills, the runtime dynamically discovers definitions by globbing the skills directory.

// Example: discovering a skill to invoke
import { globSync } from 'glob';

// Find all skill definition files
const skillFiles = globSync('*/skills/**/SKILL.md', { cwd: process.cwd() });
for (const file of skillFiles) {
  const content = readFileSync(file, 'utf-8');
  if (content.includes('name: clone-website')) {
    // Parse the front‑matter and markdown body
    console.log(`Found clone-website skill at ${file}`);
  }
}

CI Automation and Version Control

The .github/workflows/ci.yml pipeline ensures consistency across platform-specific files. After any change to AGENTS.md, the CI runs scripts/sync-agent-rules.sh automatically to regenerate the .claude/, .cursor/, and .continue/ instruction files. This guarantees that the generated rule files stay in sync with the central source.

Skill files require no build step; the runtime reads them directly from their respective directories. This architecture keeps the project agnostic to the underlying LLM provider while maintaining strict, version-controlled workflows.

Summary

• Agent instructions originate in AGENTS.md and propagate to platform directories via scripts/sync-agent-rules.sh.
• Skill definitions reside in SKILL.md files within .github/skills/, .claude/skills/, and .codex/skills/ directories.
• The runtime discovers skills using the */skills/*/SKILL.md glob pattern and loads agent rules from generated platform-specific files.
• .github/workflows/ci.yml automates synchronization to prevent drift between the central configuration and platform-specific copies.

Frequently Asked Questions

What is the difference between agent instructions and skill definitions?

Agent instructions define the overall behavior and workflow rules that govern how the AI operates across all tasks, stored in AGENTS.md. Skill definitions are specific executable commands that users can trigger, such as clone-website, each with its own step-by-step logic stored in individual SKILL.md files.

How do I add a new skill to the AI Website Cloner?

Create a new directory under .github/skills/{skill-name}/ containing a SKILL.md file with the skill metadata and workflow steps. Optionally, create platform-specific copies in .claude/skills/{skill-name}/ and .codex/skills/{skill-name}/ to optimize formatting for different AI providers. The CLI will automatically discover the new skill via the */skills/*/SKILL.md glob pattern.

Why are the configurations stored as markdown files rather than JSON or YAML?

Markdown provides human-readable formatting that doubles as structured content for LLM consumption. This approach allows developers to edit complex instructions using familiar syntax while the runtime parses the markdown body directly, eliminating the need for compilation or complex build steps.

How does the CI pipeline keep platform-specific files synchronized?

The .github/workflows/ci.yml runs scripts/sync-agent-rules.sh automatically after any change to AGENTS.md. This script copies the central markdown specification into platform-specific directories like .claude/ and .cursor/, ensuring that generated instruction files remain consistent with the source of truth.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}