How do I install the Org Syncer skill?

Run npx skillmds add majiayu000/org-syncer in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Org Syncer skill do?

Sync all projects in an organization with codex repository (with parallel execution). Delegates to fractary CLI for organization-wide sync operations. It is listed under Coding & Dev Tools on SkillMD.

Is Org Syncer safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Org Syncer?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Org Syncer free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Org Syncer?

majiayu000 (@majiayu000) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Org Syncer by majiayu000 — Agent Skill

Name: Org Syncer
Rating: 4.2 (5 reviews)
Author: majiayu000

Your responsibility is to orchestrate synchronization of ALL projects in an organization with the central codex repository by delegating to the cli-helper skill which invokes the fractary codex sync org CLI command.

Architecture (v4.0):

org-syncer skill
  ↓ (delegates to)
cli-helper skill
  ↓ (invokes)
fractary codex sync org
  ↓ (uses)
@fractary/codex SDK (SyncManager, GitHandler, parallel execution)

This provides organization-wide synchronization with:

Automatic repository discovery
Parallel execution across projects
Sequential phase ordering (projects→codex, then codex→projects)
Progress tracking and aggregation
Per-project error handling

All via the TypeScript SDK.

Step 1: Output Start Message

Output:

🎯 STARTING: Organization Sync
Organization: {organization}
Environment: {environment} (branch: {target_branch})
Direction: {direction}
Parallel: {parallel} projects at a time
Dry Run: {yes|no}
───────────────────────────────────────

Step 2: Build CLI Arguments

Construct arguments array from inputs:

args = ["sync", "org"]

// Add organization if provided (otherwise uses config default)
if (organization) {
  args.push("--org", organization)
}

// Add environment or target branch
if (environment) {
  args.push("--environment", environment)
} else if (target_branch) {
  args.push("--branch", target_branch)
}

// Add direction
args.push("--direction", direction)

// Add exclude patterns if provided
if (exclude && exclude.length > 0) {
  exclude.forEach(e => args.push("--exclude", e))
}

// Add parallel setting
if (parallel) {
  args.push("--parallel", parallel)
}

// Add dry-run flag
if (dry_run) {
  args.push("--dry-run")
}

Step 3: Delegate to CLI Helper

USE SKILL: cli-helper Operation: invoke-cli Parameters:

{
  "command": "sync",
  "args": ["org", ...organization, ...environment, ...direction, ...exclude, ...parallel, ...dry_run],
  "parse_output": true
}

The cli-helper will:

Validate CLI installation
Execute: fractary codex sync org [--org <org>] [--environment <env>|--branch <branch>] --direction <direction> [--exclude <pattern>] [--parallel <n>] [--dry-run] --json
Parse JSON output
Return results

The CLI handles:

Repository discovery (excluding codex repo and patterns)
Parallel execution (respecting parallel limit)
Phase sequencing (to-codex, then from-codex)
Progress tracking
Result aggregation
Per-project error handling

Step 4: Process CLI Response

The CLI returns JSON like:

Successful Sync:

{
  "status": "success",
  "operation": "sync-org",
  "organization": "fractary",
  "environment": "test",
  "target_branch": "test",
  "direction": "bidirectional",
  "discovered": {
    "total_repositories": 42,
    "excluded": 3,
    "to_sync": 39
  },
  "phase1_to_codex": {
    "succeeded": 37,
    "failed": 2,
    "files_synced": 1247,
    "files_deleted": 23,
    "failed_projects": [
      {
        "project": "legacy-service",
        "error": "Branch not found"
      }
    ]
  },
  "phase2_from_codex": {
    "succeeded": 38,
    "failed": 1,
    "files_synced": 892,
    "files_deleted": 5,
    "failed_projects": [
      {
        "project": "readonly-repo",
        "error": "Permission denied"
      }
    ]
  },
  "overall": {
    "total_succeeded": 36,
    "total_failed": 3,
    "total_files_synced": 2139,
    "total_files_deleted": 28
  },
  "dry_run": false,
  "duration_seconds": 145.7
}

Dry-Run Preview:

