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:

Asset type: skill, rule, or MCP?
Purpose: What should this asset do?
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

Is this reusable across multiple projects?
- YES → Create in ai-driven-dev-system (global) via PR
- NO → Create in current project's .cursor/
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

Create tests/ directory.
Create [skill-name].test.ts using assets/test.template.ts.
If scripts/ exist: Add dedicated unit tests for logic.
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

Concise: Under 500 lines, only add what agent doesn't know.
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.
Concrete examples: Show don't tell.
One concern per asset: Split large topics.

CRITICAL: Git Protocol for Global Assets

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

NEVER create directly - Use system-gardener skill
Create in feature branch
Submit PR for review
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