Asset Forge

Asset Forge

Creates assets following system standards. Works for both global (ai-driven-dev-system) and project-specific assets.

Before Creating: Gather Requirements

1. First: Infer from Context

ALWAYS try to infer information from:

• Current conversation history
• User's recent corrections or feedback
• Open files and code context
• Previous agent responses

2. Only Ask if Missing

If you cannot infer the following, then ask:

1. Asset type: skill, rule, or MCP?
2. Purpose: What should this asset do?
3. Scope: Always apply, or file-specific? (for rules)

Principle: The user's time is valuable. Extract maximum info from context before asking questions.

Deciding Where to Create

Decision Flow

1. Is this reusable across multiple projects?

   • YES → Create in ai-driven-dev-system (global) via PR
   • NO → Create in current project's .cursor/

2. Is this specific to this codebase?

   • YES → Create in project's .cursor/skills/ or .cursor/rules/
   • NO → Create in global system

Location Summary

Note: Global assets require PR workflow (use system-gardener). Project assets can be committed directly.

Creating Skills

Directory Structure

skills/[skill-name]/
├── SKILL.md              # Required
├── reference.md          # Optional - detailed docs
├── scripts/              # Optional - utilities
└── tests/                # Required - validation and unit tests

SKILL.md Template

---
name: skill-name
description: Third-person description. Include WHAT it does and WHEN to use it.
---

# Skill Title

Brief overview.

## Before You Begin

Prerequisites or requirements.

## Instructions

Step-by-step guidance.

## Examples

Concrete examples with input/output.

## Checklist

- [ ] Verification items

Frontmatter Rules

• name: max 64 chars, lowercase, hyphens only (e.g., code-review)
• description: max 1024 chars, third person, include trigger terms

Description Best Practices

Write in third person (injected into system prompt):

• ✅ "Reviews code for quality and security issues. Use when..."
• ❌ "I can help you review code"

Include both WHAT and WHEN:

• WHAT: Specific capabilities
• WHEN: Trigger scenarios

Testing Requirements

1. Create tests/ directory.
2. Create [skill-name].test.ts using assets/test.template.ts.
3. If scripts/ exist: Add dedicated unit tests for logic.
4. Run pnpm test to verify compliance.

Creating Rules

Rule File Format

---
description: What the rule does
globs: **/*.ts
alwaysApply: false
---

# Rule Title

Guidelines and examples.

## Correct

\`\`\`typescript
// ✅ GOOD
example
\`\`\`

## Incorrect

\`\`\`typescript
// ❌ BAD
example
\`\`\`

Frontmatter Fields

Configuration Options

• alwaysApply: true → Universal, applies to every session
• globs: "**/*.ts" → Applies when matching files are open

Core Principles

1. Concise: Under 500 lines, only add what agent doesn't know.
2. Progressive disclosure: Essential in main file, details in references.
   • Agent Best Practice: Use npx tsx scripts/extract-frontmatter.ts (or pnpm tsx ...) to inspect skills before reading full files.
3. Concrete examples: Show don't tell.
4. One concern per asset: Split large topics.

CRITICAL: Git Protocol for Global Assets

When creating assets in ai-driven-dev-system:

1. NEVER create directly - Use system-gardener skill
2. Create in feature branch
3. Submit PR for review
4. Wait for human approval

For project assets, commit directly to project repo.

Checklist Before Creating

• Determined scope (global vs project)
• Correct location and format
• Description is specific with trigger terms
• Content under 500 lines
• Includes concrete examples
• Created unit tests in tests/
• Verified with pnpm test
• If global: using PR workflow