{
  "status": "success",
  "operation": "sync-org",
  "organization": "fractary",
  "environment": "test",
  "direction": "bidirectional",
  "dry_run": true,
  "discovered": {
    "total_repositories": 42,
    "excluded": 3,
    "to_sync": 39,
    "repositories": ["project1", "project2", ...]
  },
  "would_sync": {
    "phase1_to_codex": {
      "projects": 39,
      "estimated_files": 1200,
      "estimated_deletions": 20
    },
    "phase2_from_codex": {
      "projects": 39,
      "estimated_files": 900,
      "estimated_deletions": 5
    }
  },
  "recommendation": "Safe to proceed",
  "estimated_duration_minutes": 3
}

IF status == "success":

Extract sync results from CLI response
Proceed to output formatting
CONTINUE

IF status == "failure":

Extract error message from CLI
Return error to caller
DONE (with error)

Step 5: Output Completion Message

Output:

✅ COMPLETED: Organization Sync
Organization: {organization}
Environment: {environment} (branch: {target_branch})
Direction: {direction}

Discovery:
- Total repositories: {total}
- Excluded: {excluded}
- Synced: {to_sync}

Phase 1 (Projects → Codex):
- Succeeded: {count}
- Failed: {count}
- Files synced: {total}

Phase 2 (Codex → Projects):
- Succeeded: {count}
- Failed: {count}
- Files synced: {total}

Overall:
- Total succeeded: {count}
- Total failed: {count}
- Total files synced: {total}

Duration: {duration}s

───────────────────────────────────────
Next: Review failed projects (if any)

Step 6: Return Results

Return structured JSON with sync results (pass through from CLI).

COMPLETION: Operation complete when sync results shown.

✅ For successful sync:

CLI invoked successfully
All repositories discovered
All requested sync phases completed
Results aggregated across all projects
Per-project status reported
No critical errors occurred

✅ For failed sync:

Error captured from CLI
Error message clear and actionable
Partial results reported (if any)
Failed projects listed
Results returned to caller

✅ For dry-run:

CLI invoked successfully
Preview shown (repositories and estimated files)
Recommendation provided
Estimated duration shown
No actual changes made

✅ In all cases:

No direct script execution
No manual orchestration
CLI handles all operations
Structured response provided

Success Output

{
  "status": "success",
  "operation": "sync-org",
  "organization": "fractary",
  "environment": "test",
  "target_branch": "test",
  "direction": "bidirectional",
  "discovered": {
    "total_repositories": 42,
    "excluded": 3,
    "to_sync": 39
  },
  "phase1_to_codex": {
    "succeeded": 37,
    "failed": 2,
    "files_synced": 1247,
    "files_deleted": 23,
    "failed_projects": [...]
  },
  "phase2_from_codex": {
    "succeeded": 38,
    "failed": 1,
    "files_synced": 892,
    "files_deleted": 5,
    "failed_projects": [...]
  },
  "overall": {
    "total_succeeded": 36,
    "total_failed": 3,
    "total_files_synced": 2139,
    "total_files_deleted": 28
  },
  "dry_run": false,
  "duration_seconds": 145.7
}

Dry-Run Output

{
  "status": "success",
  "operation": "sync-org",
  "organization": "fractary",
  "environment": "test",
  "direction": "bidirectional",
  "dry_run": true,
  "discovered": {
    "total_repositories": 42,
    "excluded": 3,
    "to_sync": 39,
    "repositories": ["project1", "project2", ...]
  },
  "would_sync": {
    "phase1_to_codex": {
      "projects": 39,
      "estimated_files": 1200,
      "estimated_deletions": 20
    },
    "phase2_from_codex": {
      "projects": 39,
      "estimated_files": 900,
      "estimated_deletions": 5
    }
  },
  "recommendation": "Safe to proceed",
  "estimated_duration_minutes": 3
}

Failure Output

{
  "status": "failure",
  "operation": "sync-org",
  "organization": "fractary",
  "environment": "test",
  "error": "Organization access denied",
  "cli_error": {
    "message": "Failed to list repositories in organization",
    "suggested_fixes": [
      "Check GitHub token has 'repo' and 'read:org' permissions",
      "Verify organization name is correct",
      "Test access: gh repo list <org> --limit 1"
    ]
  }
}

Failure: Some Projects Failed

{
  "status": "success",
  "operation": "sync-org",
  "organization": "fractary",
  "environment": "test",
  "direction": "bidirectional",
  "overall": {
    "total_succeeded": 36,
    "total_failed": 3
  },
  "failed_projects": [
    {
      "project": "legacy-service",
      "phase": "to-codex",
      "error": "Branch not found"
    },
    {
      "project": "readonly-repo",
      "phase": "from-codex",
      "error": "Permission denied"
    }
  ],
  "note": "Some projects failed but overall sync succeeded"
}

Failure: CLI Not Available

{
  "status": "failure",
  "operation": "sync-org",
  "error": "CLI not available",
  "suggested_fixes": [
    "Install globally: npm install -g @fractary/cli",
    "Or ensure npx is available"
  ]
}

Organization Access Denied

When CLI reports access issues:

Show which organization failed
Suggest checking token permissions
Recommend testing with gh repo list
Return error

No Repositories Found

When CLI finds no repositories:

Show organization name
Show exclude patterns applied
Suggest checking patterns
Return success with empty results (not an error)

Some Projects Failed

When some projects fail but others succeed:

Report overall success
List failed projects with reasons
Show partial results
Recommend reviewing failures
Return success (partial)

All Projects Failed

When all projects fail:

Show error for each project
Check for common cause (auth, network)
Suggest fixes
Return failure

Parallel Execution Issues

When CLI reports parallel execution errors:

Show which projects were running
Suggest reducing parallel count
Check for API rate limiting
Return error

CLI Not Available

When cli-helper reports CLI unavailable:

Pass through installation instructions
Don't attempt workarounds
Return clear error to caller

CLI Command Failed

When CLI returns error:

Preserve exact error message from CLI
Include suggested fixes if CLI provides them
Show which phase failed (discovery, phase1, phase2)
Include partial results if any phase succeeded
Return structured error

Success:

🎯 STARTING: org-syncer
Organization: {organization}
Environment: {environment} (branch: {target_branch})
Direction: {direction}
Parallel: {parallel} projects at a time
Dry Run: {yes|no}
───────────────────────────────────────

[Sync execution via CLI with progress tracking]

✅ COMPLETED: org-syncer
Organization: {organization}
Environment: {environment}
Direction: {direction}

Discovery:
- Total repositories: {total}
- Excluded: {excluded}
- Synced: {to_sync}

Results:
- Overall succeeded: {count}
- Overall failed: {count}
- Total files synced: {total}
- Duration: {duration}s

Source: CLI (via cli-helper)
───────────────────────────────────────
Next: Review failed projects (if any)

Dry-Run:

🎯 STARTING: org-syncer (DRY-RUN)
Organization: {organization}
Environment: {environment} (branch: {target_branch})
Direction: {direction}
───────────────────────────────────────

[Preview from CLI]

✅ COMPLETED: org-syncer (dry-run)
Would discover: {count} repositories
Would sync:
- Phase 1: {projects} projects, ~{files} files
- Phase 2: {projects} projects, ~{files} files

Estimated duration: {minutes} minutes
Recommendation: {Safe to proceed}

Source: CLI (via cli-helper)
───────────────────────────────────────
Run without --dry-run to execute

Failure:

🎯 STARTING: org-syncer
───────────────────────────────────────

❌ FAILED: org-syncer
Error: {error_message}
Phase: {discovery|phase1|phase2}
Suggested fixes:
- {fix 1}
- {fix 2}
───────────────────────────────────────

Migration from v3.0

v3.0 (manual orchestration):

org-syncer
  ├─ calls repo-discoverer skill
  ├─ orchestrates parallel execution (GNU parallel or bash)
  ├─ calls project-syncer for each project
  ├─ manages phase sequencing
  ├─ aggregates results
  └─ handles per-project errors

v4.0 (CLI delegation):

org-syncer
  └─ delegates to cli-helper
      └─ invokes: fractary codex sync org

Benefits:

~99% code reduction in this skill
No manual orchestration needed
No repository discovery logic
No parallel execution management
TypeScript type safety from SDK
Better progress tracking
Automatic result aggregation
Built-in error handling

CLI Command Used

This skill delegates to:

fractary codex sync org \
  [--org <organization>] \
  [--environment <env>|--branch <branch>] \
  --direction <to-codex|from-codex|bidirectional> \
  [--exclude <pattern>]... \
  [--parallel <number>] \
  [--dry-run] \
  --json

SDK Features Leveraged

Via the CLI, this skill benefits from:

SyncManager.syncOrganization() - Main orchestration
GitHubClient.listRepos() - Repository discovery
ParallelExecutor.run() - Concurrent sync execution
PhaseSequencer.execute() - Sequential phase ordering
ResultAggregator.collect() - Cross-project aggregation
ProgressTracker.update() - Real-time progress
Built-in retry logic
Automatic error recovery

Phase Sequencing

The CLI guarantees proper phase sequencing:

Phase 1 (to-codex) - Parallel within phase:

Discover repositories (excluding codex and patterns)
Sync all projects → codex (parallel, respecting limit)
Wait for all projects to complete
Aggregate results

Phase 2 (from-codex) - Parallel within phase:

Use same repository list
Sync codex → all projects (parallel, respecting limit)
Wait for all projects to complete
Aggregate results

Sequential Execution:

Phase 2 waits for Phase 1 to complete
Ensures codex has all project updates before distributing
Prevents race conditions
Guarantees consistency

Parallel Execution

Default Settings:

Parallel: 5 projects at a time
Prevents API throttling
Balances speed vs resource usage

Adjustable:

{
  "parallel": 10  // Increase for faster sync
}

Limits:

Minimum: 1 (sequential)
Maximum: 10 (prevent overwhelming API)
Recommended: 5-7 for most cases

Error Handling Strategy

Per-Project Errors:

If one project fails, continue with others
Collect all failures for final report
Don't fail entire operation unless ALL projects fail

Common Errors:

Auth issues: Check token permissions
Branch not found: Create branch or update config
Permission denied: Check repository access
Rate limiting: Reduce parallel count

Testing

To test this skill:

# Ensure CLI installed
npm install -g @fractary/cli

# Initialize codex config
fractary codex init --org fractary

# Test dry-run
USE SKILL: org-syncer
Parameters: {
  "organization": "fractary",
  "environment": "test",
  "direction": "bidirectional",
  "parallel": 3,
  "dry_run": true
}

# Test actual sync (careful!)
USE SKILL: org-syncer
Parameters: {
  "organization": "fractary",
  "environment": "test",
  "direction": "to-codex",
  "parallel": 5
}

Troubleshooting

If org sync fails:

Check CLI installation: fractary --version
Check config: .fractary/codex.yaml
Test CLI directly: fractary codex sync org --dry-run
Test repository access: gh repo list <org> --limit 1
Check token permissions: needs 'repo' and 'read:org'
Reduce parallel count if rate limited
Run health check: fractary codex health

Performance Considerations

Large Organizations (100+ repos):

Use dry-run first to estimate duration
Increase parallel count (7-10) if network allows
Consider filtering with exclude patterns
Monitor API rate limits
Run during off-peak hours

Small Organizations (< 20 repos):

Default settings work well
Typically completes in < 2 minutes
No special configuration needed

Org Syncer

File contents

Step 1: Output Start Message

Step 2: Build CLI Arguments

Step 3: Delegate to CLI Helper

Step 4: Process CLI Response

Step 5: Output Completion Message

Step 6: Return Results

Success Output

Dry-Run Output

Failure Output

Failure: Some Projects Failed

Failure: CLI Not Available

Organization Access Denied

No Repositories Found

Some Projects Failed

All Projects Failed

Parallel Execution Issues

CLI Not Available

CLI Command Failed

Migration from v3.0

CLI Command Used

SDK Features Leveraged

Phase Sequencing

Parallel Execution

Error Handling Strategy

Testing

Troubleshooting

Performance Considerations

Frequently asked questions

Org Syncer

File contents

Step 1: Output Start Message

Step 2: Build CLI Arguments

Step 3: Delegate to CLI Helper

Step 4: Process CLI Response

Step 5: Output Completion Message

Step 6: Return Results

Success Output

Dry-Run Output

Failure Output

Failure: Some Projects Failed

Failure: CLI Not Available

Organization Access Denied

No Repositories Found

Some Projects Failed

All Projects Failed

Parallel Execution Issues

CLI Not Available

CLI Command Failed

Migration from v3.0

CLI Command Used

SDK Features Leveraged

Phase Sequencing

Parallel Execution

Error Handling Strategy

Testing

Troubleshooting

Performance Considerations

Related skills

Frequently asked questions

How do I install the Org Syncer skill?

What does the Org Syncer skill do?

Is Org Syncer safe to use?

Which AI agents work with Org Syncer?

Is Org Syncer free to use?

Who published Org Syncer?